[Bug 121211] Please provide conventions for documenting subcommands in man-pages(7)

https://bugzilla.kernel.org/show_bug.cgi?id=121211

Michael Kerrisk [off-list ref] changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org

--- Comment #1 from Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> ---

Hi Josh

Many programs now provide subcommands, such as git, systemctl, git-remote,
git-hub, and apt.  These programs follow various different inconsistent
conventions for documenting these subcommands in their manpages.  I'm about
to write such a program with subcommands myself.  I'd love to see some
standard conventions documented in man-pages(7).

I generally would love to see more consistency in man pages across all projects
of course. The thing is, man-pages(7) was primarily driven from the desire to
document best practice for the Linux man-pages project, which produces only a
handful of (relatively short) man pages in Sections 1 and 8. As such, I'm
cautious about making too many prescriptions there about pages in Sections 1
and 8. I have made a few changes though in man-pages(7) just now (see Git).

Note that some programs will want to document all their subcommands in
separate manpages, and others will want a single all-encompassing manpage. 
I don't think man-pages(7) should mandate one or the other approach there,
just establish standards that work either way.

In particular:

- Should the SYNOPSIS section document the usage of every subcommand (see
git-remote for an example), or use a placeholders for subcommands and their
options (see systemctl, git, or git-hub for examples)?

It seems either approach works. Not sure that anything needs to be said in
man-pages about this?

- If the SYNOPSIS just uses placeholders, what placeholder should it use for
subcommands?  "<command>" or "<subcommand>" or "<cmd>" or "<subcmd>"?  (Or
similar with square brackets if optional.)

Are you meaning whether to abbreviate the word "command"? I don't think it's
necessary to specify things to that level.

- What section should subcommands appear in?  I've seen both "COMMANDS" and
"SUBCOMMANDS".

Not sure. Do you have a recommendation and a justification?

- Within that section, what formatting should subcommands use for their
name, usage, description, and options?

I've added a little more detail on this in the man page.

- If programs don't ship separate manual pages for each subcommand, should
they ship symlinks for each subcommand to the main manpage?

I'm not sure what to recommend here. Can you give an example or two?

- How does this work with programs that have multiple levels of subcommand? 
(For instance, consider git-remote, which itself has subcommands.  Or
consider a third-party git extension, like git-hub, which itself has
subcommands.)

I'm not sure I even want to get into that level of detail. (There's much worse
issues affecting many existing man pages, including general inconsistencies in
single pages, spelling, and grammar.)

-- 
You are receiving this mail because:
You are watching the assignee of the bug.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html