5 Commits

Author SHA1 Message Date
32c2cea0f9 Remove future tense from man pages
Remove all will, would, could, should and use present tense.

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2023-05-16 15:10:33 -04:00
7665bbc127 Remove 'you' from man pages
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
2022-12-07 09:29:29 -05:00
c9c2f644da markdown-preprocess: cross-reference where opts are used
In each options/foo.md, keep a list of where the option is used.
This will be valuable to anyone making future edits, and to
those reviewing those edits.

This may be a controversial commit, because those crossref lists
are autogenerated as a side effect of the script that reads them.
It definitely violates POLA. And one day, some kind person will
reconcile (e.g.) --label, using it in more man pages, and maybe
forget to git-commit the rewritten file, and CI will fail.

I think this is a tough tradeoff, but worth doing. Without this,
it's much too easy for someone to change an option file in a way
that renders it inapplicable/misleading for some podman commands.

Signed-off-by: Ed Santiago <santiago@redhat.com>
2022-10-20 10:57:51 -06:00
fbe2bd87b0 [CI:DOCS] elaborate on image lookups of foreign platforms
After pulling/creating an image of a foreign platform, Podman will
happily use it when looking it up in the local storage and will not
pull down the image matching the host platform.

As discussed in #12682, the reasoning for it is Docker compatibility and
the fact that user already rely on the behavior.  While Podman is now
emitting a warning when an image is in use not matching the local
platform, the documentation was lacking that information.

Fixes: #15300
Signed-off-by: Valentin Rothberg <vrothberg@redhat.com>
2022-08-22 16:38:20 +02:00
d7f134d687 Refactor common man page options, phase 2
Followup to #15174. These are the options that are easy(ish)
to review: those that have only drifted slightly, and need
only minor tweaks to bring back to sanity. For the most part,
I went with the text in podman-run because that was cleaned up
in #5192 way back in 2020. These diffs primarily consist of
using '**' (star star) instead of backticks, plus other
formatting and punctuation changes.

This PR also adds a README in the options dir, and a new
convention: <<container text...|pod text...>> which tries
to do the right thing based on whether the man page name
includes "-pod-" or not. Since that's kind of hairy code,
I've also added a test suite for it.

Finally, since this is impossible to review by normal means,
I'm temporarily committing hack/markdown-preprocess-review,
a script that will diff option-by-option. I will remove it
once we finish this cleanup, but be advised that there are
still 130+ options left to examine, and some of those are
going to be really hard to reunite.

Review script usage: simply run it (you need to have 'diffuse'
installed). It isn't exactly obvious, but it shouldn't take more
than a minute to figure out. The rightmost column (zzz-chosen.md)
is the "winner", the actual content that will be used henceforth.
You really want an ultrawide screen here.

Signed-off-by: Ed Santiago <santiago@redhat.com>
2022-08-09 06:33:17 -06:00