Broke out install.txt + reStructuredText markup fixes

4 files changed, 130 insertions, 100 deletions

diff --git a/doc/distributed_bugtracking.txt b/doc/distributed_bugtracking.txt
index f3d574c..5ca42a6 100644
--- a/doc/distributed_bugtracking.txt
+++ b/doc/distributed_bugtracking.txt
@@ -8,26 +8,33 @@ 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
@@ -46,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/index.txt b/doc/index.txt
index 55ee543..f1c1542 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -1,10 +1,10 @@
 Welcome to the bugs-everywhere documentation!
 =============================================
 
-Bugs Everywhere (BE) is a bugtracker built on distributed revision
+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 RCS at all.
+function with no VCS at all.
 
 .. _Arch: http://www.gnu.org/software/gnu-arch/
 .. _Bazaar: http://bazaar.canonical.com/
@@ -13,14 +13,15 @@ function with no RCS at all.
 .. _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.
+that bugs can be marked "fixed" in the branches that fix them.
+
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   install.txt
    tutorial.txt
    ids.txt
    email.txt
@@ -36,57 +37,3 @@ Indices and tables
 * :ref:`genindex`
 * :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/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/spam.txt b/doc/spam.txt
index c0a2ba3..39e7a86 100644
--- a/doc/spam.txt
+++ b/doc/spam.txt
@@ -2,38 +2,59 @@
 Dealing with spam
 *****************
 
-
-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
+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.