Merge with Trevor.

14 files changed, 1054 insertions, 43 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.txt b/doc/distributed_bugtracking.txt
new file mode 100644
index 0000000..5ca42a6
--- /dev/null
+++ b/doc/distributed_bugtracking.txt
@@ -0,0 +1,57 @@
+***********************
+Distributed Bugtracking
+***********************
+
+Usage Cases
+===========
+
+Case 1: Tracking the status of bugs in remote repo branches
+-----------------------------------------------------------
+
+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
+
+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.2: If the remote repository is not a branch of the local repository
+(Hypothetical command)::
+
+    $ be import <REPO> <ID>
+
+
+Notes
+=====
+
+Providing public repositories
+-----------------------------
+
+e.g. for non-dev users.  These are just branches that expose a public
+interface (HTML, email, ...).  Merge and query like any other
+development branch.
+
+
+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
+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/email.txt b/doc/email.txt
new file mode 120000
index 0000000..b25875f
--- /dev/null
+++ b/doc/email.txt
@@ -0,0 +1 @@
+../interfaces/email/interactive/README
\ No newline at end of file
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/hacking.txt b/doc/hacking.txt
new file mode 100644
index 0000000..5b075f9
--- /dev/null
+++ b/doc/hacking.txt
@@ -0,0 +1,75 @@
+**********
+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
+plugins (e.g. ``remove.py``) for an example of how that looks, and to
+start getting a feel for the libbe interface.
+
+See ``libbe/commands/base.py`` for the definition of the important
+classes ``Option``, ``Argument``, ``Command``, ``InputOutput``,
+``StorageCallbacks``, and ``UserInterface`` classes.  You'll be
+subclassing ``Command`` for your command, but all those classes will
+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,
+any of your completable ``Argument()`` instances (in your command's
+``.options`` or ``.args``) should be initialized with some valid
+completion_callback function.  Some common cases are defined in
+``libbe.command.util``.  If you need more flexibility, see
+``libbe.command.list``'s ``--sort`` option for an example of
+extensions via ``libbe.command.util.Completer``, or write a custom
+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.
+More details to come after I write an HTML UI...
+
+
+Testing
+=======
+
+Run any tests in your module with::
+
+    be$ python test.py <python.module.name>
+
+for example:
+
+    be$ python test.py libbe.command.merge
+
+For a definition of "any tests", see ``test.py``'s
+``add_module_tests()`` function.
+
+Note that you will need to run ``make`` before testing a clean BE
+branch to auto-generate required files like ``libbe/_version.py``.
+
+
+Profiling
+=========
+
+Find out which 20 calls take the most cumulative time (time of
+execution + childrens' times)::
+
+    $ python -m cProfile -o profile be [command] [args]
+    $ python -c "import pstats; p=pstats.Stats('profile'); p.sort_stats('cumulative').print_stats(20)"
+
+It's often useful to toss::
+
+    import sys, traceback
+    print >> sys.stderr, '-'*60, '\n', '\n'.join(traceback.format_stack()[-10:])
+
+into expensive functions (e.g. ``libbe.util.subproc.invoke()``) if
+you're not sure why they're being called.
diff --git a/doc/html.txt b/doc/html.txt
new file mode 100644
index 0000000..9e7f114
--- /dev/null
+++ b/doc/html.txt
@@ -0,0 +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/be.1.sgml b/doc/man/be.1.sgml
index a2df21f..a2df21f 100644
--- a/doc/be.1.sgml
+++ b/doc/man/be.1.sgml
diff --git a/doc/module.mk b/doc/module.mk
deleted file mode 100644
index 7791f48..0000000
--- a/doc/module.mk
+++ /dev/null
@@ -1,43 +0,0 @@
-# :vim: filetype=make : -*- makefile; coding: utf-8; -*-
-
-# doc/module.mk
-# Part of Bugs Everywhere, a distributed bug tracking system.
-#
-# Copyright (C) 2008-2009 Chris Ball <cjb@laptop.org>
-#                         W. Trevor King <wking@drexel.edu>
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License along
-# with this program; if not, write to the Free Software Foundation, Inc.,
-# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-
-# Makefile module for documentation
-
-MODULE_DIR := doc
-
-MANPAGES = be.1
-manpage_files = $(patsubst %,${MODULE_DIR}/%,${MANPAGES})
-
-GENERATED_FILES += ${manpage_files}
-
-
-.PHONY: doc
-doc: man
-
-build: doc
-
-
-.PHONY: man
-man: ${manpage_files}
-
-%.1: %.1.sgml
-	docbook-to-man $< > $@
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.txt b/doc/tutorial.txt
new file mode 100644
index 0000000..7932c9c
--- /dev/null
+++ b/doc/tutorial.txt
@@ -0,0 +1,393 @@
+********
+Tutorial
+********
+
+Introduction
+============
+
+Bugs Everywhere (BE) is a bugtracker built on distributed revision
+control.  The idea is to package the bug information with the source
+code, so that developers working on the code can make appropriate
+changes to the bug repository as they go.  For example, by marking a
+bug as "fixed" and applying the fixing changes in the same commit.
+This makes it easy to see what's been going on in a particular branch
+and helps keep the bug repository in sync with the code.
+
+However, there are some differences compared to centralized
+bugtrackers.  Because bugs and comments can be created by several
+users in parallel, they have globally unique IDs_ rather than numbers.
+There is also a developer-friendly command-line_ interface to
+compliment the user-friendly web_ and email_ interfaces.  This
+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: 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::
+
+    $ apt-get install bugs-everywhere
+
+Bugs
+====
+
+If you have any problems with BE, you can look for matching bugs::
+
+    $ be --repo http://bugseverywhere.org/bugs list
+
+If your bug isn't listed, please open a new bug::
+
+    $ be --repo http://bugseverywhere.org/bugs new 'bug'
+    Created bug with ID bea/abc
+    $ be --repo http://bugseverywhere.org/bugs comment bea/def
+    <editor spawned for comments>
+
+
+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
+to date.  You can get a list of commands and topics with::
+
+    $ be help
+
+Or see specific help on ``COMMAND`` with
+
+    $ be help COMMAND
+
+for example::
+
+    $ be help init
+
+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
+a simple way to track these things", you think.  This is where BE
+comes in.  One of the benefits of distributed versioning systems is
+the ease of repository creation, and BE follows this trend.  Just
+type::
+
+    $ be init
+    Using <VCS> for revision control.
+    BE repository initialized.
+
+in your project's root directory.  This will create a ``.be``
+directory containing the bug repository and notify your VCS so it will
+be versioned starting with your next commit.  See::
+
+    $ be help init
+
+for specific details about where the ``.be`` directory will end up
+if you call it from a directory besides your project's root.
+
+.. _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/
+
+Inside the ``.be`` directory (among other things) there will be a long
+UUID_ directory.  This is your bug directory.  The idea is that you
+could keep several bug directories in the same repository, using one
+to track bugs, another to track roadmap issues, etc.  See IDs_ for
+details.  For BE itself, the bug directory is
+``bea86499-824e-4e77-b085-2d581fa9ccab``, which is why all the bug and
+comment IDs in this tutorial will start with ``bea/``.
+
+.. _UUID: http://en.wikipedia.org/wiki/Universally_Unique_Identifier
+
+
+Creating bugs
+-------------
+
+Create new bugs with::
+
+    $ be new <SUMMARY>
+
+For example::
+
+    $ be new 'Missing demuxalizer functionality'
+    Created bug with ID bea/28f
+
+If you are entering a bug reported by another person, take advantage
+of the ``--reporter`` option to give them credit::
+
+    $ be new --reporter 'John Doe <jdoe@example.com>' 'Missing whatsit...'
+    Created bug with ID bea/81a
+
+See ``be help new`` for more details.
+
+While the bug summary should include the appropriate keywords, it
+should also be brief.  You should probably add a comment immediately
+giving a more elaborate explanation of the problem so that the
+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
+
+    $ be comment abc/28f "Thoughts about demuxalizers..."
+    Created comment with ID abc/28f/97a
+    $ be comment abc/def/012 "Oops, I forgot to mention..."
+    Created comment with ID abc/28f/e88
+
+Usually comments will be long enough that you'll want to compose them
+in a text editor, not on the command line itself.  Running ``be
+comment`` without providing a ``COMMENT`` argument will try to spawn
+an editor automatically (using your environment's ``VISUAL`` or
+``EDITOR``, see `Guide to Unix, Environmental Variables`_).
+
+.. _Guide to Unix, Environmental Variables:
+   http://en.wikibooks.org/wiki/Guide_to_Unix/Environment_Variables
+
+You can also pipe the comment body in on stdin, which is especially
+useful for binary attachments, etc.::
+
+    $ cat screenshot.png | be comment --content-type image/png bea/28f
+    Created comment with ID bea/28f/35d
+
+It's polite to insert binary attachments under comments that explain
+the content and why you're attaching it, so the above should have been
+
+    $ be comment bea/28f "Whosit dissapears when you mouse-over whatsit."
+    Created comment with ID bea/28f/41d
+    $ cat screenshot.png | be comment --content-type image/png bea/28f/41d
+    Created comment with ID bea/28f/35d
+
+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
+interested in (e.g. bug bea/28f), try::
+
+    $ be show bea/28f
+              ID : 28fb711c-5124-4128-88fe-a88a995fc519
+      Short name : bea/28f
+        Severity : minor
+          Status : open
+        Assigned :
+        Reporter :
+         Creator : ...
+         Created : ...
+    Missing demuxalizer functionality
+    --------- Comment ---------
+    Name: bea/28f/97a
+    From: ...
+    Date: ...
+    
+    Thoughts about demuxalizers...
+      --------- Comment ---------
+      Name: bea/28f/e88
+      From: ...
+      Date: ...
+      
+      Thoughts about demuxalizers...
+    --------- Comment ---------
+    Name: bea/28f/41d
+    From: ...
+    Date: ...
+    
+    Whosit dissapears when you mouse-over whatsit.
+      --------- Comment ---------
+      Name: bea/28f/35d
+      From: ...
+      Date: ...
+      
+      Content type image/png not printable.  Try XML output instead
+
+You can also get a single comment body, which is useful for extracting
+binary attachments::
+
+    $ be show --only-raw-body bea/28f/35d > screenshot.png
+
+There is also an XML output format, which can be useful for emailing
+entries around, scripting BE, etc.
+
+    $ be show --xml bea/35d
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <be-xml>
+    ...
+
+Listing bugs
+------------
+
+If you *don't* know which bug you're interested in, you can query
+the whole bug directory::
+
+    $ be list
+    bea/28f:om: Missing demuxalizer functionality
+    bea/81a:om: Missing whatsit...
+
+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
+some sort of ``diff`` command that shows what's changed since revision
+``XYZ``.  BE has it's own command that formats the bug-repository
+portion of those changes in an easy-to-understand summary format.  To
+compare your working tree with the last commit::
+
+    $ be diff
+    New bugs:
+      bea/01c:om: Need command output abstraction for flexible UIs
+    Modified bugs:
+      bea/343:om: Attach tests to bugs
+        Changed bug settings:
+          creator: None -> W. Trevor King <wking@drexel.edu>
+
+Compare with a previous revision ``480``::
+
+    $ be diff 480
+    ...
+
+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,
+and refer you to ``be help COMMAND`` for more details.
+
+* ``assign``, Assign an individual or group to fix a bug
+* ``depend``, Add/remove bug dependencies
+* ``due``, Set bug due dates
+* ``status``, Change a bug's status level
+* ``severity``, Change a bug's severity level
+* ``tag``, Tag a bug, or search bugs for tags
+* ``target``, Assorted bug target manipulations and queries
+
+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
+the changes with::
+
+    $ be subscribe --types all DIR
+
+Subscribe only to bug creaton on bugseverywhere.org with::
+
+    $ be subscribe --server bugseverywhere.org --types new DIR
+
+Subscribe to get all the details about bug ``bea/28f``::
+
+    $ be subscribe --types new bea/28f
+
+To unsubscribe, simply repeat the subscription command adding the
+``--unsubscribe`` option, but be aware that it may take some time for
+these changes to propogate between distributed repositories.  If you
+don't feel confident in your ability to filter email, it's best to
+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
+
+* ``active_status``
+  The allowed active bug states and their descriptions.
+* ``inactive_status``
+  The allowed inactive bug states and their descriptions.
+* ``severities``
+  The allowed bug severities and their descriptions.
+* ``target``
+  The current project development target (bug UUID).
+* ``extra_strings``
+  Space for an array of extra strings.  You usually won't bother with
+  this directly.
+
+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::
+
+    $ be show --xml bea/28f > bug.xml
+
+This information can be imported into (another) bug directory via
+
+    $ be import-xml bug.xml
+
+Also distributed with BE are some utilities to convert mailboxes
+into BE-XML (``be-mail-to-xml``) and convert BE-XML into mbox_
+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::
+
+    $ be html
+
+This is a fairly flexible command, see ``be help html`` for details.
+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::
+
+    $ be serve
+
+To serve a repository over HTTP.  For example::
+
+    $ be serve > server.log 2>&1 &
+    $ be --repo http://localhost:8000 list
+
+Of course, be careful about serving over insecure networks, since
+malicous users could fill your disk with endless bugs, etc.  You can
+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
+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.
+
+Commit
+~~~~~~
+
+Currently, we only expose ``be commit``, which commits all currently
+pending changes.