common: Cleanup manpage formatting #504
Conversation
siretart
force-pushed
the
manpage-fixes-common
branch
from
ecaca2d to
8d4e69c
Compare
mtrmac
left a comment
mtrmac
left a comment
There was a problem hiding this comment.
By no means a complete review, I just have enough questions that this feels like a good point to stop and discuss.
Also address most troff issues. Not all of them are easy, in particular those manpages with long urls and examples that include digests are difficult to render in traditional manpages. Signed-off-by: Reinhard Tartler <siretart@tauware.de>
siretart
force-pushed
the
manpage-fixes-common
branch
from
f0f541f to
a8a0290
Compare
| Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz. | ||
|
|
||
| The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label. | ||
| The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label. | ||
|
|
||
| The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount. | ||
| The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount. | ||
|
|
||
| Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container. | ||
| Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container. |
There was a problem hiding this comment.
These are conceptually a description of the relabel= options, so should be nested under those bullet points (as opposed to the Options specific to *tmpfs* line below, which is “higher level” than the bullet points).
So, I think these should be indented one level; that seems to make a difference for GitHub rendering, but I’m afraid creates exactly the same man page content, so it does not help there. Maybe I’m missing a trick. If not, using a more precise markup means we can hope for md2man improvements in the future.
| Matching is done using the `filepath.Match` rules: | ||
|
|
||
| * A preprocessing step removes leading and trailing whitespace and eliminates | ||
| . and .. elements using the golang `path/filepath` package. |
There was a problem hiding this comment.
(If this should be referring to Go’s implementation details at all — arguably that’s not very useful to users, but I think rewording all of this would be a different PR),filepath.Clean is a specific way to clean, and matches the form of the filepath.Match reference above.
| Container engines like Podman & Buildah read containers.conf file, if it exists | ||
| and modify the defaults for running containers on the host. containers.conf uses | ||
| a TOML format that can be easily modified and versioned. | ||
| Container engines like Podman & Buildah read` containers.conf` file, if it |
There was a problem hiding this comment.
| Container engines like Podman & Buildah read` containers.conf` file, if it | |
| Container engines like Podman & Buildah read `containers.conf` file, if it |
otherwise md2man joins the two words.
|
|
||
| Options are: | ||
| `device` Uses the network_interface name from the network config as interface name. Falls back to the ethX pattern if the network_interface is not set. | ||
| `device`: Uses the network_interface name from the network config as interface name. Falls back to the ethX pattern if the network_interface is not set. |
There was a problem hiding this comment.
The other “Options are” sections don’t use a colon. I have very little preference on one vs. the other, but consistency is easier to maintain.
(Reformating these ~tables to consistently be proper tables, or perhaps definition lists, would also be an option, but not at all necessary.)
2 participants
Also address most troff issues. Not all of them are easy, in particular those manpages with long urls and examples that include digests are difficult to render in traditional manpages.
Add troff renderering to the Manpage to surface those troff issues more easily