revisit pedantic question about markdown in man pages
given that i'm poking around man pages and submitting (admittedly minor) fixes, can someone clarify the proper markdown for commands versus files? it seems that the marking of commands and/or filenames bounces back and forth between, well, what you see in podman-unshare.1.md: **podman unshare** ... snip ... Executing `podman mount` fails for unprivileged users unless the user is running inside a `podman unshare` session. while filenames seem to typically use backquotes. i have no intention of generating massive churn making all of that consistent, but if i'm submitting a fix for a man page anyway, it might be useful to at least make that page consistent while i'm there. thoughts? rday p.s. i am not trying to be pedantically annoying, i am merely succeeding. -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ========================================================================
On Thu, 23 Jan 2020, Robert P. J. Day wrote:
given that i'm poking around man pages and submitting (admittedly minor) fixes, can someone clarify the proper markdown for commands versus files?
it seems that the marking of commands and/or filenames bounces back and forth between, well, what you see in podman-unshare.1.md:
**podman unshare** ... snip ... Executing `podman mount` fails for unprivileged users unless the user is running inside a `podman unshare` session.
while filenames seem to typically use backquotes.
i have no intention of generating massive churn making all of that consistent, but if i'm submitting a fix for a man page anyway, it might be useful to at least make that page consistent while i'm there.
thoughts?
as this morning's example, i fixed a couple things in "man podman-unshare" (grammar and list formatting), so i cleaned up the markdown while i was there: https://github.com/containers/libpod/pull/4951 that's the sort of thing i had in mind. rday
Honestly Robert, I'm not sure what the right way is to denote commands vs files. I think we've had a number of contributors over time that have done a best guess at the proper format and as you're finding, we've wandered about a bit. I'd be all for picking a format, especially if there's one that widely accepted, and posting it on the CONTRIBUTING.md, and if someone was especially interested, I'd love for a CI job that would verify the formatting, but that's likely a pipe dream. t On 1/23/20 6:02 AM, Robert P. J. Day wrote:
given that i'm poking around man pages and submitting (admittedly minor) fixes, can someone clarify the proper markdown for commands versus files?
it seems that the marking of commands and/or filenames bounces back and forth between, well, what you see in podman-unshare.1.md:
**podman unshare** ... snip ... Executing `podman mount` fails for unprivileged users unless the user is running inside a `podman unshare` session.
while filenames seem to typically use backquotes.
i have no intention of generating massive churn making all of that consistent, but if i'm submitting a fix for a man page anyway, it might be useful to at least make that page consistent while i'm there.
thoughts?
rday
p.s. i am not trying to be pedantically annoying, i am merely succeeding.
On 1/23/20 12:02 PM, Robert P. J. Day wrote:
given that i'm poking around man pages and submitting (admittedly minor) fixes, can someone clarify the proper markdown for commands versus files?
it seems that the marking of commands and/or filenames bounces back and forth between, well, what you see in podman-unshare.1.md:
**podman unshare** ... snip ... Executing `podman mount` fails for unprivileged users unless the user is running inside a `podman unshare` session.
while filenames seem to typically use backquotes.
i have no intention of generating massive churn making all of that consistent, but if i'm submitting a fix for a man page anyway, it might be useful to at least make that page consistent while i'm there.
thoughts?
rday
p.s. i am not trying to be pedantically annoying, i am merely succeeding.
I think this is more about different people submitting different man pages, and us not having a standard. Also people are not doing a good job of reviewing the markdown versus the generated man pages. I would say we should stick to the **podman unshare**. But if you know of a standard format that we should follow, I am willing to listen. Thanks for pointing these out. I opened a couple of PRs to fix them. But any PRs are welcome.
participants (3)
-
Daniel Walsh -
Robert P. J. Day -
Tom Sweeney