scattered inconsistency in podman docs markdown files
this would be my OCD coming through, but as i'm crawling through the man page markdown files, i see a lack of consistency in how various objects are marked (and therefore possibly rendered). using podman-run.1.md as a single example, it first appears that commands are marked with double asterisks, as in: "Run a process in a new container. **podman run** starts a process with its own file system, its own networking, and its own isolated process tree. The IMAGE which starts the process may define defaults related to the process that will be run in the container, the networking to expose, and more, but **podman run** ..." ok, fair enough, so that's the standard for commands which, in a simple terminal window, renders as bold. on the other hand, filenames apparently use backqoutes: "Several files will be automatically created within the container. These include `/etc/hosts`, `/etc/hostname`, and `/etc/resolv.conf` to manage networking..." again, fair enough, except in the very next para, they're not similarly marked: "When running from a user defined network namespace, the /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise /etc/resolv.conf will be used..." in any event, that is also rendered as bold in a terminal window, so i'm assuming that, in other environments, there will be a difference in rendering. next, WRT options, i notice that some man pages use the word "option" while others use the word "flag". from the same markdown file we're using so far, we have both examples: "Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times." "To modify the proportion from the default of 1024, use the **--cpu-shares** flag to set the weighting to 2 or higher." is it worth bouncing back and forth between "flag" and "option"? finally, in other pages, there is the occasional example of a flag that doesn't include the leading two hyphens, such as near the beginning of podman-save.1.md: "**podman save** writes to STDOUT by default and can be redirected to a file using the **output** flag. The **quiet** flag suppresses the output when set." i'm guessing that the above should read **--output** and **--quiet**, no? in any event, is there a short list of standards for all of this? rday
On Fri, 2020-01-03 at 16:15 -0500, Robert P. J. Day wrote:
this would be my OCD coming through, but as i'm crawling through the man page markdown files, i see a lack of consistency in how various objects are marked (and therefore possibly rendered).
using podman-run.1.md as a single example, it first appears that commands are marked with double asterisks, as in:
"Run a process in a new container. **podman run** starts a process with its own file system, its own networking, and its own isolated process tree. The IMAGE which starts the process may define defaults related to the process that will be run in the container, the networking to expose, and more, but **podman run** ..."
ok, fair enough, so that's the standard for commands which, in a simple terminal window, renders as bold.
on the other hand, filenames apparently use backqoutes:
"Several files will be automatically created within the container. These include `/etc/hosts`, `/etc/hostname`, and `/etc/resolv.conf` to manage networking..."
again, fair enough, except in the very next para, they're not similarly marked:
"When running from a user defined network namespace, the /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise /etc/resolv.conf will be used..."
in any event, that is also rendered as bold in a terminal window, so i'm assuming that, in other environments, there will be a difference in rendering.
next, WRT options, i notice that some man pages use the word "option" while others use the word "flag". from the same markdown file we're using so far, we have both examples:
"Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times."
"To modify the proportion from the default of 1024, use the **--cpu-shares** flag to set the weighting to 2 or higher."
is it worth bouncing back and forth between "flag" and "option"?
finally, in other pages, there is the occasional example of a flag that doesn't include the leading two hyphens, such as near the beginning of podman-save.1.md:
"**podman save** writes to STDOUT by default and can be redirected to a file using the **output** flag. The **quiet** flag suppresses the output when set."
i'm guessing that the above should read **--output** and **--quiet**, no?
in any event, is there a short list of standards for all of this?
rday _______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
Robert, I am not aware of any standards. I am sure google can find them for man pages. But then again, you are addressing primarily programmers here and this isn't exactly a string point for many of us. That said, patches are certainly welcome!
On Fri, 3 Jan 2020, Brent Baude wrote: ... snip ...
Robert,
I am not aware of any standards. I am sure google can find them for man pages. But then again, you are addressing primarily programmers here and this isn't exactly a string point for many of us.
That said, patches are certainly welcome!
oh, i appreciate that the developers are not as concerned about this kind of nitpickery as i am, but since i'm poring over the docs in preparation to giving some tutorials and seminars on this stuff, i might as well, as you suggest, submit some patches. i assume i can just submit them to this list in the same manner as kernel patches to LKML, yes? rday
On Sat, Jan 04, 2020 at 05:11:36AM -0500, Robert P. J. Day wrote:
On Fri, 3 Jan 2020, Brent Baude wrote:
... snip ...
Robert,
I am not aware of any standards. I am sure google can find them for man pages. But then again, you are addressing primarily programmers here and this isn't exactly a string point for many of us.
That said, patches are certainly welcome!
oh, i appreciate that the developers are not as concerned about this kind of nitpickery as i am, but since i'm poring over the docs in preparation to giving some tutorials and seminars on this stuff, i might as well, as you suggest, submit some patches.
i assume i can just submit them to this list in the same manner as kernel patches to LKML, yes?
No; the libpod project is on github[1]; please follow the github PR model for submitting pull requests. [1] https://github.com/containers/libpod/ And: as someone with a similar level of persnicketiness, *thank you* (or should that be **thank you**?). I've long despaired about the inconsistencies in man pages, and I try to fix them as I find them, but have been unable to find an automated way to detect/prevent them. Best regards, Ed -- Ed Santiago [he/him/his] Toolsmith santiago@redhat.com
On 1/3/20 4:55 PM, Brent Baude wrote:
On Fri, 2020-01-03 at 16:15 -0500, Robert P. J. Day wrote:
this would be my OCD coming through, but as i'm crawling through the man page markdown files, i see a lack of consistency in how various objects are marked (and therefore possibly rendered).
using podman-run.1.md as a single example, it first appears that commands are marked with double asterisks, as in:
"Run a process in a new container. **podman run** starts a process with its own file system, its own networking, and its own isolated process tree. The IMAGE which starts the process may define defaults related to the process that will be run in the container, the networking to expose, and more, but **podman run** ..."
ok, fair enough, so that's the standard for commands which, in a simple terminal window, renders as bold.
on the other hand, filenames apparently use backqoutes:
"Several files will be automatically created within the container. These include `/etc/hosts`, `/etc/hostname`, and `/etc/resolv.conf` to manage networking..."
again, fair enough, except in the very next para, they're not similarly marked:
"When running from a user defined network namespace, the /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise /etc/resolv.conf will be used..."
in any event, that is also rendered as bold in a terminal window, so i'm assuming that, in other environments, there will be a difference in rendering.
next, WRT options, i notice that some man pages use the word "option" while others use the word "flag". from the same markdown file we're using so far, we have both examples:
"Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times."
"To modify the proportion from the default of 1024, use the **--cpu-shares** flag to set the weighting to 2 or higher."
is it worth bouncing back and forth between "flag" and "option"?
finally, in other pages, there is the occasional example of a flag that doesn't include the leading two hyphens, such as near the beginning of podman-save.1.md:
"**podman save** writes to STDOUT by default and can be redirected to a file using the **output** flag. The **quiet** flag suppresses the output when set."
i'm guessing that the above should read **--output** and **--quiet**, no?
in any event, is there a short list of standards for all of this?
rday _______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io Robert,
I am not aware of any standards. I am sure google can find them for man pages. But then again, you are addressing primarily programmers here and this isn't exactly a string point for many of us.
That said, patches are certainly welcome! _______________________________________________ Podman mailing list -- podman@lists.podman.io To unsubscribe send an email to podman-leave@lists.podman.io
Yes, I would say that the man pages and other markdown have evolved over time, with no set standard, they have wandered over time, and no one has had the time or inclination to go back over them and standardize on one format. If you want to open a patch to make them standard that would be welcome. If you had a standard document, that you knew about for man pages, that we could add to contributors page, that would be good. BTW I am probably part of the problem, in not always doing things the same way. :^(
participants (4)
-
Brent Baude -
Daniel Walsh -
Ed Santiago -
Robert P. J. Day