Added page titles to the documentation & adjusted section levels.

7 files changed, 123 insertions, 86 deletions

diff --git a/doc/distributed_bugtracking.txt b/doc/distributed_bugtracking.txt
index 1164c14..f3d574c 100644
--- a/doc/distributed_bugtracking.txt
+++ b/doc/distributed_bugtracking.txt
@@ -1,3 +1,7 @@
+***********************
+Distributed Bugtracking
+***********************
+
 Usage Cases
 ===========
 
diff --git a/doc/tutorial-email.txt b/doc/email.txt
index b25875f..b25875f 120000
--- a/doc/tutorial-email.txt
+++ b/doc/email.txt
diff --git a/doc/hacking.txt b/doc/hacking.txt
index 67be177..5b075f9 100644
--- a/doc/hacking.txt
+++ b/doc/hacking.txt
@@ -1,8 +1,9 @@
-Extending BE
-============
+**********
+Hacking BE
+**********
 
 Adding commands
----------------
+===============
 
 To write a plugin, you simply create a new file in the
 ``libbe/commands/`` directory.  Take a look at one of the simpler
@@ -17,7 +18,7 @@ be important.
 
 
 Command completion
-~~~~~~~~~~~~~~~~~~
+------------------
 
 BE implements a general framework to make it easy to support command
 completion for arbitrary plugins.  In order to support this system,
@@ -31,7 +32,7 @@ completion function from scratch.
 
 
 Adding user interfaces
-----------------------
+======================
 
 Take a look at ``libbe/ui/command_line.py`` for an example.  Basically
 you'll need to setup a ``UserInterface`` instance for running commands.
diff --git a/doc/tutorial-html.txt b/doc/html.txt
index 0822ebd..9e7f114 100644
--- a/doc/tutorial-html.txt
+++ b/doc/html.txt
@@ -1,3 +1,7 @@
+**************
+HTML Interface
+**************
+
 There's an interactive HTML interface in the works
 (http://bitbucket.org/sjl/cherryflavoredbugseverywhere/), but it's not
 ready for use as a public interface yet.
diff --git a/doc/index.txt b/doc/index.txt
index 0aca57c..55ee543 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -1,16 +1,35 @@
-.. bugs-everywhere documentation master file, created by
-   sphinx-quickstart on Fri Feb  5 20:02:21 2010.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Welcome to the bugs-everywhere documentation!
+=============================================
 
-Welcome to bugs-everywhere's documentation!
-===========================================
+Bugs Everywhere (BE) is a bugtracker built on distributed revision
+control.  It works with Arch_ , Bazaar_ , Darcs_ , Git_ , and
+Mercurial_ at the moment, but is easily extensible.  It can also
+function with no RCS at all.
+
+.. _Arch: http://www.gnu.org/software/gnu-arch/
+.. _Bazaar: http://bazaar.canonical.com/
+.. _Darcs: http://darcs.net/
+.. _Git: http://git-scm.com/
+.. _Mercurial: http://mercurial.selenic.com/
+
+The idea is to package the bug information with the source code, so
+that bugs can be marked "fixed" in the branches that fix them.  So,
+instead of numbers, bugs have globally unique ids.
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   tutorial.txt
+   ids.txt
+   email.txt
+   html.txt
+   distributed_bugtracking.txt
+   hacking.txt
+   spam.txt
+
+
 Indices and tables
 ==================
 
@@ -18,3 +37,56 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+Getting BE
+==========
+
+BE is available as a bzr repository::
+
+    $ bzr branch http://bzr.bugseverywhere.org/be
+
+See the homepage_ for details.  If you do branch the bzr repo, you'll
+need to run::
+
+    $ make
+
+to build some auto-generated files (e.g. ``libbe/_version.py``), and::
+
+    $ make install
+
+to install BE.  By default BE will install into your home directory,
+but you can tweak the ``PREFIX`` variable in ``Makefile`` to install
+to another location.
+
+.. _homepage: http://bugseverywhere.org/
+
+
+Getting started
+===============
+
+To get started, you must set the bugtracker root.  Typically, you will
+want to set the bug root to your project root, so that Bugs Everywhere
+works in any part of your project tree.::
+
+    $ be init -r $PROJECT_ROOT
+
+To create bugs, use ``be new $DESCRIPTION``.  To comment on bugs, you
+can can use ``be comment $BUG_ID``.  To close a bug, use
+``be close $BUG_ID`` or ``be status $BUG_ID fixed``.  For more
+commands, see ``be help``.  You can also look at the usage examples in
+``test_usage.sh``.
+
+Documentation
+=============
+
+If ``be help`` isn't scratching your itch, there's also
+
+* doc/tutorial        (a gentle introduction to BE)
+* doc/distributed_bugtracking  (notes on distributed workflows)
+* doc/spam            (notes on removing spam entries from VCSs)
+* doc/README.dev      (a guide to hacking BE)
+
+The documentation is marked up in reStructuredText_, so you can use
+the docutils_ to convert it to other formats if you desire.
+
+.. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _docutils: http://docutils.sourceforge.net/
diff --git a/doc/spam.txt b/doc/spam.txt
index 4d74580..c0a2ba3 100644
--- a/doc/spam.txt
+++ b/doc/spam.txt
@@ -1,3 +1,8 @@
+*****************
+Dealing with spam
+*****************
+
+
 Removing spam commits from the history
 ======================================
 
diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 5a91bcd..3dd7ff3 100644
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -1,8 +1,9 @@
+********
 Tutorial
-========
+********
 
 Introduction
-------------
+============
 
 Bugs Everywhere (BE) is a bugtracker built on distributed revision
 control.  The idea is to package the bug information with the source
@@ -21,11 +22,12 @@ tutorial will focus on the command-line interface as the most
 powerful, and leave the web and email interfaces to other documents.
 
 .. _command-line: `Command-line interface`_
-.. _web: ../doc/tutorial-html
-.. _email: ../doc/tutorial-email
+.. _web: tutorial-html.txt
+.. _email: tutorial-email.txt
+.. _IDs: ids.txt
 
 Installation
-------------
+============
 
 If your distribution packages BE, it will be easiest to use their package.
 For example, most Debian-based distributions support::
@@ -33,7 +35,7 @@ For example, most Debian-based distributions support::
     $ apt-get install bugs-everywhere
 
 Bugs
-----
+====
 
 If you have any problems with BE, you can look for matching bugs::
 
@@ -48,10 +50,10 @@ If your bug isn't listed, please open a new bug::
 
 
 Command-line interface
-----------------------
+======================
 
 Help
-~~~~
+----
 
 All of the following information elaborates on the command help text,
 which is stored in the code itself, and therefore more likely to be up
@@ -70,7 +72,7 @@ for example::
 will give help on the ``init`` command.
 
 Initialization
-~~~~~~~~~~~~~~
+--------------
 
 You're happily coding in your Arch_ / Bazaar_ / Darcs_ / Git_ /
 Mercurial_ versioned project and you discover a bug.  "Hmm, I'll need
@@ -110,7 +112,7 @@ comment IDs in this tutorial will start with ``bea/``.
 
 
 Creating bugs
-~~~~~~~~~~~~~
+-------------
 
 Create new bugs with::
 
@@ -136,7 +138,7 @@ developer understands what you want and when the bug can be considered
 fixed.
 
 Commenting on bugs
-~~~~~~~~~~~~~~~~~~
+------------------
 
 Bugs are like little mailing lists, and you can comment on the bug
 itself or previous comments, attach files, etc.  For example
@@ -172,7 +174,7 @@ the content and why you're attaching it, so the above should have been
 For more details, see ``be help comment``.
 
 Showing bugs
-~~~~~~~~~~~~
+------------
 
 Ok, you understand how to enter bugs, but how do you get that
 information back out?  If you know the ID of the item you're
@@ -227,7 +229,7 @@ entries around, scripting BE, etc.
     ...
 
 Listing bugs
-~~~~~~~~~~~~
+------------
 
 If you *don't* know which bug you're interested in, you can query
 the whole bug directory::
@@ -240,7 +242,7 @@ There are a whole slew of options for filtering the list of bugs.  See
 ``be help list`` for details.
 
 Showing changes
-~~~~~~~~~~~~~~~
+---------------
 
 Often you will want to see what's going on in another dev's branch or
 remind yourself what you've been working on recently.  All VCSs have
@@ -267,7 +269,7 @@ Compare your BE branch with the trunk::
     $ be diff --repo http://bugseverywhere.org/bugs/
 
 Manipulating bugs
-~~~~~~~~~~~~~~~~~
+-----------------
 
 There are several commands that allow to to set bug properties.  They
 are all fairly straightforward, so we will merely point them out here,
@@ -285,7 +287,7 @@ You can also remove bugs you feel are no longer useful with
 ``be remove``, and merge duplicate bugs with ``be merge``.
 
 Subscriptions
-~~~~~~~~~~~~~
+-------------
 
 Since BE bugs act as mini mailing lists, we provide ``be subscribe``
 as a way to manage change notification.  You can subscribe to all
@@ -309,7 +311,7 @@ only subscribe to the repository for which you have direct write
 access.
 
 Managing bug directories
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 ``be set`` lets you configure a bug directory.  You can set
 
@@ -330,7 +332,7 @@ For example, to set the current target to '1.2.3'::
     $ be set target $(be target --resolve '1.2.3')
 
 Import XML
-~~~~~~~~~~
+----------
 
 For serializing bug information (e.g. to email to a mailing list), use::
 
@@ -347,7 +349,7 @@ format for reading in your mail client.
 .. _mbox: http://en.wikipedia.org/wiki/Mbox
 
 Export HTML
-~~~~~~~~~~~
+-----------
 
 To create a static dump of your bug directory, use::
 
@@ -358,7 +360,7 @@ It works pretty well as the browsable part of a public interface using
 the email_ interface for interactive access.
 
 BE over HTTP
-~~~~~~~~~~~~
+------------
 
 Besides using BE to work directly with local VCS-based repositories,
 you can use::
@@ -376,7 +378,7 @@ dissable write access by using the ``--read-only`` option, which would
 make serving on a public network safer.
 
 Driving the VCS through BE
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Since BE uses internal storage drivers for its various backends, it
 seemed useful to provide a uniform interface to some of the common
@@ -384,59 +386,8 @@ functionality.  These commands are not intended to replace the usually
 much more powerful native VCS commands, but to provide an easy means
 of simple VCS-agnostic scripting for BE user interfaces, etc.
 
-Currently, we only expose ``be commit``, which commits all currently
-pending changes.
-
-
-IDs
----
-
-Format
+Commit
 ~~~~~~
 
-BE IDs are formatted::
-
-    <bug-directory>[/<bug>[/<comment>]]
-
-where each ``<..>`` is a UUID.  For example::
-
-    bea86499-824e-4e77-b085-2d581fa9ccab/3438b72c-6244-4f1d-8722-8c8d41484e35
-
-refers to bug ``3438b72c-6244-4f1d-8722-8c8d41484e35`` which is
-located in bug directory ``bea86499-824e-4e77-b085-2d581fa9ccab``.
-This is a bit of a mouthful, so you can truncate each UUID so long as
-it remains unique.  For example::
-
-    bea/343
-
-If there were two bugs ``3438...`` and ``343a...`` in ``bea``, you'd
-have to use::
-
-    bea/3438
-
-BE will only truncate each UUID down to three characters to slightly
-future-proof the short user ids.  However, if you want to save keystrokes
-and you *know* there is only one bug directory, feel free to truncate
-all the way to zero characters::
-
-    /3438
-
-Cross references
-~~~~~~~~~~~~~~~~
-
-To refer to other bug-directories/bugs/comments from bug comments, simply
-enclose the ID in pound signs (``#``).  BE will automatically expand the
-truncations to the full UUIDs before storing the comment, and the reference
-will be appropriately truncated (and hyperlinked, if possible) when the
-comment is displayed.
-
-Scope
-~~~~~
-
-Although bug and comment IDs always appear in compound references,
-UUIDs at each level are globally unique.  For example, comment
-``bea/343/ba96f1c0-ba48-4df8-aaf0-4e3a3144fc46`` will *only* appear
-under ``bea/343``.  The prefix (``bea/343``) allows BE to reduce
-caching global comment-lookup tables and enables easy error messages
-("I couldn't find ``bea/343/ba9`` because I don't know where the
-``bea`` bug directory is located").
+Currently, we only expose ``be commit``, which commits all currently
+pending changes.