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@xxxxxxxxxxxxxxxxxxxx Reporter: josh@xxxxxxxxxx Regression: No 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). 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.) -- 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
