Your message dated Mon, 14 Dec 2009 13:52:51 -0500
with message-id <[email protected]>
and subject line Re: [man] order options alphabetically
has caused the Debian Bug report #551741,
regarding alien: [PATCH] manual page - list items in alphabetical order
to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact [email protected]
immediately.)
--
551741: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=551741
Debian Bug Tracking System
Contact [email protected] with problems
--- Begin Message ---
Package: alien
Version: 8.78
Severity: wishlist
Tags: patch
The following path arranges sections PACKAGE FORMAT NOTES, OPTIONS, ENVIRONMENT
in alphabetical order. Cf GNU cp(1), mv(1), OpenBSD ssh(1) 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 alien depends on:
ii cpio 2.10-1 GNU cpio -- a program to manage ar
ii debhelper 7.4.3 helper programs for debian/rules
ii dpkg-dev 1.15.4 Debian package development tools
ii make 3.81-6 An utility for Directing compilati
ii perl 5.10.0-25 Larry Wall's Practical Extraction
ii rpm 4.7.0-9 package manager for RPM
alien recommends no packages.
Versions of packages alien suggests:
ii bzip2 1.0.5-3 high-quality block-sorting file co
ii lintian 2.2.17 Debian package checker
pn lsb-rpm <none> (no description available)
ii patch 2.5.9-5 Apply a diff file to an original
-- no debconf information
>From e86b32a3bed788bedbd2b23f407de2b1d984497e Mon Sep 17 00:00:00 2001
From: Jari Aalto <[email protected]>
Date: Tue, 20 Oct 2009 13:03:33 +0300
Subject: [PATCH] Arrange items in aplhabetical order (PACKAGE FORMAT NOTES,
OPTIONS, ENVIRONMENT)
Signed-off-by: Jari Aalto <[email protected]>
---
alien.pl | 159 +++++++++++++++++++++++++++++++-------------------------------
1 files changed, 79 insertions(+), 80 deletions(-)
diff --git a/alien.pl b/alien.pl
index cc0c423..3dea5b8 100755
--- a/alien.pl
+++ b/alien.pl
@@ -30,10 +30,10 @@ alien version.
=over 4
-=item rpm
+=item deb
-For converting to and from rpm format the Red Hat Package Manager must be
-installed.
+For converting to (but not from) deb format, the gcc, make, debhelper,
+dpkg-dev, and dpkg packages must be installed.
=item lsb
@@ -53,10 +53,16 @@ lsbdev environment.
Note that unlike other package formats, converting an LSB package to
another format will not cause its minor version number to be changed.
-=item deb
+=item pkg
-For converting to (but not from) deb format, the gcc, make, debhelper,
-dpkg-dev, and dpkg packages must be installed.
+To manipulate packages in the Solaris pkg format (which is really the SV
+datastream package format), you will need the Solaris pkginfo and pkgtrans
+tools.
+
+=item rpm
+
+For converting to and from rpm format the Red Hat Package Manager must be
+installed.
=item tgz
@@ -67,12 +73,6 @@ standard linux directory tree. Do NOT run B<alien> on tar
files with source
code in them, unless you want this source code to be installed in your root
directory when you install the package!
-=item pkg
-
-To manipulate packages in the Solaris pkg format (which is really the SV
-datastream package format), you will need the Solaris pkginfo and pkgtrans
-tools.
-
=back
=head1 OPTIONS
@@ -87,30 +87,43 @@ deb format.
The list of package files to convert.
-=item B<-d>, B<--to-deb>
+=item B<--anypatch>
-Make debian packages. This is the default.
+Be less strict about which patch file is used, perhaps attempting to use a
patch
+file for an older verson of the package. This is not guaranteed to always work;
+older patches may not necessarily work with newer packages.
-=item B<-r>, B<--to-rpm>
+=item B<--bump=>I<number>
-Make rpm packages.
+Instead of incrementing the version number of the converted package by 1,
+increment it by the given number.
-=item B<-t>, B<--to-tgz>
+=item B<-c>, B<--scripts>
-Make tgz packages.
+Try to convert the scripts that are meant to be run when the
+package is installed and removed. Use this with caution, because these
+scripts might be designed to work on a system unlike your own, and could
+cause problems. It is recommended that you examine the scripts by hand
+and check to see what they do before using this option.
-=item B<--to-slp>
+This is enabled by default when converting from lsb packages.
-Make slp packages.
+=item B<-d>, B<--to-deb>
-=item B<-p>, B<--to-pkg>
+Make debian packages. This is the default.
-Make Solaris pkg packages.
+=item B<--description=>I<desc>
-=item B<-i>, B<--install>
+Specifiy a description for the package. This only has an effect when
+converting from the tgz package format, which lacks descriptions.
-Automatically install each generated package, and remove the package file
-after it has been installed.
+=item B<--fixperms>
+
+Sanitize all file owners and permissions when building a deb. This may be
+useful if the original package is a mess. On the other hand, it may break
+some things to mess with their permissions and owners to the degree this does,
+so it defaults to off. This can only be used when converting to debian
+packages.
=item B<-g>, B<--generate>
@@ -121,50 +134,47 @@ this temporary directory by running "debian/rules
binary", if you were creating
a Debian package, or by running "rpmbuild -bb <packagename>.spec" if you were
creating a Red Hat package.
-=item B<-s>, B<--single>
+=item B<-h>, B<--help>
-Like B<-g>, but do not generate the packagename.orig directory. This is only
-useful when you are very low on disk space and are generating a debian
-package.
+Display a short usage summary.
-=item B<--patch=>I<patch>
+=item B<-i>, B<--install>
-Specify the patch to be used instead of automatically looking the patch up
-in B</var/lib/alien>. This has no effect unless a debian package is being
-built.
+Automatically install each generated package, and remove the package file
+after it has been installed.
-=item B<--anypatch>
+=item B<-k>, B<--keep-version>
-Be less strict about which patch file is used, perhaps attempting to use a
patch
-file for an older verson of the package. This is not guaranteed to always work;
-older patches may not necessarily work with newer packages.
+By default, B<alien> adds one to the minor version number of each package it
+converts. If this option is given, B<alien> will not do this.
=item B<--nopatch>
Do not use any patch files.
-=item B<--description=>I<desc>
+=item B<-p>, B<--to-pkg>
-Specifiy a description for the package. This only has an effect when
-converting from the tgz package format, which lacks descriptions.
+Make Solaris pkg packages.
-=item B<--version=>I<version>
+=item B<--patch=>I<patch>
-Specifiy a version for the package. This only has an effect when
-converting from the tgz package format, which may lack version
-information.
+Specify the patch to be used instead of automatically looking the patch up
+in B</var/lib/alien>. This has no effect unless a debian package is being
+built.
-Note that without an argument, this displays the version of B<alien> instead.
+=item B<-r>, B<--to-rpm>
-=item B<-c>, B<--scripts>
+Make rpm packages.
-Try to convert the scripts that are meant to be run when the
-package is installed and removed. Use this with caution, because these
-scripts might be designed to work on a system unlike your own, and could
-cause problems. It is recommended that you examine the scripts by hand
-and check to see what they do before using this option.
+=item B<-s>, B<--single>
-This is enabled by default when converting from lsb packages.
+Like B<-g>, but do not generate the packagename.orig directory. This is only
+useful when you are very low on disk space and are generating a debian
+package.
+
+=item B<-t>, B<--to-tgz>
+
+Make tgz packages.
=item B<-T>, B<--test>
@@ -172,41 +182,30 @@ Test the generated packages. Currently this is only
supported for debian
packages, which, if lintian is installed, will be tested with lintian and
lintian's output displayed.
-=item B<-k>, B<--keep-version>
-
-By default, B<alien> adds one to the minor version number of each package it
-converts. If this option is given, B<alien> will not do this.
-
-=item B<--bump=>I<number>
-
-Instead of incrementing the version number of the converted package by 1,
-increment it by the given number.
-
-=item B<--fixperms>
+=item B<--to-slp>
-Sanitize all file owners and permissions when building a deb. This may be
-useful if the original package is a mess. On the other hand, it may break
-some things to mess with their permissions and owners to the degree this does,
-so it defaults to off. This can only be used when converting to debian
-packages.
+Make slp packages.
=item B<-v>, B<--verbose>
Be verbose: Display each command B<alien> runs in the process of converting a
package.
-=item B<--veryverbose>
+=item B<-V>, B<--version>
-Be verbose as with --verbose, but also display the output of each command
-run. Some commands may generate a lot of output.
+Display the version of B<alien>.
+=item B<--version=>I<version>
-=item B<-h>, B<--help>
+Specifiy a version for the package. This only has an effect when
+converting from the tgz package format, which may lack version
+information.
-Display a short usage summary.
+Note that without an argument, this displays the version of B<alien> instead.
-=item B<-V>, B<--version>
+=item B<--veryverbose>
-Display the version of B<alien>.
+Be verbose as with --verbose, but also display the output of each command
+run. Some commands may generate a lot of output.
=back
@@ -243,6 +242,11 @@ B<alien> recognizes the following environemnt variables:
=over 4
+=item EMAIL
+
+If set, B<alien> assumes this is your email address. Email addresses are
+included in generated debian packages.
+
=item RPMBUILDOPTS
Options to pass to rpm when it is building a package.
@@ -251,11 +255,6 @@ Options to pass to rpm when it is building a package.
Options to pass to rpm when it is installing a package.
-=item EMAIL
-
-If set, B<alien> assumes this is your email address. Email addresses are
-included in generated debian packages.
-
=back
=head1 NOTES
--
1.6.4.3
--- End Message ---
--- Begin Message ---
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
Description: Digital signature
--- End Message ---
