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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
