Command flags (OPTIONS) in man pages have to date been in
haphazard order. Sometimes that order is sensible, e.g.,
most-important options first, but more often they're
just in arbitrary places. This makes life hard for users.
Here, I update the man-page-check Makefile script so it
checks and enforces alphabetical order in OPTIONS sections.
Then -- the hard part -- update all existing man pages to
conform to this requirement.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Add new CI check to confirm that links and references
in SEE ALSO sections are properly formatted and that
links are valid (at least in theory: we do no actual
URL fetching to test for 404).
The check is piggybacked into existing xref-helpmsgs-manpages
script. It could conceivably be more elegant to write a
separate tool for this purpose, but I don't wish to duplicate
the logic for finding and reading markdown files.
Script identified various problems, which I fix in this PR:
. missing '**' (asterisks) around some references, or '**'
in the wrong place.
. links pointing to github.com/.../tree/ instead of /blob/
(github redirects those automatically, but I like
consistency)
. a few copy-paste errors, e.g. subgid linking to subuid.
Signed-off-by: Ed Santiago <santiago@redhat.com>
* Write a description to outline the scope and mechanism of runlabel.
* Describe the variables/attributes that we want to be used.
* Do not describe the --optN or OPTN flags/variables since they are
already hidden flags and date back to the Atomic days.
* Update references to other man pages.
* Remove unsupported variables (e.g., SUDO_*) which caused confusion.
Fixes: #10799
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Point to containers-certs.d(5) for details on the default paths, the
lookup logic and the structure of these directories. Previously, the
man pages stated that the default path would be in `/etc/containers/...`
which is not entirely and a red herring for users (see #10116).
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
Commit 800a2e2d35 introduced a way to disable the conversion of `--`into
an en dash on docs.podman.io, so the ugly workaround of escaping the
dashes is no longer necessary.
Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
Escape the two dashes, otherwise they are combined into one long dash.
I tested that this change is safe and still renders correctly on github
and with the man pages.
This commit also contains a small change to make it build locally.
Assuming you have the dependencies installed you can do:
```
cd docs
make html
```
Preview the html files in docs/build/html with
`python -m http.server 8000 --directory build/html`.
Fixescontainers/podman.io#373
Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
Remove --volume option from podman-remote since it is
not supported, also add information to podman-build man page
indicating options not supported over remote connections.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
Change the docs markdown so that flag names will be h4 headers.
Sphinx will automatically add anchors to headers. Add css to
make sure the flag names are not to big compared to the text.
The man pages also still renders fine but it looks a bit different.
Signed-off-by: Paul Holzinger <paul.holzinger@web.de>
These options are now fully supported in the remote API and should no
longer be hidden and/or documented as non supported.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
The other direction: fix or clean up elements documented in
man pages but which did/do not exist in actual podman:
* runlabel: add missing "-n" alias for --name
And, remove man page entries for nonexistent options:
* podman commit: --iidfile
* podman container runlabel: --rootfs, --storage
* podman create: --cpu-count
There are two problems I don't know how to deal with. Both
are related to main_local.go:rootCmd.PersistentFlags() :
1) podman-build.1.md documents --cni-config-dir and
--runtime options, but these are not actually options
under podman build; they are global options. The
documentation in this man page differs from that
under podman-build.
2) podman ps implements a binary --namespace option,
but this option does not (cannot?) appear in --help
because there's a global --namespace string option
and Cobra somehow gets confused about this.
Do we really intend for global options to be parsed on
the right-hand side of subcommands? This strikes me as
unintuitive and potentially confusing, although the
fact that it has taken me this long to discover it
suggests that it's not _that_ confusing.
Suggestions welcome. I can file issues for 1/2 above,
or simply teach my script to special-case ignore them.
Signed-off-by: Ed Santiago <santiago@redhat.com>
* Refactored code and Makefile to support new docs layout
* Removed some old code packaging code
* Add Readme.md to document what we're doing
Signed-off-by: Jhon Honce <jhonce@redhat.com>
Signed-off-by: baude <bbaude@redhat.com>
