Debian Bug report logs - #561017
pristine-tar: [man] order options alphabetically

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Jari Aalto <jari.aalto@cante.net>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: pristine-tar: [man] order options alphabetically

Date: Sun, 13 Dec 2009 20:35:48 +0200

Package: pristine-tar
Version: 1.00
Severity: wishlist


Please consider ordering options alphabetically in manual
page. C.f. GNU cp, mv, etc.

-- System Information:
Debian Release: squeeze/sid
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.30-2-amd64 (SMP w/2 CPU cores)
Locale: LANG=en_DK.UTF-8, LC_CTYPE=en_DK.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages pristine-tar depends on:
ii  libc6                  2.10.2-2          GNU C Library: Shared libraries
ii  perl-modules           5.10.1-8          Core Perl modules
ii  xdelta                 1.1.3-9           A diff utility which works with bi
ii  zlib1g                 1:1.2.3.3.dfsg-15 compression library - runtime

Versions of packages pristine-tar recommends:
ii  bzip2                         1.0.5-3    high-quality block-sorting file co
ii  pbzip2                        1.0.5-1    parallel bzip2 implementation

pristine-tar suggests no packages.

-- no debconf information

Message #10 received at 561017-done@bugs.debian.org (full text, mbox, reply):

From: Joey Hess <joeyh@debian.org>

To: Jari Aalto <jari.aalto@cante.net>, 561017-done@bugs.debian.org, 499487-done@bugs.debian.org, 551741-done@bugs.debian.org

Subject: Re: [man] order options alphabetically

Date: Mon, 14 Dec 2009 13:52:51 -0500

[Message part 1 (text/plain, inline)]

Jari Aalto wrote in #499487 on alien:
> The following pat[c]h arranges sections PACKAGE FORMAT NOTES, OPTIONS,
> ENVIRONMENT in alphabetical order. Cf GNU cp(1), mv(1), OpenBSD ssh(1) etc.

Jari Aalto wrote in #499487 on pristine-tar:
> Consider ordering the options alhabetically. (Cf. see ls(1), cp(1),
> mv(1) etc.)

Jari Aalto wrote in #561017 on pristine-tar:
> Please consider ordering options alphabetically in manual
> page. C.f. GNU cp, mv, etc.

Man pages can be read in one of two ways:

1. Searched for a given term. What you do if you forget the name
   of some option.
2. Straight through. Typically only skimming the start of each section
   in turn until it stops seeming interesting.

In the first case, alphabetical order does not help; in fact order is
largely irrelevant.

In the second case, alphabetical order is generally a pessimal order;
it's better to put the most important information first so that the user
is more likely to see it, and/or to group related concepts.

I hesitate to use the GNU man pages as good examples of anything, given
the crappy stubs pointing to info files that "GNU man pages" brings to
mind. But it is perhaps worth noting that cp(1) and mv(1) reorder --help
and --version to the end, out of the alphabetical sequence, in an
attempt to at least get the more useful options first and boilerplate
last. The vast number of forward references in the ls(1) man page is
also interesting. (These options are all mentioned before they are
documented: -l, -lt, -x, -m, -l, -1, --time-style, --sort, -p,
--file-type, -F, -U, -X, -S, -t, -v) I suspect that it is impossible for
a normal human (who can't keep 20 things in his head at a time) to read
that man page straight through and understand it all.

The pristine-tar man page lists subcommands in an order that builds up
an understanding of what it does and groups related concepts. Starting
with 'gendelta' which creates a delta, then `gentar` which uses a delta
to recreate the tarball, and then `commit` and `checkout`, which are
likewise paired operations at a higher abstraction level. Reordering this
to alphabetical would put checkout before commit, and both VCS-based 
operations before the gendelta/gentar operations that need to be understood
first.

Of course, you didn't ask me to reorder that to alphabetical. You asked
me to reorder the options list to alphabetrical. That list is of 4
options, and easily fits on one page, therefore the order does not
matter much. However, three of those options, "-vdk", are shared by
pristine-bz and pristine-gz, and are accepted by all subcommands. The
other option, -m, is the odd one out. Therefore, it makes sense to me to
put it last. This allows all the synopses to include a "[-vdk]" that
lists the options in the same order they are documented. The choice of
ordering for the -v, -d, and -k is loosely based on the likelyhood of
an option being used.

Now, in alien, there are a lot of options, and oddly you didn't ask me
to reorder them. They are arranged in approximate use order, with
logical groupings. (And I just reordered them a bit since --patch etc is
fairly deprecated now.) Instead you want me to reorder some of the
sections. First, your examples are bad; ssh(1)'s sections are in this
order: N, S, D, A, E, T, X, V, S, E, F, S, A. The order is loosely
a use-based ordering; few users do ssh-based VPNs, so that is near the
end. The other man pages cited use the order N, S, D, A, R, C, S.
Indeed, man pages have a strong tradition of a mostly use-based
section ordering, not alphabetical. man-pages(7) documents it; there is
little alphabetization involved.

Now, alien(1) lists the WARNING near the top because it is important;
PACKAGE FORMAT NOTES is also important; ENVIRONMENT is not very
important. The rest of the ordering is the traditional, documented man
page section ordering. (I have, though, removed the other NOTES section,
which was clutter and in the wrong place.)

In summary, you may like to file bugs on alpabetical order, but I have
you beat; I can overanalise this stuff into the ground. :P

-- 
see shy jo

[signature.asc (application/pgp-signature, inline)]

Send a report that this bug log contains spam.