New: Please provide conventions for documenting subcommands in man-pages(7)
https://bugzilla.kernel.org/show_bug.cgi?id=121211
Bug ID: 121211
Summary: Please provide conventions for documenting subcommands
in man-pages(7)
Product: Documentation
Version: unspecified
Hardware: All
OS: Linux
Status: NEW
Severity: enhancement
Priority: P1
Component: man-pages
Assignee: documentation_man-pages-ztI5WcYan/[email protected]
Reporter: [email protected]
Regression: NoMany 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).
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)?
- 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.)
- What section should subcommands appear in? I've seen both "COMMANDS" and "SUBCOMMANDS".
- Within that section, what formatting should subcommands use for their name, usage, description, and options?
- If programs don't ship separate manual pages for each subcommand, should they ship symlinks for each subcommand to the main manpage?
- 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.)
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): bug-121211-11311-3bo0kxnWaOQUvHkbgXJLS5sdmw4N0Rt+2LY78lusg7I@public.gmane.org/
[Bug 121211] Please provide conventions for documenting subcommands in man-pages(7)
https://bugzilla.kernel.org/show_bug.cgi?id=121211
Michael Kerrisk <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
CC| |[email protected]
--- Comment #1 from Michael Kerrisk <[email protected]> --- Hi Josh
Quoted 5 lines
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).
Quoted 10 lines
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?
Quoted 3 lines
- 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.
Quoted 2 lines
- What section should subcommands appear in? I've seen both "COMMANDS" and "SUBCOMMANDS".
Not sure. Do you have a recommendation and a justification?
Quoted 2 lines
- 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.
Quoted 2 lines
- 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?
Quoted 4 lines
- 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.)
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 121211] Please provide conventions for documenting subcommands in man-pages(7)
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=121211
--- Comment #2 from Josh Triplett <[email protected]> --- (In reply to Michael Kerrisk from comment #1)
Quoted 8 lines
Hi Josh
Quoted 5 lines
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).
Quoted 6 lines
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.
The man-pages project, though, seems like the one project with the greatest claim to provide style guidelines for consistency. Some of these have less to do with one stylistic choice looking *better*, and more about maintaining consistency between pages.
Quoted 2 lines
I have made a few changes though in man-pages(7) just now (see Git).
Those look helpful, thanks.
One bug report for those changes: the first of the two new subheadings should say "Formatting conventions for manual pages describing commands", rather than "... functions" (duplicating the second heading).
Quoted 5 lines
Quoted 5 lines
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.
Quoted 8 lines
Quoted 5 lines
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?
Consistency between pages helps.
Personally, I'd suggest using a placeholder for the subcommand, for the same reason that the majority of manpages just say [OPTION]... rather than listing every possible option in the synopsis.
Quoted 6 lines
Quoted 3 lines
- 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.
No, I was mostly asking about whether the thing in question should be called a "command" or a "subcommand", as with the question below about headings. man-pages makes several specific recommendations about terminology for consistency; this seems like a useful distinction to make there.
Quoted 4 lines
Quoted 2 lines
- What section should subcommands appear in? I've seen both "COMMANDS" and "SUBCOMMANDS".
Not sure. Do you have a recommendation and a justification?
I would recommend "SUBCOMMANDS", because we typically use "commands" to refer to the top-level programs like "cp", "ls", and "git". Let's avoid the ambiguity.
Quoted 4 lines
Quoted 2 lines
- 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.
I saw the details regarding the use of boldface and italics. I was more wondering about paragraphs and indentation. I'd thought of using the following, though the need for .RS/.RE bugs me:
.SH SUBCOMMANDS
.TP
\fBcommand subcommand1\fR
Description of subcommand1.
.IP
More description of subcommand1.
.TP
\fBcommand subcommand2\fR [\fB-f\fR|\fB--flag\fR] \fIarg\fR Description of subcommand2.
.IP
More description of subcommand2.
.RS
.TP
\fIarg\fR
Description of \fIarg\fR.
.TP
.BR -f | --flag
Description of \fB--flag\fR.
.RE
Does that look reasonable, or do you have another idea for how subcommands with flags and arguments should format their descriptions? Either way, this seems like something worth providing guidance on, just as man-pages(7) currently provides guidance suggesting the use of .TP in several places.
I can provide a patch for this.
Quoted 4 lines
Quoted 2 lines
- 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?
git(1) mentions its subcommands, but has separate manpages for git-diff(1), git-commit(1), and so on, so "man git diff" works. If git instead documented all of its subcommands inline, should it ship a symlink git-diff.1.gz -> git.1.gz? (Or a manpage containing just a .so line?)
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 121211] Please provide conventions for documenting subcommands in man-pages(7)
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=121211
--- Comment #3 from Josh Triplett <[email protected]> --- Created attachment 222381
--> https://bugzilla.kernel.org/attachment.cgi?id=222381&action=edit
[PATCH 1/3] man-pages.7: tfix
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 121211] Please provide conventions for documenting subcommands in man-pages(7)
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=121211
--- Comment #4 from Josh Triplett <[email protected]> --- Created attachment 222391
--> https://bugzilla.kernel.org/attachment.cgi?id=222391&action=edit
[PATCH 2/3] man-pages.7: Document conventions for formatting OPTIONS
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 121211] Please provide conventions for documenting subcommands in man-pages(7)
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=121211
--- Comment #5 from Josh Triplett <[email protected]> --- Created attachment 222401
--> https://bugzilla.kernel.org/attachment.cgi?id=222401&action=edit
[PATCH 3/3] man-pages.7: Add SUBCOMMANDS section and conventions
Signature · 6 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html