split into smaller sections for improved readability

1 files changed, 55 insertions, 17 deletions

diff --git a/URPM.pm b/URPM.pm
index 3a9ddec..031e1af 100644
--- a/URPM.pm
+++ b/URPM.pm
@@ -306,6 +306,8 @@ and C<URPM::Transaction>.
 
 =head2 The URPM class
 
+=head3 Initialization
+
 =over 4
 
 =item URPM->new()
@@ -341,14 +343,14 @@ parse_synthesis()).
 
 Force the re-reading of the RPM configuration files.
 
-=item URPM::ranges_overlap($range1, $range2)
+=back
 
-This utility function compares two version ranges, in order to calculate
-dependencies properly. The ranges have roughly the form
+=head3 Loading packages data
 
-    [<|<=|==|=>|>] [epoch:]version[-release]
+$urpm->{depslist} is loaded when parsing sources (synthesis, hdlists or a plain
+rpm file).
 
-where epoch, version and release are RPM-style version numbers.
+=over
 
 =item $urpm->parse_synthesis($file [, callback => sub {...} ])
 
@@ -388,6 +390,21 @@ If C<keep_all_tags> isn't specified, URPM will drop all memory-consuming tags
 
 Callback signature is callback(URPM::Package).
 
+=back
+
+=head3 Searching packages
+
+=over
+
+=item URPM::ranges_overlap($range1, $range2)
+
+This utility function compares two version ranges, in order to calculate
+dependencies properly. The ranges have roughly the form
+
+    [<|<=|==|=>|>] [epoch:]version[-release]
+
+where epoch, version and release are RPM-style version numbers.
+
 =item $urpm->packages_providing($name)
 
 Returns a list of C<URPM::Package> providing <$name>
@@ -407,13 +424,19 @@ this $urpm. The behaviour of the search is influenced by several options:
 
 =item src => look only for srpms => 0 / 1
 
+=back
+
+=head3 Debuging
+
+These are used when faking a URPM::DB: $urpm can be used as-a $db
+
+=over
+
 =item $urpm->traverse($callback)
 
 Executes the callback for each package in the depslist, passing a
 C<URPM::Package> object as argument the callback.
 
-This is used when faking a URPM::DB: $urpm can be used as-a $db
-
 =item $urpm->traverse_tag($tag, $names, $callback)
 
 $tag may be one of C<name>, C<whatprovides>, C<whatrequires>, C<whatconflicts>,
@@ -424,8 +447,6 @@ Then, $callback is called for each matching package in the depslist.
 
 Callback signature is callback(URPM::Package).
 
-This is used when faking a URPM::DB: $urpm can be used as-a $db
-
 =item $urpm->traverse_tag_find($tag,$name,$callback)
 
 Quite similar to C<traverse_tag>, but stops when $callback returns true.
@@ -434,7 +455,11 @@ Quite similar to C<traverse_tag>, but stops when $callback returns true.
 
 Callback signature is callback(URPM::Package).
 
-This is used when faking a URPM::DB: $urpm can be used as-a $db
+=back
+
+=head3 Checking packages
+
+=over
 
 =item URPM::verify_rpm($file, %options)
 
@@ -460,13 +485,6 @@ Imports a key in the RPM database.
     block => '...'
     filename => '...'
 
-=item URPM::spec2srcheader($specfile)
-
-Returns a URPM::Package object containing the header of the source rpm produced
-by the evaluation of the specfile whose path is given as argument. All
-dependencies stored in this header are exactly the one needed to build the
-specfile.
-
 =back
 
 =head2 The URPM::DB class
@@ -526,6 +544,26 @@ specified DB.
 
 =head2 The URPM::Package class
 
+=head3 Getting a URPM::Package object
+
+URPM::Package objects are usually retrieved from $urpm->{depslist} after
+having loaded either the RPM DB and/or synthesis files.
+
+It's also possible to get such an object with:
+
+=over
+
+=item URPM::spec2srcheader($specfile)
+
+Returns a URPM::Package object containing the header of the source rpm produced
+by the evaluation of the specfile whose path is given as argument. All
+dependencies stored in this header are exactly the one needed to build the
+specfile.
+
+=back
+
+=head3 Methods
+
 Most methods of C<URPM::Package> are accessors for the various properties
 of an RPM package.