reorganize manpage ordering and contents

1 files changed, 144 insertions, 128 deletions

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"