Merged initial Sphinx documentation structure.

There's still a long way to go in this direction, but the basic
framework is now in place.  Toss in numpydoc-style docstrings 
  http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
when you have time, and things will gradually improve over time.

I also punted our user ID creation/parsing in libbe.ui.util.user to
the email module.  This way IDs are handled in an RFC-compliant way
(less suprising for users) and by someone else (less work for us :).

15 files changed, 579 insertions, 125 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..6d7bbc5
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,94 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = .build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+	@echo "  libbe     to autogenerate files for all libbe modules"
+
+clean:
+	-rm -rf $(BUILDDIR) libbe
+
+html: libbe
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml: libbe
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle: libbe
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json: libbe
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp: libbe
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp: libbe
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/bugs-everywhere.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/bugs-everywhere.qhc"
+
+latex: libbe
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes: libbe
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck: libbe
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest: libbe
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY : libbe
+libbe :
+	python generate-libbe-txt.py
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..1090a28
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,198 @@
+# -*- coding: utf-8 -*-
+#
+# bugs-everywhere documentation build configuration file, created by
+# sphinx-quickstart on Fri Feb  5 20:02:21 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
+
+import libbe.version
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
+              'numpydoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'bugs-everywhere'
+copyright = u'2010, W. Trevor King'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = libbe.version.version()
+# The full version, including alpha/beta/rc tags.
+release = libbe.version.version()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['.build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'bugs-everywheredoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'bugs-everywhere.tex', u'bugs-everywhere Documentation',
+   u'W. Trevor King', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff --git a/doc/distributed_bugtracking b/doc/distributed_bugtracking.txt
index 1164c14..5ca42a6 100644
--- a/doc/distributed_bugtracking
+++ b/doc/distributed_bugtracking.txt
@@ -1,29 +1,40 @@
+***********************
+Distributed Bugtracking
+***********************
+
 Usage Cases
 ===========
 
 Case 1: Tracking the status of bugs in remote repo branches
 -----------------------------------------------------------
 
-See discussion in
-  #bea86499-824e-4e77-b085-2d581fa9ccab/12c986be-d19a-4b8b-b1b5-68248ff4d331#
+See the discussion in
+#bea86499-824e-4e77-b085-2d581fa9ccab/12c986be-d19a-4b8b-b1b5-68248ff4d331#.
 Here, it doesn't matter whether the remote repository is a branch of
 the local repository, or a completely separate project
 (e.g. upstream, ...).  So long as the remote project provides access
-via some REPO format, you can use
-  be --repo REPO ...
-to run your query, or
-  be diff REPO
+via some REPO format, you can use::
+
+    $ be --repo REPO ...
+
+to run your query, or::
+
+    $ be diff REPO
+
 to see the changes between the local and remote repositories.
 
 
 Case 2: Importing bugs from other repositories
 ----------------------------------------------
 
-Case 2.1: If the remote repository is a branch of the local repository
-  VCS merge REPO
+Case 2.1: If the remote repository is a branch of the local repository::
+
+     $ <VCS> merge <REPO>
+
 Case 2.2: If the remote repository is not a branch of the local repository
-  Hypothetical command:
-    be import REPO ID
+(Hypothetical command)::
+
+    $ be import <REPO> <ID>
 
 
 Notes
@@ -42,5 +53,5 @@ Managing permissions
 
 Many bugtrackers implement some sort of permissions system, and they
 are certainly required for a central system with diverse user roles.
-However DVCSs also support the 'pull my changes' workflow, where
+However DVCSs also support the "pull my changes" workflow, where
 permissions are irrelevant.
diff --git a/doc/doc.txt b/doc/doc.txt
new file mode 100644
index 0000000..e1b7a3a
--- /dev/null
+++ b/doc/doc.txt
@@ -0,0 +1,23 @@
+****************************
+Producing this documentation
+****************************
+
+This documentation is written in reStructuredText_, and produced
+using Sphinx_ and the numpydoc_ extension.  The documentation source
+should be fairly readable without processing, but you can compile the
+documentation, you'll need to install Sphinx and numpydoc::
+
+    $ easy_install Sphinx
+    $ easy_install numpydoc
+
+.. _Sphinx: http://sphinx.pocoo.org/
+.. _numpydoc: http://pypi.python.org/pypi/numpydoc
+
+See the reStructuredText quick reference and the `NumPy/SciPy
+documentation guide`_ for an introduction to the documentation
+syntax.
+
+.. _reStructuredText:
+  http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _NumPy/SciPy documentation guide:
+  http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
diff --git a/doc/tutorial-email b/doc/email.txt
index b25875f..b25875f 120000
--- a/doc/tutorial-email
+++ b/doc/email.txt
diff --git a/doc/generate-libbe-txt.py b/doc/generate-libbe-txt.py
new file mode 100644
index 0000000..35eb5c4
--- /dev/null
+++ b/doc/generate-libbe-txt.py
@@ -0,0 +1,52 @@
+#!/usr/bin/python
+#
+# Copyright
+
+"""Auto-generate reStructuredText of the libbe module tree for Sphinx.
+"""
+
+import sys
+import os, os.path
+
+sys.path.insert(0, os.path.abspath('..'))
+from test import python_tree
+
+def title(modname):
+    t = ':mod:`%s`' % modname
+    delim = '*'*len(t)
+    return '\n'.join([delim, t, delim, '', ''])
+
+def automodule(modname):
+    return '\n'.join([
+            '.. automodule:: %s' % modname,
+            '   :members:',
+            '   :undoc-members:',
+            '', ''])
+
+def toctree(children):
+    if len(children) == 0:
+        return ''
+    return '\n'.join([
+            '.. toctree::',
+            '   :maxdepth: 2',
+            '',
+            ] + [
+            '   %s.txt' % c for c in sorted(children)
+            ] + ['', ''])
+
+def make_module_txt(modname, children):
+    filename = os.path.join('libbe', '%s.txt' % modname)
+    if not os.path.exists('libbe'):
+        os.mkdir('libbe')
+    if os.path.exists(filename):
+        return None # don't overwrite potentially hand-written files.
+    f = file(filename, 'w')
+    f.write(title(modname))
+    f.write(automodule(modname))
+    f.write(toctree(children))
+    f.close()
+
+if __name__ == '__main__':
+    pt = python_tree(root_path='../libbe', root_modname='libbe')
+    for node in pt.traverse():
+        make_module_txt(node.modname, [c.modname for c in node])
diff --git a/doc/README.dev b/doc/hacking.txt
index 67be177..5b075f9 100644
--- a/doc/README.dev
+++ 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 b/doc/html.txt
index 0822ebd..9e7f114 100644
--- a/doc/tutorial-html
+++ 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
new file mode 100644
index 0000000..30b0318
--- /dev/null
+++ b/doc/index.txt
@@ -0,0 +1,39 @@
+Welcome to the bugs-everywhere documentation!
+=============================================
+
+Bugs Everywhere (BE) is a bugtracker built on distributed version
+control.  It works with Arch_, Bazaar_, Darcs_, Git_, and Mercurial_
+at the moment, but is easily extensible.  It can also function with no
+VCS 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.
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   install.txt
+   tutorial.txt
+   email.txt
+   html.txt
+   distributed_bugtracking.txt
+   hacking.txt
+   spam.txt
+   libbe/libbe.txt
+   doc.txt
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/install.txt b/doc/install.txt
new file mode 100644
index 0000000..b1d153e
--- /dev/null
+++ b/doc/install.txt
@@ -0,0 +1,55 @@
+*************
+Installing BE
+*************
+
+Bazaar repository
+=================
+
+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/
+
+
+Release tarballs
+================
+
+For those not interested in the cutting edge, or those who don't want
+to worry about installing Bazaar, we'll post release tarballs somewhere
+(once we actually make a release).  After you've downloaded the release
+tarball, unpack it with::
+
+    $ tar -xzvf be-<VERSION>.tar.gz
+
+And install it with:::
+
+    $ cd be-<VERSION>
+    $ make install
+
+
+Distribution packages
+=====================
+
+Some distributions (Debian_ , Ubuntu_ , others?) package BE.  If
+you're running one of those distributions, you can install the package
+with your regular package manager.  For Debian, Ubuntu, and related
+distros, that's::
+
+    $ apt-get install bugs-everywhere
+
+.. _Debian: http://packages.debian.org/sid/bugs-everywhere
+.. _Ubuntu: http://packages.ubuntu.com/lucid/bugs-everywhere
diff --git a/doc/src/be.1.sgml b/doc/man/be.1.sgml
index a2df21f..a2df21f 100644
--- a/doc/src/be.1.sgml
+++ b/doc/man/be.1.sgml
diff --git a/doc/src/module.mk b/doc/man/module.mk
index ea4eacc..ea4eacc 100644
--- a/doc/src/module.mk
+++ b/doc/man/module.mk
diff --git a/doc/spam b/doc/spam
deleted file mode 100644
index 4d74580..0000000
--- a/doc/spam
+++ /dev/null
@@ -1,34 +0,0 @@
-Removing spam commits from the history
-======================================
-
-arch bzr darcs git hg none
-
-In the case that some spam or inappropriate comment makes its way
-through you interface, you can remove the offending commit XYZ with:
-
-  If the offending commit is the last commit:
-
-    arch:  
-    bzr:   bzr uncommit && bzr revert
-    darcs: darcs obliterate --last=1
-    git:   git reset --hard HEAD^
-    hg:    hg rollback && hg revert
-
-  If the offending commit is not the last commit:
-
-    arch:  
-    bzr:   bzr rebase -r <XYZ+1>..-1 --onto before:XYZ .
-      (requires bzr-rebase plugin, note, you have to increment XYZ by
-      hand for <XYZ+1>, because bzr does not support "after:XYZ".)
-    darcs: darcs obliterate --matches 'name XYZ'
-    git:   git rebase --onto XYZ~1 XYZ
-    hg:     -not-supported-
-      (From http://hgbook.red-bean.com/read/finding-and-fixing-mistakes.html#id394667
-      "Mercurial also does not provide a way to make a file or
-      changeset completely disappear from history, because there is no
-      way to enforce its disappearance")
-
-Note that all of these _change_the_repo_history_, so only do this on
-your interface-specific repo before it interacts with any other repo.
-Otherwise, you'll have to survive by cherry-picking only the good
-commits.
diff --git a/doc/spam.txt b/doc/spam.txt
new file mode 100644
index 0000000..39e7a86
--- /dev/null
+++ b/doc/spam.txt
@@ -0,0 +1,60 @@
+*****************
+Dealing with spam
+*****************
+
+In the case that some spam or inappropriate comment makes its way
+through you interface, you can (sometimes) remove the offending commit
+``XYZ``.
+
+
+If the offending commit is the last commit
+==========================================
+
++-------+----------------------------+
+| arch  |                            |
++-------+----------------------------+
+| bzr   | bzr uncommit && bzr revert |
++-------+----------------------------+
+| darcs | darcs obliterate --last=1  |
++-------+----------------------------+
+| git   | git reset --hard HEAD^     |
++-------+----------------------------+
+| hg    | hg rollback && hg revert   |
++-------+----------------------------+
+
+If the offending commit is not the last commit
+==============================================
+
++----------+-----------------------------------------------+
+| arch     |                                               |
++----------+-----------------------------------------------+
+| bzr [#]_ | bzr rebase -r <XYZ+1>..-1 --onto before:XYZ . |
++----------+-----------------------------------------------+
+| darcs    | darcs obliterate --matches 'name XYZ'         |
++----------+-----------------------------------------------+
+| git      | git rebase --onto XYZ~1 XYZ                   |
++----------+-----------------------------------------------+
+| hg [#]_  |                                               |
++----------+-----------------------------------------------+
+
+.. [#] Requires the ```bzr-rebase`` plugin`_.  Note, you have to
+   increment ``XYZ`` by hand for ``<XYZ+1>``, because ``bzr`` does not
+   support ``after:XYZ``.
+
+.. [#] From `Mercurial: The Definitive Guide`:
+
+     "Mercurial also does not provide a way to make a file or
+     changeset completely disappear from history, because there is no
+     way to enforce its disappearance"
+
+.. _bzr-rebase plugin: http://wiki.bazaar.canonical.com/Rebase
+.. _Mercurial: The Definitive Guide:
+  http://hgbook.red-bean.com/read/finding-and-fixing-mistakes.html#id394667
+
+Warnings about changing history
+===============================
+
+Note that all of these *change the repo history* , so only do this on
+your interface-specific repo before it interacts with any other repo.
+Otherwise, you'll have to survive by cherry-picking only the good
+commits.
diff --git a/doc/tutorial b/doc/tutorial.txt
index 5a91bcd..7932c9c 100644
--- a/doc/tutorial
+++ 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: libbe/libbe.util.id.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.