reorganize manpage ordering and contents

3 files changed, 269 insertions, 231 deletions

diff --git a/ChangeLog b/ChangeLog
index 1fb80c0..d643867 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2007-06-15  Junichi Uekawa  <dancer@debian.org>
+
+	* pbuilderrc.5: reorganize to maintain same ordering as pbuilder.8
+
+	* pbuilder.8: reorganize the ordering of options.
+
 2007-06-07  Junichi Uekawa  <dancer@debian.org>
 
 	* Makefile (install): install rebuild example scripts.
diff --git a/pbuilder.8 b/pbuilder.8
index 2a768de..c54ae00 100644
--- a/pbuilder.8
+++ b/pbuilder.8
@@ -87,13 +87,12 @@ Dumps configuration information, used for debugging.
 .TP
 .B "debuild"
 Builds a Debian package from the Debian source directory.
-There needs to be a 
+The current directory should have the usual
 .I "debian/"
-directory in the current directory.
+directory.
 
-This command is a convenience script, 
-and it does not accept most command-line options.
-This may change in the future.
+Same as
+.B "pdebuild --use-pdebuild-internal"
 
 .SH "OPTIONS"
 
@@ -110,9 +109,9 @@ Specifies the location of
 
 This option will define the default distribution and 
 apt-lines when used in
-.B "pbuilder update"
+.B "pbuilder --update"
 and 
-.B "pbuilder create"
+.B "pbuilder --create"
 
 .TP
 .BI "\-\-buildplace [" "location of build" "]"
@@ -138,6 +137,9 @@ This is to avoid
 overwriting already existing deb files with
 the newly generated ones.
 
+\" 
+\" 
+\" 
 .TP
 .BI "\-\-mirror [" "mirror location" "]"
 Specifies the URL of Debian mirror to be 
@@ -158,6 +160,9 @@ the chroot, and specifying
 .B "file:/somewhere/"
 will most probably fail.
 
+\" 
+\" 
+\" 
 .TP
 .BI "\-\-othermirror [" "deb http://xxx/xxx/ ./ " "|" " other deb lines... " "]"
 The lines which is added to the sources.list, delimited with 
@@ -177,7 +182,29 @@ mirror sites; apt will then use them in preference to the ones
 listed in 
 .B "\-\-mirror".
 
-These options are only valid when
+
+\" 
+\" 
+\" 
+.TP
+.BI "\-\-distribution [" "distribution" "]"
+Specifies the distribution used. Currently the supported values are
+.B "sid"
+.B "etch"
+.B "lenny"
+and 
+.B "experimental".
+
+.TP
+.BI "\-\-override\-config"
+
+Specify to use different apt set up inside the chroot than it was used for creating the 
+base.tgz.
+Specify this when you want to do pbuilder update with a different distribution
+target set up.
+
+.B "--distribution, " "--mirror, " "--othermirror"
+ options are only valid when
 .B "\-\-override\-config"
 option is specified in 
 .B "update"
@@ -185,27 +212,15 @@ target, or when
 .B "pbuilder create"
 is being called.
 
+
+\" 
+\" 
+\" 
 .TP
 .BI "\-\-http\-proxy [" "proxy" "]"
 Specifies the http proxy URL. Something like
 .B "http://xxx.xxx.xxx.xxx:8080/"
 should do. 
-.TP
-.BI "\-\-distribution [" "distribution" "]"
-Specifies the distribution used. Currently the supported values are
-.B "sid"
-.B "etch"
-.B "lenny"
-and 
-.B "experimental".
-
-This option is only effective for 
-.B "pbuilder create" 
-or when 
-.B "pbuilder update"
-is specified with 
-.B "\-\-override\-config"
-option.
 
 .TP
 .BI "\-\-aptcache [" "location of retrieved package files" "]"
@@ -214,34 +229,6 @@ be cached. Use
 .B "\-\-aptcache """""
 if you want caching to be turned off.
 
-.TP
-.BI "\-\-removepackages [" "packages to remove" "]"
-Removes the packages on creating the 
-.BR "base.tgz" "."
-Use this option to remove potentially dangerous or undesirable
-packages, like
-.B "lilo"
-which nobody will need to have inside a chroot.
-
-Packages should be specified in a space-delimited manner, 
-surrounded in double quotations, like 
-.B """lilo gcc mawk"""
-
-.TP
-.BI "\-\-extrapackages [" "packages to add" "]"
-Adds packages specified as an addition to the default,
-which is 
-.B "build-essential"
-by default.
-This is used in 
-.B "build"
-and 
-.B "create"
-(after successfully creating the initial chroot)
-and 
-.BR "update" .
-
-The packages should be specified as a space-delimited list.
 
 .TP
 .BI "\-\-configfile [" "configuration file to load" "]"
@@ -334,17 +321,6 @@ target.
 
 \" End of hookdir description
 
-
-.TP
-.BI "\-\-debemail [" "maintainer-name <email-address>" "]"
-
-Specifies that dpkg-buildpackage be called with
-.BI "-m" "maintainer-name <email-address>"
-instead of default value specified in the environment
-variable, or pbuilderrc
-
-.B "This option is almost obsolete, use \-\-debbuildopts instead"
-
 .TP
 .BI "\-\-debbuildopts [" "options" "]"
 
@@ -361,6 +337,110 @@ The messages generated during execution will be written to the specified file,
 and the standard output.
 
 .TP
+.BI "\-\-binary\-arch"
+
+Specify to build architecture specific targets instead of all targets.
+Setting
+.B "\-\-debbuildopts"
+after this option will re-set some parts of the effect.
+
+Use this option rather than using 
+.B "\-\-debbuildopts -B"
+
+.TP
+.BI "\-\-bindmounts " "bind-mount-points"
+Bind-mount the specified directories to inside the chroot.
+.I "bind-mount-points"
+is a space-delimited list of directories to bind-mount.
+
+.TP
+.BI "\-\-debootstrapopts " "\-\-variant=buildd"
+Add extra command-line options to debootstrap.
+
+Specify multiple options through multiple instance of this
+option, for example:
+
+.B "--debootstrapopts --arch=arm --debootstrapopts --variant=buildd"
+
+.TP
+.BI "\-\-debootstrap " "debootstrap"
+Use specified debootstrap implementation as debootstrap.
+Known implementations are
+.B cdebootstrap
+and
+.B debootstrap
+
+.TP
+.BI "\-\-save\-after\-login "
+.TP
+.BI "\-\-save\-after\-exec "
+Save the chroot image after exiting from the chroot instead of 
+deleting changes.
+Effective for 
+.B login
+and 
+.B execute
+session.
+
+
+.TP
+.BI "\-\-autocleanaptcache"
+Clean apt cache automatically, to run apt-get autoclean to only 
+keep the packages which are required for the version of Debian.
+This is useful when you keep a aptcache directory for each distribution
+and want to keep the size of the aptcache down.
+
+.TP
+.BI "\-\-help"
+
+Show a brief help message.
+
+.SH "MORE SPECIFIC OPTIONS"
+
+Some options are more involved to pbuilder internal than others. The
+following options are available.
+
+.TP
+.BI "\-\-removepackages [" "packages to remove" "]"
+Removes the packages on creating the 
+.BR "base.tgz" "."
+Use this option to remove potentially dangerous or undesirable
+packages, like
+.B "lilo"
+which nobody will need to have inside a chroot.
+
+Packages should be specified in a space-delimited manner, 
+surrounded in double quotations, like 
+.B """lilo gcc mawk"""
+
+.TP
+.BI "\-\-extrapackages [" "packages to add" "]"
+Adds packages specified as an addition to the default,
+which is 
+.B "build-essential"
+by default.
+This is used in 
+.B "build"
+and 
+.B "create"
+(after successfully creating the initial chroot)
+and 
+.BR "update" .
+
+The packages should be specified as a space-delimited list.
+
+
+.TP
+.BI "\-\-debemail [" "maintainer-name <email-address>" "]"
+
+Specifies that dpkg-buildpackage be called with
+.BI "-m" "maintainer-name <email-address>"
+instead of default value specified in the environment
+variable, or pbuilderrc
+
+.B "This option is almost obsolete, use \-\-debbuildopts instead"
+
+.TP
 .BI "\-\-pkgname\-logfile"
 Alternative option to 
 .B "\-\-logfile"
@@ -386,6 +466,7 @@ chroot.
 This option overrides other options, and may cause some inconsistency
 problems.
 
+
 .TP
 .BI "\-\-timeout [" "timeout in sleep time" "]"
 Time out building after sleeping set time.
@@ -395,25 +476,6 @@ in the command line.
 Default is no timeout.
 
 
-.TP
-.BI "\-\-override\-config"
-
-Specify to use different apt set up inside the chroot than it was used for creating the 
-base.tgz.
-Specify this when you want to do pbuilder update with a different distribution
-target set up.
-
-
-.TP
-.BI "\-\-binary\-arch"
-
-Specify to build architecture specific targets instead of all targets.
-Setting
-.B "\-\-debbuildopts"
-after this option will re-set some parts of the effect.
-
-Use this option rather than using 
-.B "\-\-debbuildopts -B"
 
 .TP
 .BI "\-\-no\-targz"
@@ -465,11 +527,6 @@ their build dependencies satisfied.
 It will clean up the build place on failure, 
 or after a successful build.
 
-.TP
-.BI "\-\-bindmounts " "bind-mount-points"
-Bind-mount the specified directories to inside the chroot.
-.I "bind-mount-points"
-is a space-delimited list of directories to bind-mount.
 
 .TP
 .BI "\-\-debug"
@@ -481,47 +538,6 @@ and try to avoid cleanup processing when error happens in
 .B create
 targets.
 
-.TP
-.BI "\-\-debootstrapopts " "\-\-variant=buildd"
-Add extra command-line options to debootstrap.
-
-Specify multiple options through multiple instance of this
-option, for example:
-
-.B "--debootstrapopts --arch=arm --debootstrapopts --variant=buildd"
-
-.TP
-.BI "\-\-debootstrap " "debootstrap"
-Use specified debootstrap implementation as debootstrap.
-Known implementations are
-.B cdebootstrap
-and
-.B debootstrap
-
-.TP
-.BI "\-\-save\-after\-login "
-.TP
-.BI "\-\-save\-after\-exec "
-Save the chroot image after exiting from the chroot instead of 
-deleting changes.
-Effective for 
-.B login
-and 
-.B execute
-session.
-
-
-.TP
-.BI "\-\-autocleanaptcache"
-Clean apt cache automatically, to run apt-get autoclean to only 
-keep the packages which are required for the version of Debian.
-This is useful when you keep a aptcache directory for each distribution
-and want to keep the size of the aptcache down.
-
-.TP
-.BI "\-\-help"
-
-Show a brief help message.
 
 
 .SH "FILES"
diff --git a/pbuilderrc.5 b/pbuilderrc.5
index f072cdf..bba11cc 100644
--- a/pbuilderrc.5
+++ b/pbuilderrc.5
@@ -10,27 +10,15 @@ program invocation.
 The file itself is sourced by a shell script, so
 it is required that the file conforms to shell script conventions.
 .SH "FORMAT"
+
 .TP
 .BI "BASETGZ=" "/var/cache/pbuilder/base.tgz"
 Specifies the default location for the archived 
 chroot image to be created and used.
 This is overridden with the option 
 .BR "--basetgz" "."
-.TP
-.BI "EXTRAPACKAGES=" """ccache linda XXX"""
-Specifies extra packages which the system should install
-in the chroot on 
-.BR "pbuilder create" "."
-This is a space-delimited list.
-Also this is installed on
-.B "pbuilder build"
 
 .TP
-.BI "export DEBIAN_BUILDARCH=" "athlon"
-Uses this variable as 
-.BR "DEBIAN_BUILDARCH" "."
-This trick can be used for other environmental variables as well.
-.TP
 .BI "BUILDPLACE=" "/var/cache/pbuilder/build/"
 The default place which the chroot is constructed.
 .B pbuilder
@@ -49,6 +37,18 @@ when doing such a thing.
 
 .B "pbuilder clean"
 cleans up this directory.
+
+.TP
+.BI "BUILDRESULT=" "/var/cache/pbuilder/result/"
+Specify the default directory which the build result will
+be copied over to after the building.
+
+Unlike
+.B "--buildresult"
+command-line option.
+The path is not canonicalized, so you should specify a full-path,
+not a relative path.
+
 .TP
 .BI "MIRRORSITE=" "http://www.jp.debian.org/debian"
 Specify the mirror site which contains the
@@ -84,42 +84,6 @@ To make changes on mirror site effective on
 needs to be specified.
 
 .TP
-.BI "export http_proxy=" "http://your-proxy:8080/"
-Defines the proxy for http connection.
-.TP
-.BI "USEPROC=" "yes"
-Specify 
-.B yes
-when it is desired to mount
-.B /proc
-interface. It is usually a good idea, since there are many
-software which fail miserably when there is no
-.B /proc
-being mounted.
-
-.TP
-.BI "USEDEVPTS=" "yes"
-Specify
-.B yes
-when it is desired to mount
-.B /dev/pts
-interface. It is usually a good idea, since there
-are many software which fail miserably when there is no
-.B /dev/pts
-being mounted.
-
-.TP
-.BI "BUILDRESULT=" "/var/cache/pbuilder/result/"
-Specify the default directory which the build result will
-be copied over to after the building.
-
-Unlike
-.B "--buildresult"
-command-line option.
-The path is not canonicalized, so you should specify a full-path,
-not a relative path.
-
-.TP
 .BI "DISTRIBUTION=" "sid"
 Specify the default distribution to use.
 This option only affects when doing
@@ -130,6 +94,11 @@ is specified for
 .B "pbuilder update" 
 option.
 
+
+.TP
+.BI "export http_proxy=" "http://your-proxy:8080/"
+Defines the proxy for http connection.
+
 .TP
 .BI "APTCACHE=" "/var/cache/pbuilder/aptcache"
 Specify the location that the packages downloaded by apt
@@ -148,12 +117,6 @@ It is advised to set this to
 if you are using user-mode-linux.
 
 .TP
-.BI "REMOVEPACKAGES=" "lilo"
-Specify the packages to be removed on creation of 
-.B base.tgz
-Leaving lilo in the chroot is like keeping a timebomb...
-
-.TP
 .BI "HOOKDIR=" "/usr/lib/pbuilder/hooks"
 Specifies the default location for the user hooks
 directory. 
@@ -170,6 +133,107 @@ For details, see
 .B "pbuilder.1"
 
 .TP
+.BI "DEBBUILDOPTS=" ""
+
+The options given here will be passed on to
+.BR dpkg-buildpackage .
+This can be useful e.g. for binary-only builds. The command-line option
+.B "--debbuildopts"
+overrides any contents specified here.
+The default value is to build source and binary package.
+
+
+.TP
+.BI "BINDMOUNTS=" "directories-to-bind-mount"
+When this value is set, pbuilder will mount these directories using
+bind-mount.
+
+Example:
+.B "BINDMOUNTS=""/home /mnt/test """
+
+Do not bind-mount 
+.B "/"
+
+.TP
+.BI "USE_PDEBUILD_INTERNAL=" "yes"
+When this option is set to
+.I yes
+.B "pdebuild-internal"
+implementation of 
+.B pdebuild
+is used.
+
+.TP
+.BI "DEBOOTSTRAPOPTS=" "'--variant=buildd'"
+When this option is set to 
+.B "--variant=buildd"
+.B "pbuilder"
+will invoke 
+.B "debootstrap" 
+with "--variant=buildd"
+option, which results in debootstrap creating a minimal chroot for 
+buildd instead of trying to create a minimal installation chroot.
+
+
+.TP
+.BI "DEBOOTSTRAP=" "debootstrap"
+Use this option to switch the implementation of
+debootstrap.
+Known implementations of debootstrap are 
+.B "cdebootstrap" 
+and
+.B "debootstrap"
+
+
+.TP
+.BI "EXTRAPACKAGES=" """ccache linda XXX"""
+Specifies extra packages which the system should install
+in the chroot on 
+.BR "pbuilder create" "."
+This is a space-delimited list.
+Also this is installed on
+.B "pbuilder build"
+
+.TP
+.BI "export DEBIAN_BUILDARCH=" "athlon"
+Uses this variable as 
+.BR "DEBIAN_BUILDARCH" "."
+This trick can be used for other environmental variables as well.
+
+
+
+
+.TP
+.BI "USEPROC=" "yes"
+Specify 
+.B yes
+when it is desired to mount
+.B /proc
+interface. It is usually a good idea, since there are many
+software which fail miserably when there is no
+.B /proc
+being mounted.
+
+.TP
+.BI "USEDEVPTS=" "yes"
+Specify
+.B yes
+when it is desired to mount
+.B /dev/pts
+interface. It is usually a good idea, since there
+are many software which fail miserably when there is no
+.B /dev/pts
+being mounted.
+
+
+.TP
+.BI "REMOVEPACKAGES=" "lilo"
+Specify the packages to be removed on creation of 
+.B base.tgz
+Leaving lilo in the chroot is like keeping a timebomb...
+
+
+.TP
 .BI "DEBEMAIL=" "Maintainer Name <Mail@Address>"
 
 If this was specified, 
@@ -185,15 +249,6 @@ The default configuration for
 .B pbuilder
 is empty for this value.
 
-.TP
-.BI "DEBBUILDOPTS=" ""
-
-The options given here will be passed on to
-.BR dpkg-buildpackage .
-This can be useful e.g. for binary-only builds. The command-line option
-.B "--debbuildopts"
-overrides any contents specified here.
-The default value is to build source and binary package.
 
 .TP
 .BI "BUILDSOURCEROOTCMD=" "fakeroot"
@@ -292,45 +347,6 @@ When this value is set to yes,
 will invoke debsign command after building.
 
 
-.TP
-.BI "BINDMOUNTS=" "directories-to-bind-mount"
-When this value is set, pbuilder will mount these directories using
-bind-mount.
-
-Example:
-.B "BINDMOUNTS=""/home /mnt/test """
-
-Do not bind-mount 
-.B "/"
-
-.TP
-.BI "USE_PDEBUILD_INTERNAL=" "yes"
-When this option is set to
-.I yes
-.B "pdebuild-internal"
-implementation of 
-.B pdebuild
-is used.
-
-.TP
-.BI "DEBOOTSTRAPOPTS=" "'--variant=buildd'"
-When this option is set to 
-.B "--variant=buildd"
-.B "pbuilder"
-will invoke 
-.B "debootstrap" 
-with "--variant=buildd"
-option, which results in debootstrap creating a minimal chroot for 
-buildd instead of trying to create a minimal installation chroot.
-
-.TP
-.BI "DEBOOTSTRAP=" "debootstrap"
-Use this option to switch the implementation of
-debootstrap.
-Known implementations of debootstrap are 
-.B "cdebootstrap" 
-and
-.B "debootstrap"
 
 .TP
 .BI "PKGNAME_LOGFILE_EXTENTION=" ".build"