Group options by purpose and add sub-headlines for each group.

The urpmi tools share a lot of options like download options, media
selections and so on. Other option groups are package selection,
output options (for urpmf, urpmq) and database options. Grouping them
makes it easier for the user to spot what she needs.

Additionally tool-specific groups will be put near the top of the
options section, while common groups will be put near the end of that
list, followed by rarely used stuff like debugging. This makes it easier
for the user to spot the tool-specific parts.

Grouping may not be perfect and some option may be in a group not
matching 100 percent. But anyway this should be a fairly good state.
followed

5 files changed, 585 insertions, 411 deletions

diff --git a/pod/8/urpmf.pod b/pod/8/urpmf.pod
index bff688d0..d63c7993 100644
--- a/pod/8/urpmf.pod
+++ b/pod/8/urpmf.pod
@@ -32,69 +32,57 @@ Prints a help message and exits.
 
 Prints the version number and exits.
 
-=item B<--env> I<directory>
+=item B<--verbose>
 
-Use a different environment directly out of a bug report tarball.
+Verbose mode. urpmf will emit various messages related to the parsing of
+media_info files for your media.
 
-=item B<--excludemedia> I<medium1,...,mediumN>
+=item B<--wait-lock>
 
-Do not use the given media.
+If the urpmi or rpm db is busy, wait until it is available
+
+=back
+
+=head2 Query Options
+
+=over
 
 =item B<-l>, B<--literal>
 
 Match literally instead of interpreting the argument as a regular
 expression.
 
-=item B<--media> I<medium1,...,mediumN>
+=item B<-i>
 
-Select specific media to be used, instead of defaulting to all available
-media (or all update media if B<--update> is used).
+Ignore case distinctions in the patterns that follow.
 
-=item B<--sortmedia> I<medium1,...,mediumN>
+=item B<-I>
 
-Sort the given media, substrings may be used to simplify grouping.
-This way, C<media1> will be taken into account first, then C<media2>, and
-so on. Media which aren't listed are taken into account after the others.
+Honor case distinctions in the patterns that follow. This is the default
+behaviour.
 
-=item B<--synthesis> I<file>
 
-Use the given synthesis file instead of urpmi db for searching packages.
+=back
 
-=item B<--use-distrib> I<directory>
+=head2 Output Options
 
-Use the given distribution tree instead of urpmi db for searching packages.
+=over
 
 =item B<--uniq>
 
 Do not print identical lines twice.
 
-=item B<--update>
-
-Use only update media. This means urpmf will only search through media
-marked as update.
-
-=item B<--urpmi-root> I<directory>
-
-Use the file system tree rooted for urpmi database and rpm install. Contrary
-to B<--root>, the urpmi configuration comes from the rooted tree.
-
-=item B<--verbose>
-
-Verbose mode. urpmf will emit various messages related to the parsing of
-media_info files for your media.
-
-=item B<--wait-lock>
 
-If the urpmi or rpm db is busy, wait until it is available
+=item B<-m>
 
-=item B<-i>
+Print the name of the media in which the
+package has been found.
 
-Ignore case distinctions in the patterns that follow.
+=item B<-f>
 
-=item B<-I>
+Print version, release and arch along with name
+of package. This modifies the effect of the I<--name> option.
 
-Honor case distinctions in the patterns that follow. This is the default
-behaviour.
 
 =item B<-F> I<string>
 
@@ -115,8 +103,7 @@ Prints the BuildHost tag.
 
 =item B<--buildtime>
 
-Prints the
-BuildTime tag.
+Prints the BuildTime tag.
 
 =item B<--conffiles>
 
@@ -200,15 +187,11 @@ Prints the packages' URL.
 
 Prints the Vendor tag.
 
-=item B<-m>
-
-Print the name of the media in which the
-package has been found.
+=back
 
-=item B<-f>
+=head2 Advanced Query Options
 
-Print version, release and arch along with name
-of package. This modifies the effect of the I<--name> option.
+=over
 
 =item B<-e>
 
@@ -240,6 +223,67 @@ Right parenthesis to close a group expression.
 
 Includes debugging output.
 
+
+=back
+
+=head2 Media Selection
+
+=over
+
+=item B<--excludemedia> I<medium1,...,mediumN>
+
+Do not use the given media.
+
+=item B<--media> I<medium1,...,mediumN>
+
+Select specific media to be used, instead of defaulting to all available
+media (or all update media if B<--update> is used).
+
+=item B<--sortmedia> I<medium1,...,mediumN>
+
+Sort the given media, substrings may be used to simplify grouping.
+This way, C<media1> will be taken into account first, then C<media2>, and
+so on. Media which aren't listed are taken into account after the others.
+
+=item B<--synthesis> I<file>
+
+Use the given synthesis file instead of urpmi db for searching packages.
+
+=item B<--use-distrib> I<directory>
+
+Use the given distribution tree instead of urpmi db for searching packages.
+
+=item B<--update>
+
+Use only update media. This means urpmf will only search through media
+marked as update.
+
+=back
+
+=head2 Database Options
+
+=over
+
+=item B<--urpmi-root> I<directory>
+
+Use the file system tree rooted for urpmi database and rpm install. Contrary
+to B<--root>, the urpmi configuration comes from the rooted tree.
+
+=item B<--wait-lock>
+
+If the urpmi or rpm db is busy, wait until it is available
+
+=back
+
+=head2 Debugging Options
+
+=over
+
+=item B<--env> I<directory>
+
+Use a different environment directly out of a bug report tarball.
+
+
 =back
 
 =head1 FORMAT
diff --git a/pod/8/urpmi.addmedia.pod b/pod/8/urpmi.addmedia.pod
index 4ccaf64f..0cc6fceb 100644
--- a/pod/8/urpmi.addmedia.pod
+++ b/pod/8/urpmi.addmedia.pod
@@ -82,44 +82,57 @@ machine (e.g. C<media/main>).
 
 =head1 OPTIONS
 
+=head2 Media Search and Selection
+
 =over
 
-=item B<--wget>
+=item B<--mirrorlist>
 
-Use wget only for downloading distant files. By default curl is used if
+Use the given url as a mirror list. It is quite special, please see examples
+at the beginning of this page.
+
+You can also give a space seperated list of urls. Each url can be either a
+mirrorlist or a mirror url. This is useful if you have a mirror to use inside
+a local network, but still use standard mirrors when the local mirror is not
 available.
 
-=item B<--curl>
 
-Use curl only for downloading distant files. This is the default if curl
-is available.
+nb: $MIRRORLIST is a special variable which gives the default URL for the
+current distribution/arch. $MIRRORLIST is the default mirrorlist.
 
-=item B<--curl-options> I<'options'>
+=item B<--zeroconf>
 
-=item B<--rsync-options> I<'options'>
+Find a media repository for the current distribution using zeroconf (DNS-SD).
+It can be used together with B<--distrib> or by specifying a media name and a
+path to the media directory, relative to the repository root.
 
-=item B<--wget-options> I<'options'>
+=item B<--distrib>
 
-Specify additional command-line options to be passed to curl, rsync or
-wget when retrieving files. If several options are to be passed, separate
-them with spaces and enclose them in quotes.
+Retrieve a set of media from a distribution. Typically, the URL provided
+to C<urpmi.addmedia> will represent the parent directory of a directory
+B<media>, which in turn will contain various subdirectories for each
+medium of the distribution. <I<name>> is combined with medium names found
+to create newer medium names in the urpmi database.
 
-Note that the rsync options will also be used for ssh media.
+=item B<--interactive>
 
-=item B<--limit-rate I<rate>>
+This option is to be used with B<--distrib>. With it, C<urpmi.addmedia>
+will ask for confirmation for each media it finds for the specified
+distribution.
 
-Try to limit the download speed, I<rate> is given in bytes/sec. This option
-is not active by default.
+=item B<--all-media>
 
-=item B<--proxy> I<proxyhost[:port|1080]>
+This option is to be used with B<--distrib>. With it, C<urpmi.addmedia>
+will attempt to add all media it finds. By default, it won't add media
+containing source rpms, or media corresponding to supplementary CD-ROMs
+on distributions.
 
-Use specified HTTP proxy.
 
-=item B<--proxy-user> I<user:password>
+=back
 
-Use specified user and password to use for proxy authentication.
-Specifying B<--proxy-user=ask> will cause C<urpmi.addmedia> to prompt for a
-username and a password.
+=head2 Media Handling
+
+=over
 
 =item B<--update>
 
@@ -149,70 +162,82 @@ Use synthesis file.
 
 Use rpm files (instead of synthesis).
 
-=item B<--mirrorlist>
 
-Use the given url as a mirror list. It is quite special, please see examples
-at the beginning of this page.
+=item B<--virtual>
 
-You can also give a space seperated list of urls. Each url can be either a
-mirrorlist or a mirror url. This is useful if you have a mirror to use inside
-a local network, but still use standard mirrors when the local mirror is not
+Creates a virtual medium: the medium is always up-to-date and so it does not
+need to be updated by C<urpmi.update>.
+
+=item B<--raw>
+
+Add the new media in the urpmi configuration file, but don't update it nor
+proceed to any download. The media, to be usable, will need to be updated
+with C<urpmi.update>; it's ignored until then.
+
+=item B<--nopubkey>
+
+Don't import pubkey of added media.
+
+
+=back
+
+=head2 Download Options
+
+=over
+
+=item B<--wget>
+
+Use wget only for downloading distant files. By default curl is used if
 available.
 
+=item B<--curl>
 
-nb: $MIRRORLIST is a special variable which gives the default URL for the
-current distribution/arch. $MIRRORLIST is the default mirrorlist.
+Use curl only for downloading distant files. This is the default if curl
+is available.
 
-=item B<--zeroconf>
+=item B<--curl-options> I<'options'>
 
-Find a media repository for the current distribution using zeroconf (DNS-SD).
-It can be used together with B<--distrib> or by specifying a media name and a
-path to the media directory, relative to the repository root.
+=item B<--rsync-options> I<'options'>
 
-=item B<--distrib>
+=item B<--wget-options> I<'options'>
 
-Retrieve a set of media from a distribution. Typically, the URL provided
-to C<urpmi.addmedia> will represent the parent directory of a directory
-B<media>, which in turn will contain various subdirectories for each
-medium of the distribution. <I<name>> is combined with medium names found
-to create newer medium names in the urpmi database.
+Specify additional command-line options to be passed to curl, rsync or
+wget when retrieving files. If several options are to be passed, separate
+them with spaces and enclose them in quotes.
 
-=item B<--interactive>
+Note that the rsync options will also be used for ssh media.
 
-This option is to be used with B<--distrib>. With it, C<urpmi.addmedia>
-will ask for confirmation for each media it finds for the specified
-distribution.
+=item B<--limit-rate I<rate>>
 
-=item B<--all-media>
+Try to limit the download speed, I<rate> is given in bytes/sec. This option
+is not active by default.
 
-This option is to be used with B<--distrib>. With it, C<urpmi.addmedia>
-will attempt to add all media it finds. By default, it won't add media
-containing source rpms, or media corresponding to supplementary CD-ROMs
-on distributions.
+=item B<--proxy> I<proxyhost[:port|1080]>
 
-=item B<--urpmi-root> I<directory>
+Use specified HTTP proxy.
 
-Use the file system tree rooted for urpmi database and rpm install. Contrary
-to B<--root>, the urpmi configuration comes from the rooted tree.
+=item B<--proxy-user> I<user:password>
 
-=item B<--wait-lock>
+Use specified user and password to use for proxy authentication.
+Specifying B<--proxy-user=ask> will cause C<urpmi.addmedia> to prompt for a
+username and a password.
 
-If the urpmi or rpm db is busy, wait until it is available
 
-=item B<--virtual>
+=back
 
-Creates a virtual medium: the medium is always up-to-date and so it does not
-need to be updated by C<urpmi.update>.
+=head2 Database Options
 
-=item B<--raw>
+=over
 
-Add the new media in the urpmi configuration file, but don't update it nor
-proceed to any download. The media, to be usable, will need to be updated
-with C<urpmi.update>; it's ignored until then.
+=item B<--urpmi-root> I<directory>
 
-=item B<--nopubkey>
+Use the file system tree rooted for urpmi database and rpm install. Contrary
+to B<--root>, the urpmi configuration comes from the rooted tree.
+
+=item B<--wait-lock>
+
+If the urpmi or rpm db is busy, wait until it is available
 
-Don't import pubkey of added media.
 
 =back
 
diff --git a/pod/8/urpmi.pod b/pod/8/urpmi.pod
index 205d7188..3fc9a7ad 100644
--- a/pod/8/urpmi.pod
+++ b/pod/8/urpmi.pod
@@ -59,6 +59,23 @@ example when the ftp archive changes) use C<urpmi.update>.
 
 Prints a help message and exit.
 
+=item B<--force>
+
+Assume yes on all questions.
+
+=item B<-q>, B<--quiet>
+
+Quiet mode: when calling rpm no upgrade status is printed.
+
+=item B<-v>, B<--verbose>
+
+Proposes a verbose mode with various messages.
+
+=back
+
+=head2 Media Selection
+
+=over
 
 =item B<--media> I<media1,...,mediaN>
 
@@ -93,9 +110,19 @@ Use the specified synthesis file instead of the urpmi database for
 searching packages and resolving dependencies. This option is mostly
 designed for internal use.
 
-=item B<--auto>
+=item B<--use-distrib> I<directory>
 
-Install all required dependencies without asking.
+Configure urpmi on the fly from a distrib tree, useful to install a chroot
+with the B<--root> option. See the description of the B<--distrib> option
+in the C<urpmi.addmedia> manpage.
+
+
+
+=back
+
+=head2 Operation Modes
+
+=over
 
 =item B<--auto-select>
 
@@ -112,6 +139,90 @@ C<urpmi.update>.
 
 Remove all orphans without asking (see also C<urpme --auto-orphans>)
 
+
+=back
+
+=head2 Package Selection
+
+=over
+
+=item B<--auto>
+
+Install all required dependencies without asking.
+
+
+=item B<-y>, B<--fuzzy>
+
+Disable fast search on exact package name; that means that urpmi will
+propose all packages matching part of the name, even if one of them
+matches exactly the specified name.
+
+=item B<--buildrequires>
+
+Select all the C<BuildRequires> of the wanted source packages.
+(You can also install the build dependencies read directly from an rpm spec file.)
+
+=item B<--install-src>
+
+Install only the source package (that is, no binary packages will be
+installed). You don't need to be root to use this option (if you have
+write access to your rpm build top directory).
+
+
+=item B<--no-recommends>
+
+With this option, urpmi will not install "suggested" packages.
+By default, urpmi will install (newly) suggested packages.
+
+=item B<--allow-suggests>
+
+With this option, urpmi will install "suggested" packages.
+This is useful if you have C<no-recommends> in urpmi.cfg.
+
+
+=item B<--strict-arch>
+
+Upgrade only packages if the newer version has the same architecture as
+the one installed. Mostly useful on machines that support several
+architectures (32 and 64 bit).
+
+=item B<-a>
+
+If multiple packages match the given substring, install them all.
+
+=item B<-p>
+
+Allow search in provides to find the package (this is the default).
+
+=item B<-P>
+
+Do not search in provides to find package (this is the opposite of B<-p>).
+
+
+=item B<--skip> I<pattern,...>
+
+You can specify a list of packages which installation should be skipped.
+You can also include patterns between //, just like in
+F</etc/urpmi/skip.list> (see urpmi.files(5)).
+
+=item B<--prefer> I<pattern,...>
+
+You can specify a list of packages which installation should be preferred
+(especially useful with B<--auto>).
+You can also include patterns between //, just like in
+F</etc/urpmi/prefer.list> (see urpmi.files(5)).
+
+=item B<--more-choices>
+
+When several packages are found, propose more choices than the default.
+
+
+=back
+
+=head2 Package Processing
+
+=over
+
 =item B<--no-md5sum>
 
 Disable MD5SUM file checking when updating media.
@@ -149,23 +260,6 @@ Split urpmi's operation in small transactions of at
 least I<count> packages. The default is 8 and setting this value to 0 just
 disables splitting in small transactions.
 
-=item B<-y>, B<--fuzzy>
-
-Disable fast search on exact package name; that means that urpmi will
-propose all packages matching part of the name, even if one of them
-matches exactly the specified name (this is the same as B<-y>).
-
-=item B<--buildrequires>
-
-Select all the C<BuildRequires> of the wanted source packages. 
-(You can also install the build dependencies read directly from an rpm spec file.)
-
-=item B<--install-src>
-
-Install only the source package (that is, no binary packages will be
-installed). You don't need to be root to use this option (if you have
-write access to your rpm build top directory).
-
 =item B<--clean>
 
 Remove all packages from the cache in directory F</var/cache/urpmi/rpms>.
@@ -175,40 +269,6 @@ Remove all packages from the cache in directory F</var/cache/urpmi/rpms>.
 Do not remove any package from the cache in directory
 F</var/cache/urpmi/rpms>.
 
-=item B<--force>
-
-Assume yes on all questions.
-
-=item B<-q>, B<--quiet>
-
-Quiet mode: when calling rpm no upgrade status is printed.
-
-=item B<-v>, B<--verbose>
-
-Proposes a verbose mode with various messages.
-
-=item B<--debug>
-
-Proposes a very verbose mode.
-
-=item B<--debug-librpm>
-
-Proposes a very verbose mode (similar to rpm -vv)
-
-=item B<--deploops>
-
-Print warnings when packages cannot be ordered properly due to dependancy loops.
-
-=item B<--no-recommends>
-
-With this option, urpmi will not install "suggested" packages. 
-By default, urpmi will install (newly) suggested packages.
-
-=item B<--allow-suggests>
-
-With this option, urpmi will install "suggested" packages. 
-This is useful if you have C<no-recommends> in urpmi.cfg.
-
 =item B<--justdb>
 
 Update only the database, not the filesystem.
@@ -238,33 +298,6 @@ this case.
 When used when B<--auto>, do not suppress all questions, but still ask the
 user for medium changes (e.g. insertion of CD-ROMs).
 
-=item B<--parallel> I<alias>
-
-Activate distributed execution of urpmi to other machines (it is mandatory
-that urpmi is installed, but it is not necessary to have media defined on
-any machines). I<alias> defines which extension module is to be used by
-urpmi (currently, C<urpmi-parallel-ka-run> or C<urpmi-parallel-ssh> are
-available) and which machines should be updated. This alias is defined in
-the file F</etc/urpmi/parallel.cfg> as described in the L<urpmi.files>
-manpage.
-
-=item B<--root> I<directory>
-
-Use the file system tree rooted for rpm install. All operations and
-scripts will run after chroot(2). The rpm database that lies in the rooted
-tree will be used, but the urpmi configuration comes from the normal
-system.
-
-=item B<--urpmi-root> I<directory>
-
-Use the file system tree rooted for urpmi database and rpm install. Contrary
-to B<--root>, the urpmi configuration comes from the rooted tree.
-
-=item B<--use-distrib> I<directory>
-
-Configure urpmi on the fly from a distrib tree, useful to install a chroot
-with the B<--root> option. See the description of the B<--distrib> option
-in the C<urpmi.addmedia> manpage.
 
 =item B<--download-all> I<dest-dir>
 
@@ -274,58 +307,6 @@ option is set, urpmi will first download all the needed packages and proceed
 to install them if it managed to download them all. You can optionally 
 specify a directory where the files should be downloaded (default is /var/cache/urpmi which could be too small to hold all the files).
 
-=item B<--downloader> I<program name>
-
-Use a specific program for downloading distant files via http or ftp. 
-By default curl is used if available, or wget instead.
-
-=item B<--curl-options> I<'options'>
-
-=item B<--rsync-options> I<'options'>
-
-=item B<--wget-options> I<'options'>
-
-Specify additional command-line options to be passed to curl, rsync or
-wget when retrieving files. If several options are to be passed, separate
-them with spaces and enclose them in quotes.
-
-Note that the rsync options will also be used for ssh media (since it's
-actually rsync over ssh).
-
-=item B<--limit-rate> I<rate>
-
-Try to limit the download speed. I<rate> is given in bytes/sec. This
-option is not active by default.
-
-=item B<--resume>
-
-Resume transfer of partially-downloaded files.
-
-=item B<--retry> I<times>
-
-Retries to download files over FTP or HTTP the specified number
-of times.
-
-=item B<--proxy> I<proxyhost[:port]>
-
-Use specified HTTP proxy.
-
-=item B<--proxy-user> I<user:password>
-
-Use specified user and password to use for proxy authentication.
-Specifying B<--proxy-user=ask> will cause urpmi to prompt for a username
-and a password.
-
-=item B<--bug> I<directory>
-
-Create a bug report in I<directory>. You have to send a compressed archive
-of the directory to the urpmi maintainer for the bug being (probably)
-reproduced. See L</"BUG REPORTS"> below.
-
-=item B<--env> I<directory>
-
-Use a different environment directly from a bug report to replay a bug.
-The argument is the same argument given to B<--bug> option.
 
 =item B<--verify-rpm>
 
@@ -368,22 +349,26 @@ This is equivalent to C<rpm --noscripts>.
 Ignore file conflicts.
 This is equivalent to C<rpm --replacefiles>.
 
-=item B<--skip> I<pattern,...>
 
-You can specify a list of packages which installation should be skipped.
-You can also include patterns between //, just like in
-F</etc/urpmi/skip.list> (see urpmi.files(5)).
 
-=item B<--prefer> I<pattern,...>
 
-You can specify a list of packages which installation should be preferred
-(especially useful with B<--auto>).
-You can also include patterns between //, just like in
-F</etc/urpmi/prefer.list> (see urpmi.files(5)).
+=back
 
-=item B<--more-choices>
+=head2 Database Options
 
-When several packages are found, propose more choices than the default.
+=over
+
+=item B<--root> I<directory>
+
+Use the file system tree rooted for rpm install. All operations and
+scripts will run after chroot(2). The rpm database that lies in the rooted
+tree will be used, but the urpmi configuration comes from the normal
+system.
+
+=item B<--urpmi-root> I<directory>
+
+Use the file system tree rooted for urpmi database and rpm install. Contrary
+to B<--root>, the urpmi configuration comes from the rooted tree.
 
 =item B<--nolock>
 
@@ -394,23 +379,94 @@ B<--root>.
 
 If the urpmi or rpm db is busy, wait until it is available
 
-=item B<--strict-arch>
 
-Upgrade only packages if the newer version has the same architecture as
-the one installed. Mostly useful on machines that support several
-architectures (32 and 64 bit).
+=back
 
-=item B<-a>
+=head2 Download Options
 
-If multiple packages match the given substring, install them all.
+=over
 
-=item B<-p>
+=item B<--parallel> I<alias>
 
-Allow search in provides to find the package (this is the default).
+Activate distributed execution of urpmi to other machines (it is mandatory
+that urpmi is installed, but it is not necessary to have media defined on
+any machines). I<alias> defines which extension module is to be used by
+urpmi (currently, C<urpmi-parallel-ka-run> or C<urpmi-parallel-ssh> are
+available) and which machines should be updated. This alias is defined in
+the file F</etc/urpmi/parallel.cfg> as described in the L<urpmi.files>
+manpage.
 
-=item B<-P>
+=item B<--downloader> I<program name>
+
+Use a specific program for downloading distant files via http or ftp.
+By default curl is used if available, or wget instead.
+
+=item B<--curl-options> I<'options'>
+
+=item B<--rsync-options> I<'options'>
+
+=item B<--wget-options> I<'options'>
+
+Specify additional command-line options to be passed to curl, rsync or
+wget when retrieving files. If several options are to be passed, separate
+them with spaces and enclose them in quotes.
+
+Note that the rsync options will also be used for ssh media (since it's
+actually rsync over ssh).
+
+=item B<--limit-rate> I<rate>
+
+Try to limit the download speed. I<rate> is given in bytes/sec. This
+option is not active by default.
+
+=item B<--resume>
+
+Resume transfer of partially-downloaded files.
+
+=item B<--retry> I<times>
+
+Retries to download files over FTP or HTTP the specified number
+of times.
+
+=item B<--proxy> I<proxyhost[:port]>
+
+Use specified HTTP proxy.
+
+=item B<--proxy-user> I<user:password>
+
+Use specified user and password to use for proxy authentication.
+Specifying B<--proxy-user=ask> will cause urpmi to prompt for a username
+and a password.
+
+=back
+
+=head2 Debugging Options
+
+=over
+
+=item B<--debug>
+
+Proposes a very verbose mode.
+
+=item B<--debug-librpm>
+
+Proposes a very verbose mode (similar to rpm -vv)
+
+=item B<--deploops>
+
+Print warnings when packages cannot be ordered properly due to dependancy loops.
+
+=item B<--bug> I<directory>
+
+Create a bug report in I<directory>. You have to send a compressed archive
+of the directory to the urpmi maintainer for the bug being (probably)
+reproduced. See L</"BUG REPORTS"> below.
+
+=item B<--env> I<directory>
+
+Use a different environment directly from a bug report to replay a bug.
+The argument is the same argument given to B<--bug> option.
 
-Do not search in provides to find package (this is the opposite of B<-p>).
 
 =back
 
diff --git a/pod/8/urpmi.update.pod b/pod/8/urpmi.update.pod
index 134ef97a..cd059646 100644
--- a/pod/8/urpmi.update.pod
+++ b/pod/8/urpmi.update.pod
@@ -24,25 +24,10 @@ Force update of GPG key.
 Don't update media, but mark them as ignored (that is, disables them).
 B<--no-ignore> has the reverse behaviour: it marks the media as enabled.
 
-=item B<--limit-rate I<rate>>
-
-Try to limit the download speed, I<rate> is given in bytes/sec. This
-option is not active by default.
-
 =item B<--no-md5sum>
 
 Disable MD5SUM file checking.
 
-=item B<--proxy> I<proxyhost[:port|1080]>
-
-Use specified HTTP proxy.
-
-=item B<--proxy-user> I<user:password>
-
-Use specified user and password to use for proxy authentication.
-Specifying B<--proxy-user=ask> will cause urpmi.update to prompt for a
-username and a password.
-
 =item B<--urpmi-root> I<directory>
 
 Use the file system tree rooted for urpmi database and rpm install. Contrary
@@ -56,6 +41,37 @@ If the urpmi or rpm db is busy, wait until it is available
 
 Use only update media.
 
+=item B<-a>
+
+Select all enabled non-static media to update them.
+
+=item B<-f>
+
+Force updating synthesis
+
+=item B<-ff>
+
+Really force updating synthesis
+
+=item B<--probe-rpms>
+
+Do not use synthesis, use rpm files directly
+
+=item B<-q>
+
+Quiet mode.
+
+=item B<-v>
+
+Verbose mode.
+
+
+=back
+
+=head2 Download Options
+
+=over
+
 =item B<--curl>
 
 Use curl for downloading distant
@@ -78,29 +94,21 @@ them with spaces and enclose them in quotes.
 
 Note that the rsync options will also be used for ssh media.
 
-=item B<-a>
-
-Select all enabled non-static media to update them.
-
-=item B<-f>
-
-Force updating synthesis
-
-=item B<-ff>
-
-Really force updating synthesis
+=item B<--proxy> I<proxyhost[:port|1080]>
 
-=item B<--probe-rpms>
+Use specified HTTP proxy.
 
-Do not use synthesis, use rpm files directly
+=item B<--proxy-user> I<user:password>
 
-=item B<-q>
+Use specified user and password to use for proxy authentication.
+Specifying B<--proxy-user=ask> will cause urpmi.update to prompt for a
+username and a password.
 
-Quiet mode.
+=item B<--limit-rate I<rate>>
 
-=item B<-v>
+Try to limit the download speed, I<rate> is given in bytes/sec. This
+option is not active by default.
 
-Verbose mode.
 
 =back
 
diff --git a/pod/8/urpmq.pod b/pod/8/urpmq.pod
index 577505a1..33fed7db 100644
--- a/pod/8/urpmq.pod
+++ b/pod/8/urpmq.pod
@@ -24,6 +24,21 @@ according to the command-line options that were used:
 
 Prints a help message and exit.
 
+=item B<-v>, B<--verbose>
+
+Activate verbose mode.
+
+
+=item B<--force>
+
+Continue when requesting packages that are not available.
+
+=back
+
+=head2 Operation Modes
+
+=over
+
 =item B<--list>
 
 List available packages.
@@ -46,38 +61,13 @@ List available nodes for parallel installation (when using B<--parallel>).
 
 List available parallel aliases.
 
-=item B<--update>
-
-Use only update media. This means that urpmq will search and resolve
-dependencies only in media marked as containing updates (e.g. which have
-been created with C<urpmi.addmedia --update>).
-
-=item B<--media> I<media1,...,mediaN>
-
-Select specific media to be used, instead of defaulting
-to all available media (or all update media if B<--update> is used).
-No rpm will be found in other media.
-
-=item B<--excludemedia> I<media1,...,mediaN>
-
-Do not use the specified media.
-
-=item B<--searchmedia> I<media>
-
-Use only the specified media to search for packages that are specified on
-the command-line, or which are found when using B<--auto-select>.
-Dependencies of those packages can still be found in other media.
 
-=item B<--sortmedia> I<media1,...,mediaN>
 
-Sort the specified media. Substrings may be used to simplify grouping.
-This way, C<media1> will be taken into account first, then C<media2>, and
-so on. Media which aren't listed are taken into account after the others.
+=back
 
-=item B<--synthesis> I<file>
+=head2 Package Selection
 
-Use the specified synthesis file instead of the urpmi database for
-searching packages and resolving dependencies.
+=over
 
 =item B<--auto-select>
 
@@ -127,97 +117,70 @@ Like B<-y>/B<--fuzzy>, but forces to match case-insensitively.
 Search a source package
 matching I<name> and it will select all dependencies by default.
 
-=item B<--sources>
-
-Prints source URLs (or file names) of all selected
-packages.
-
-=item B<--force>
-
-Continue when requesting packages that are not available.
-
 =item B<--ignorearch>
 
 Allow to search packages whose architecture isn't compatible with the
 architecture of the host.
 
-=item B<--parallel> I<alias>
+=item B<-u>
 
-Activate distributed execution of urpmi to other machines (it is mandatory
-that urpmi is installed but it is not necessary to have media defined on
-any machines). I<alias> defines which extension module to use by urpmi
-(currently urpmi-parallel-ka-run or urpmi-parallel-ssh) and which
-machines should be updated, this alias is defined in the file
-F</etc/urpmi/parallel.cfg> as described below.
+Deselect packages if a better version is already installed.
 
-=item B<--root> I<directory>
+=item B<-m>
 
-Use the file system tree rooted for rpm install. All operations and
-scripts will run after chroot(2). The rpm database in the rooted tree
-will be used but urpmi configuration comes from normal system.
+Equivalent to B<-du>.
 
-=item B<--urpmi-root> I<directory>
+=item B<-a>
 
-Use the file system tree rooted for urpmi database and rpm install. Contrary
-to B<--root>, the urpmi configuration comes from the rooted tree.
+Select all matches on command line; that's useful when one gives an
+incomplete package name and when using B<-f> or B<-r>.
 
-=item B<--wget>
+=item B<-c>
 
-Use wget for downloading distant files. By default curl
-is used if available, or wget instead.
+If maximal closure is used, assume that a package listed may have wrong or
+not up-to-date dependencies. This causes more packages to be upgraded and
+may correct unresolved dependencies on the rpm database.
 
-=item B<--curl>
 
-Use curl for downloading distant files. By default curl is used if
-available, or wget instead.
+=item B<-p>, B<--whatprovides>
 
-=item B<--curl-options> I<'options'>
+Search in provides to find package.
 
-=item B<--rsync-options> I<'options'>
+=item B<--whatrequires>
 
-=item B<--wget-options> I<'options'>
+Reverse search to what requires the package given.
 
-Specify additional command-line options to be passed to curl, rsync or
-wget when retrieving files. If several options are to be passed, separate
-them with spaces and enclose them in quotes.
+=item B<--whatrequires-recursive>
 
-Note that the rsync options will also be used for ssh media.
+Reverse search to what requires recursively the package given
+(looking through virtual packages).
 
-=item B<--proxy> I<proxyhost[:port|1080]>
+=back
 
-Use specified HTTP proxy.
+=head2 Output Options
 
-=item B<--proxy-user> I<user:password>
+=over
 
-Use specified user and password to use for proxy authentication.
-Specifying B<--proxy-user=ask> will cause urpmq to prompt for a username
-and a password.
 
-=item B<--use-distrib> I<directory>
+=item B<-i>
 
-Configure urpmq on the fly from a distribution tree.
+Prints useful information in human readable form, as for I<rpm -qi>.
 
-=item B<--env> I<directory>
+=item B<-g>
 
-Use a different environment directly from a bug report to replay a bug.
-The argument is the same argument given to B<--bug> option.
+Prints groups of each package listed.
 
-=item B<--skip> I<pattern,...>
+=item B<-r>
 
-You can specify a list of packages which installation should be skipped.
-You can also include patterns between //, just like in
-F</etc/urpmi/skip.list> (see urpmi.files(5)).
+Prints also version and release of each package listed.
 
-=item B<--prefer> I<pattern,...>
+=item B<-f>
 
-You can specify a list of packages which installation should be preferred
-(especially useful with B<--auto>).
-You can also include patterns between //, just like in
-F</etc/urpmi/prefer.list> (see urpmi.files(5)).
+Prints also version, release and arch of each package listed.
 
-=item B<--wait-lock>
+=item B<-l>
 
-If the urpmi or rpm db is busy, wait until it is available
+Lists files in packages.
 
 =item B<--changelog>
 
@@ -243,6 +206,11 @@ Prints the package requires.
 
 Prints the package suggests.
 
+=item B<--sources>
+
+Prints source URLs (or file names) of all selected
+packages.
+
 =item B<--sourcerpm>
 
 Prints the sourcerpm of the package
@@ -251,65 +219,138 @@ Prints the sourcerpm of the package
 
 Prints concise information about the package.
 
-=item B<-v>, B<--verbose>
+=item B<-d>, B<--requires-recursive>
 
-Activate verbose mode.
+Print dependencies (maximal closure).
 
-=item B<-u>
 
-Deselect packages if a better version is already installed.
+=back
 
-=item B<-m>
+=head2 Media Selection
 
-Equivalent to B<-du>.
+=over
 
-=item B<-a>
+=item B<--update>
 
-Select all matches on command line; that's useful when one gives an
-incomplete package name and when using B<-f> or B<-r>.
+Use only update media. This means that urpmq will search and resolve
+dependencies only in media marked as containing updates (e.g. which have
+been created with C<urpmi.addmedia --update>).
 
-=item B<-c>
+=item B<--media> I<media1,...,mediaN>
 
-If maximal closure is used, assume that a package listed may have wrong or
-not up-to-date dependencies. This causes more packages to be upgraded and
-may correct unresolved dependencies on the rpm database.
+Select specific media to be used, instead of defaulting
+to all available media (or all update media if B<--update> is used).
+No rpm will be found in other media.
 
-=item B<-d>, B<--requires-recursive>
+=item B<--excludemedia> I<media1,...,mediaN>
 
-Print dependencies (maximal closure).
+Do not use the specified media.
 
-=item B<-p>, B<--whatprovides>
+=item B<--searchmedia> I<media>
 
-Search in provides to find package.
+Use only the specified media to search for packages that are specified on
+the command-line, or which are found when using B<--auto-select>.
+Dependencies of those packages can still be found in other media.
 
-=item B<--whatrequires>
+=item B<--sortmedia> I<media1,...,mediaN>
 
-Reverse search to what requires the package given.
+Sort the specified media. Substrings may be used to simplify grouping.
+This way, C<media1> will be taken into account first, then C<media2>, and
+so on. Media which aren't listed are taken into account after the others.
 
-=item B<--whatrequires-recursive>
+=item B<--synthesis> I<file>
 
-Reverse search to what requires recursively the package given
-(looking through virtual packages).
+Use the specified synthesis file instead of the urpmi database for
+searching packages and resolving dependencies.
 
-=item B<-i>
+=item B<--parallel> I<alias>
 
-Prints useful information in human readable form, as for I<rpm -qi>.
+Activate distributed execution of urpmi to other machines (it is mandatory
+that urpmi is installed but it is not necessary to have media defined on
+any machines). I<alias> defines which extension module to use by urpmi
+(currently urpmi-parallel-ka-run or urpmi-parallel-ssh) and which
+machines should be updated, this alias is defined in the file
+F</etc/urpmi/parallel.cfg> as described below.
 
-=item B<-g>
+=item B<--root> I<directory>
 
-Prints groups of each package listed.
+Use the file system tree rooted for rpm install. All operations and
+scripts will run after chroot(2). The rpm database in the rooted tree
+will be used but urpmi configuration comes from normal system.
 
-=item B<-r>
+=item B<--urpmi-root> I<directory>
 
-Prints also version and release of each package listed.
+Use the file system tree rooted for urpmi database and rpm install. Contrary
+to B<--root>, the urpmi configuration comes from the rooted tree.
 
-=item B<-f>
 
-Prints also version, release and arch of each package listed.
+=item B<--use-distrib> I<directory>
 
-=item B<-l>
+Configure urpmq on the fly from a distribution tree.
+
+=item B<--skip> I<pattern,...>
+
+You can specify a list of packages which installation should be skipped.
+You can also include patterns between //, just like in
+F</etc/urpmi/skip.list> (see urpmi.files(5)).
+
+=item B<--prefer> I<pattern,...>
+
+You can specify a list of packages which installation should be preferred
+(especially useful with B<--auto>).
+You can also include patterns between //, just like in
+F</etc/urpmi/prefer.list> (see urpmi.files(5)).
+
+
+=back
+
+=head2 Download Options
+
+=over
+
+=item B<--wget>
+
+Use wget for downloading distant files. By default curl
+is used if available, or wget instead.
+
+=item B<--curl>
+
+Use curl for downloading distant files. By default curl is used if
+available, or wget instead.
+
+=item B<--curl-options> I<'options'>
+
+=item B<--rsync-options> I<'options'>
+
+=item B<--wget-options> I<'options'>
+
+Specify additional command-line options to be passed to curl, rsync or
+wget when retrieving files. If several options are to be passed, separate
+them with spaces and enclose them in quotes.
+
+Note that the rsync options will also be used for ssh media.
+
+=item B<--proxy> I<proxyhost[:port|1080]>
+
+Use specified HTTP proxy.
+
+=item B<--proxy-user> I<user:password>
+
+Use specified user and password to use for proxy authentication.
+Specifying B<--proxy-user=ask> will cause urpmq to prompt for a username
+and a password.
+
+=back
+
+=head2 Debugging Options
+
+=over
+
+=item B<--env> I<directory>
+
+Use a different environment directly from a bug report to replay a bug.
+The argument is the same argument given to B<--bug> option.
 
-Lists files in packages.
 
 =back