tweaks, clarifications, corrections

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@3559 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 39 insertions, 27 deletions

diff --git a/docutils/docs/dev/distributing.txt b/docutils/docs/dev/distributing.txt
index 05aa4f2c6..0a2e25d2b 100644
--- a/docutils/docs/dev/distributing.txt
+++ b/docutils/docs/dev/distributing.txt
@@ -15,11 +15,11 @@
 .. contents::
 
 This document describes how to create packages of Docutils (e.g. for
-shipping them with a Linux distribution).  If you have any questions,
+shipping with a Linux distribution).  If you have any questions,
 please direct them to the Docutils-develop_ mailing list.
 
-First of all, please download the most current `release tarball`_ and
-unpack it.
+First, please download the most current `release tarball`_ and unpack
+it.
 
 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
 .. _release tarball: http://docutils.sourceforge.net/#download
@@ -30,15 +30,15 @@ Dependencies
 
 Docutils has the following dependencies:
 
-* Python 2.1 or later is required.  (While the compiler package from
+* Python 2.1 or later is required.  While the compiler package from
   the Tools/ directory of Python's source distribution must be
   installed for the test suite to pass with Python 2.1, the
   functionality available to end users should be available without the
-  compiler package as well.  So just use >= Python 2.1 in the
-  dependencies.)
+  compiler package as well.  So just use ">= Python 2.1" in the
+  dependencies.
 
-* Docutils may optionally make use of the PIL (Python Imaging
-  Library).  If PIL is present, it is automatically detected by
+* Docutils may optionally make use of the PIL (`Python Imaging
+  Library`).  If PIL is present, it is automatically detected by
   Docutils.
 
 * There are three files in the ``extras/`` directory of the Docutils
@@ -52,6 +52,8 @@ Docutils has the following dependencies:
   These files are automatically installed by the setup script (when
   calling "python setup.py install").
 
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
 
 Python Files
 ============
@@ -62,17 +64,17 @@ install`` should do the trick, but if you want to place the files
 yourself, you can just install the ``docutils/`` directory of the
 Docutils tarball to ``/usr/lib/python/site-packages/docutils/``.  In
 this case you should also compile the Python files to ``.pyc`` and/or
-``.pyo`` files so that Docutils doesn't need to be recompiled
-everytime it's executed.
+``.pyo`` files so that Docutils doesn't need to be recompiled every
+time it's executed.
 
 
-Binaries
-========
+Executables
+===========
 
-The binaries are located in the ``tools/`` directory of the Docutils
-tarball.
+The executable front-end tools are located in the ``tools/`` directory
+of the Docutils tarball.
 
-The ``rst2*.py`` tools except ``rst2newlatex.py`` are intended for
+The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
 end-users.  You should install them to ``/usr/bin/``.  You do not need
 to change the names (e.g. to ``docutils-rst2html.py``) because the
 ``rst2`` prefix is unique.
@@ -81,25 +83,34 @@ to change the names (e.g. to ``docutils-rst2html.py``) because the
 Documentation
 =============
 
-The documentation should be generated using ``buildhtml.py``.  Go to
-the ``tools/`` directory and run ``./buildhtml.py ..``.  This will
-create all HTML files.
+The documentation should be generated using ``buildhtml.py``.  To
+generate HTML for all documentation files, go to the ``tools/``
+directory and run::
+
+    ./buildhtml.py ..
 
 Then install the following files to ``/usr/share/doc/docutils/`` (or
-however you like to call the documentation directory):
+wherever you install documentation):
 
 * All ``.html`` and ``.txt`` files in the base directory.
-* The ``docs/`` directory.  (Do not install the contents of the
-  ``docs/`` directory directory directly to
-  ``/usr/share/doc/docutils/``\ —it's incomplete and would contain
-  invalid references!)
+
+* The ``docs/`` directory.
+
+  Do not install the contents of the ``docs/`` directory directly to
+  ``/usr/share/doc/docutils/`` —- it's incomplete and would contain
+  invalid references!
+
 * The ``licenses/`` directory.
+
 * ``tools/stylesheets/default.css``, creating the ``tools/`` and
   ``tools/stylesheets/`` directory beforehand.  This file is needed
-  for correct viewing of the HTML files.  (You do not need to install
-  the other contents of the ``tools/`` or ``stylesheets/`` directory.
-  However, do not install ``default.css`` right into the documentation
-  base directory, or the references to the stylesheet will not work.)
+  for correct viewing of the HTML files.  The remaining contents of
+  the ``tools/`` and ``tools/stylesheets/`` directories are not
+  needed.
+
+  Be sure not to install ``default.css`` into the root of the
+  documentation directory, or the relative references to the
+  stylesheet will not work.
 
 
 Removing the ``.txt`` Files
@@ -110,6 +121,7 @@ the tree except for:
 
 * those in the ``licenses/`` directory because they have not been
   processed to HTML and
+
 * ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
   be readable in source form.