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

1 files changed, 87 insertions, 62 deletions

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