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

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

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

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/vQLgFONoPN62D2FQJk+8+b@public.gmane.org
          Reporter: josh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org
        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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

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

Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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

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

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

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

--- Comment #2 from Josh Triplett <josh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> ---
(In reply to Michael Kerrisk from comment #1)
> 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.

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.

> 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).

> > 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?

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.

> > - 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.

> > - 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.

> > - 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.

> > - 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?)

-- 
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

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

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

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

--- Comment #3 from Josh Triplett <josh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> ---
Created attachment 222381
  --> https://bugzilla.kernel.org/attachment.cgi?id=222381&action=edit
[PATCH 1/3] man-pages.7: tfix

-- 
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

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

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

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

--- Comment #4 from Josh Triplett <josh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> ---
Created attachment 222391
  --> https://bugzilla.kernel.org/attachment.cgi?id=222391&action=edit
[PATCH 2/3] man-pages.7: Document conventions for formatting OPTIONS

-- 
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

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

[bugzilla-daemon-590EEB7GvNiWaY/ihj7yzEB+6BGkLq7r]

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

--- Comment #5 from Josh Triplett <josh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> ---
Created attachment 222401
  --> https://bugzilla.kernel.org/attachment.cgi?id=222401&action=edit
[PATCH 3/3] man-pages.7: Add SUBCOMMANDS section and conventions

-- 
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