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

[Jakub Narebski <jnareb@gmail.com>]

On Sun, 28 Sep 2008 21:04, Michael Witten wrote:
> On 28 Sep 2008, at 3:08 AM, Jakub Narebski wrote:
>> Michael Witten wrote:
>>
>>> Now the man page lists the options in alphabetical
>>> order (in terms of the 'main' part of an option's
>>> name).
>>
>> I know it is a matter of taste, but I prefer having options
>> on man page in functional order, grouped by function, perhaps
>> with subsections to group them (c.f. git-rev-list man page).
> 
> See: http://marc.info/?l=git&m=122246885210923&w=2

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.

-- 
Jakub Narebski
Poland