Doc page reordered in a more logical order

dvarrazzo · dvarrazzo · commit ef2c7da4a52d · 2012-11-13T14:33:08.000Z
Requirements, Installation, Usage, Examples, etc.
diff --git a/doc/pg_repack.rst b/doc/pg_repack.rst
@@ -5,50 +5,13 @@ pg_repack -- Reorganize tables in PostgreSQL databases without any locks
     :depth: 1
     :backlinks: none
 
-Synopsis
---------
-
-::
-
-    pg_repack [OPTION]... [DBNAME]
-
-The following options can be specified in ``OPTIONS``. See also Options_ for
-details.
-
-Options:
-  -a, --all                 repack all databases
-  -n, --no-order            do vacuum full instead of cluster
-  -o, --order-by=COLUMNS    order by columns instead of cluster keys
-  -t, --table=TABLE         repack specific table only
-  -T, --wait-timeout=SECS   timeout to cancel other backends on conflict
-  -Z, --no-analyze          don't analyze at end
-
-Connection options:
-  -d, --dbname=DBNAME       database to connect
-  -h, --host=HOSTNAME       database server host or socket directory
-  -p, --port=PORT           database server port
-  -U, --username=USERNAME   user name to connect as
-  -w, --no-password         never prompt for password
-  -W, --password            force password prompt
-
-Generic options:
-  -e, --echo                echo queries
-  -E, --elevel=LEVEL        set output message level
-  --help                    show this help, then exit
-  --version                 output version information, then exit
-
-
-Description
------------
 
 pg_repack_ is an utility program to reorganize tables in PostgreSQL databases.
 Unlike clusterdb_, it doesn't block any selections and updates during
 reorganization.
 
-pg_repack is a fork of the previous pg_reorg_ project. It was founded to
-gather the bug fixes and new development ideas that the slow pace of
-development of pg_reorg was struggling to satisfy. Please check the `project
-page`_ for bug report and development information.
+pg_repack is a fork of the previous pg_reorg_ project. Please check the
+`project page`_ for bug report and development information.
 
 You can choose one of the following methods to reorganize:
 
@@ -68,24 +31,89 @@ NOTICE:
 .. _pg_reorg: http://reorg.projects.pgfoundry.org/
 
 
-Examples
---------
+Requirements
+------------
 
-Execute the following command to perform an online CLUSTER of all tables in
-test database::
+PostgreSQL versions
+    PostgreSQL 8.3, 8.4, 9.0, 9.1, 9.2
 
-    $ pg_repack test
+OS
+    RHEL 5.2, Windows XP SP3
 
-Execute the following command to perform an online VACUUM FULL to foo table in
-test database::
+Disks
+    Requires free disk space twice as large as the target table(s) and
+    indexes. For example, if the total size of the tables and indexes to be
+    reorganized is 1GB, an additional 2GB of disk space is required.
 
-    $ pg_repack --no-order --table foo -d test
 
+Installation
+------------
+
+pg_repack can be built with ``make`` on UNIX or Linux. The PGXS build
+framework is used automatically. Before building, you might need to install
+the PostgreSQL development packages (``postgresql-devel``, etc.) and add the
+directory containing ``pg_config`` to your ``$PATH``. Then you can run::
 
-Options
--------
+    $ cd pg_repack
+    $ make
+    $ sudo make install
+
+You can also use Microsoft Visual C++ 2010 to build the program on Windows.
+There are project files in the ``msvc`` folder.
+
+After installation, load the pg_repack extension in the database you want to
+process. On PostgreSQL 9.1 and following pg_repack is packaged as an
+extension, so you can execute::
+
+    $ psql -c "CREATE EXTENSION pg_repack" -d your_database
+
+For previous PostgreSQL versions you should load the script
+``$SHAREDIR/contrib/pg_repack.sql`` in the database to process; you can
+get ``$SHAREDIR`` using ``pg_config --sharedir``, e.g. ::
+
+    $ psql -f "$(pg_config --sharedir)/contrib/pg_repack.sql" -d your_database
+
+You can remove pg_repack from a PostgreSQL 9.1 and following database using
+``DROP EXTENSION pg_repack``. For previous Postgresql versions load the
+``$SHAREDIR/contrib/uninstall_pg_repack.sql`` script or just drop the
+``repack`` schema.
+
+If you are upgrading from a previous version of pg_repack or pg_reorg, just
+drop the old version from the database as explained above and install the new
+version.
+
+
+Usage
+-----
+
+::
+
+    pg_repack [OPTION]... [DBNAME]
+
+The following options can be specified in ``OPTIONS``.
+
+Options:
+  -a, --all                 repack all databases
+  -n, --no-order            do vacuum full instead of cluster
+  -o, --order-by=COLUMNS    order by columns instead of cluster keys
+  -t, --table=TABLE         repack specific table only
+  -T, --wait-timeout=SECS   timeout to cancel other backends on conflict
+  -Z, --no-analyze          don't analyze at end
+
+Connection options:
+  -d, --dbname=DBNAME       database to connect
+  -h, --host=HOSTNAME       database server host or socket directory
+  -p, --port=PORT           database server port
+  -U, --username=USERNAME   user name to connect as
+  -w, --no-password         never prompt for password
+  -W, --password            force password prompt
+
+Generic options:
+  -e, --echo                echo queries
+  -E, --elevel=LEVEL        set output message level
+  --help                    show this help, then exit
+  --version                 output version information, then exit
 
-pg_repack has the following command line options:
 
 Reorg Options
 ^^^^^^^^^^^^^
@@ -190,6 +218,20 @@ Environment
     .. __: http://www.postgresql.org/docs/current/static/libpq-envars.html
 
 
+Examples
+--------
+
+Execute the following command to perform an online CLUSTER of all tables in
+test database::
+
+    $ pg_repack test
+
+Execute the following command to perform an online VACUUM FULL to foo table in
+test database::
+
+    $ pg_repack --no-order --table foo -d test
+
+
 Diagnostics
 -----------
 
@@ -294,58 +336,6 @@ table. Then, it updates the system catalogs directly to swap the work table
 and the original one.
 
 
-Installation
-------------
-
-pg_repack can be built with ``make`` on UNIX or Linux. The PGXS build
-framework is used automatically. Before building, you might need to install
-the PostgreSQL development packages (``postgresql-devel``, etc.) and add the
-directory containing ``pg_config`` to your ``$PATH``. Then you can run::
-
-    $ cd pg_repack
-    $ make
-    $ sudo make install
-
-You can also use Microsoft Visual C++ 2010 to build the program on Windows.
-There are project files in the ``msvc`` folder.
-
-After installation, load the pg_repack extension in the database you want to
-process. On PostgreSQL 9.1 and following pg_repack is packaged as an
-extension, so you can execute::
-
-    $ psql -c "CREATE EXTENSION pg_repack" -d your_database
-
-For previous PostgreSQL versions you should load the script
-``$SHAREDIR/contrib/pg_repack.sql`` in the database to process; you can
-get ``$SHAREDIR`` using ``pg_config --sharedir``, e.g. ::
-
-    $ psql -f "$(pg_config --sharedir)/contrib/pg_repack.sql" -d your_database
-
-You can remove pg_repack from a PostgreSQL 9.1 and following database using
-``DROP EXTENSION pg_repack``. For previous Postgresql versions load the
-``$SHAREDIR/contrib/uninstall_pg_repack.sql`` script or just drop the
-``repack`` schema.
-
-If you are upgrading from a previous version of pg_repack or pg_reorg, just
-drop the old version from the database as explained above and install the new
-version.
-
-
-Requirements
-------------
-
-PostgreSQL versions
-    PostgreSQL 8.3, 8.4, 9.0, 9.1, 9.2
-
-OS
-    RHEL 5.2, Windows XP SP3
-
-Disks
-    Requires free disk space twice as large as the target table(s) and
-    indexes. For example, if the total size of the tables and indexes to be
-    reorganized is 1GB, an additional 2GB of disk space is required.
-
-
 Releases
 --------
 
