Re: [PATCH 3/8] Docs: send-email: Man page option ordering

On Sun, 28 Sep 2008 21:04, Michael Witten wrote:

You meant the following comment by  Jeff King?

peff> 4/6: I am not sure about making the order of options the same, peff> the two formats serve different purposes. I think peff> "git send-email --foo" should present the options based on peff> commonality of use. You clearly got the usage wrong, so peff> I think it is helping you to figure out quickly what you peff> probably meant.

This agrees with Gnits (GNU Coding Standard expanded) about --help http://www.gnu.org/software/womb/gnits/Help-Output.html#Help-Output

# When a program has many options, try regrouping options logically,
  instead of listing them all alphabetically (say), as the mere
  regrouping is a succint way to convey much information. Present each
  group of options in its own subtable, suitably introduced by some few
  words. Separate groups by white lines for making the overall structure
  more easy to grasp by the reader. Here is an excerpt from a relatively
  big `--help' output:

       Main operation mode:
          -t, --list              list the contents of an archive
          -x, --extract, --get    extract files from an archive
          -c, --create            create a new archive
          -d, --diff, --compare   find differences between archive and file system
          -r, --append            append files to the end of an archive
          -u, --update            only append files newer than copy in archive
          -A, --catenate          append tar files to an archive
              --concatenate       same as -A
              --delete            delete from the archive (not on mag tapes!)
          
        Device blocking:
          -b, --blocking-factor=BLOCKS   BLOCKS x 512 bytes per record
              --record-size=SIZE         SIZE bytes per record, multiple of 512
          -i, --ignore-zeros             ignore zeroed blocks in archive (means EOF)
          -B, --read-full-records        reblock as we read (for 4.2BSD pipes)

peff>    The manpage, on the other hand, is a comprehensive reference
peff>    and so should probably be alphabetized for easy reading.
 
I haven't found definitive guide or definitive suggestion whether
options in man page should be alphabetized or put in some functional
order. GNU Coding Standards doesn't say anything; at least I haven't
found anything on this topic.

First, git lacks structured texinfo documentation, so manpages serves _both_ as reference, and _as learning tool_. For learning you would want options grouped by function, perhaps sorted alphabetically in group. If you want to find some option, you can always use search and incremental search capabilities of manpages pager.

Second, large manpages with large number of options are usually divided into sections, see git-rev-list(1) manpage, or rpmbuild(8) manpage. So there is precedent for that. And I think it is good precedent.