7 Commits

Author SHA1 Message Date
22f3dd4c29 Man pages: refactor common options: arch
Smaller, more reviewable chunks.

This is just one option, --arch. Future PRs may, if the reviewing
is easy, include multiple options. This one includes fixes to
the preprocessor script, though:

 * big oops, I was not handling '<<something pod|something>>'
   where 'pod' appears other than the beginning of the string.
 * I was also not handling 'container<<| or pod>>', where one
   side was empty.
 * Behavior change: <<subcommand>>, on podman-pod-foo,
   becomes just 'foo' (not 'pod foo'). This will be useful
   in a future PR where we refactor --pod-id-file.

Signed-off-by: Ed Santiago <santiago@redhat.com>
2022-08-15 12:31:30 -06:00
2bcee9f627 Man pages: refactor common options
Continued. Harder-to-review ones this time.

Signed-off-by: Ed Santiago <santiago@redhat.com>
2022-08-09 16:18:53 -06: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
5ea4ebb163 markdown-preprocess: force extra newline on comments
go-md2man happily ignores our comment lines in most cases,
but sphinx (used in readthedocs) cannot deal with comments
if they immediately follow any other content line:

    blah blah
    [//]: # (my comment)

...the whole comment line is actually rendered in its output.

Only solution seems to be to add extra newlines before each
comment. Makes diff and PR review harder, but otherwise has
no effect on the rendered documents.

Signed-off-by: Ed Santiago <santiago@redhat.com>
2022-08-04 08:38:29 -06:00
65fb90165a hack/markdown-preprocess: allow to be executed from any dir
Signed-off-by: Paul Holzinger <pholzing@redhat.com>
2022-08-04 10:57:31 +02:00
031b7dec71 fix hack/markdown-preprocess to support older python versions
str.removeprefix() and str.removesuffix() is python 3.9+ only but we need to
support older versions for the OSX cross task.

This fixes broken CI on main.

Signed-off-by: Paul Holzinger <pholzing@redhat.com>
2022-08-04 10:26:18 +02:00
56039cffd7 Refactor common options in man pages
podman-create and -run have many options in common. To date,
these are copy-pasted and haphazardly maintained.

Solution: add an include mechanism, '@@option foo', such
that multiple md source files can fetch from one common file.

This is a Phase One commit, a very small subset of what's
possible. Purpose of this commit is ease of review. If this
passes review, much more (trickier stuff) will be forthcoming.

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