1 files changed, 146 insertions, 0 deletions
diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
new file mode 100644
index 000000000..c81807279
--- /dev/null
+++ b/docs/dev/distributing.txt
@@ -0,0 +1,146 @@
+===============================
+ Docutils_ Distributor's Guide
+===============================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. contents::
+
+This document describes how to create packages of Docutils (e.g. for
+shipping with a Linux distribution).  If you have any questions,
+please direct them to the Docutils-develop_ mailing list.
+
+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
+
+
+Dependencies
+============
+
+Docutils has the following dependencies:
+
+* 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.
+
+* 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
+  distribution, ``optparse.py``, ``textwrap.py``, and ``roman.py``.
+  For Python 2.1/2.2, all of them must be installed (into the
+  ``site-packages/`` directory).  Python 2.3 and later versions have
+  ``textwrap`` and ``optparse`` included in the standard library, so
+  only ``roman.py`` is required here; installing the other files won't
+  hurt, though.
+
+  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
+============
+
+The Docutils Python files must be installed into the
+``site-packages/`` directory of Python.  Running ``python setup.py
+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 every
+time it's executed.
+
+
+Executables
+===========
+
+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
+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.
+
+
+Documentation
+=============
+
+The documentation should be generated using ``buildhtml.py``.  To
+generate HTML for all documentation files, go to the ``tools/``
+directory and run::
+
+    # Place html4css1.css in base directory.
+    cp ../docutils/writers/html4css1/html4css1.css ..
+    ./buildhtml.py --stylesheet-path=../html4css1.css ..
+
+Then install the following files to ``/usr/share/doc/docutils/`` (or
+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 directly to
+  ``/usr/share/doc/docutils/``; it's incomplete and would contain
+  invalid references!
+
+* The ``licenses/`` directory.
+
+* ``html4css1.css`` in the base directory.
+
+
+Removing the ``.txt`` Files
+---------------------------
+
+If you are tight with disk space, you can remove all ``.txt`` files in
+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.
+
+Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
+with the ``--no-source-link`` switch to avoid broken references to the
+source files.
+
+
+Other Files
+===========
+
+You may want to install the Emacs-Lisp files
+``tools/editors/emacs/*.el`` into the appropriate directory.
+
+
+Configuration File
+==================
+
+It is possible to have a system-wide configuration file at
+``/etc/docutils.conf``.  However, this is usually not necessary.  You
+should *not* install ``tools/docutils.conf`` into ``/etc/``.
+
+
+Tests
+=====
+
+While you probably do not need to ship the tests with your
+distribution, you can test your package by installing it and then
+running ``alltests.py`` from the ``tests/`` directory of the Docutils
+tarball.