Rewrote documentation

1 files changed, 56 insertions, 45 deletions

diff --git a/interfaces/email/interactive/README b/interfaces/email/interactive/README
index b25054c..f7d57ad 100644
--- a/interfaces/email/interactive/README
+++ b/interfaces/email/interactive/README
@@ -2,15 +2,14 @@ Overview
 ========
 
 The interactive email interface to Bugs Everywhere (BE) attempts to
-provide a Debian-bug-tracking-system-style interface to a BE
+provide a `Debian-bug-tracking-system-style`_ interface to a BE
 repository.  Users can mail in bug reports, comments, or control
 requests, which will be committed to the served repository.
 Developers can then pull the changes they approve of from the served
 repository into their other repositories and push updates back onto
 the served repository.
 
-For details about the Debian bug tracking system that inspired this
-interface, see http://www.debian.org/Bugs .
+.. _Debian-bug-tracking-system-style: http://www.debian.org/Bugs
 
 Architecture
 ============
@@ -18,27 +17,34 @@ Architecture
 In order to reduce setup costs, the entire interface can piggyback on
 an existing email address, although from a security standpoint it's
 probably best to create a dedicated user.  Incoming email is filtered
-by procmail, with matching emails being piped into be-handle-mail for
-execution.
-
-Once be-handle-mail receives the email, the parsing method is selected
-according to the subject tag that procmail used grab the email in the
-first place.  There are four parsing styles:
-    Style                 Subject
-    creating bugs         [be-bug:submit] new bug summary
-    commenting on bugs    [be-bug:<bug-id>] commit message
-    control               [be-bug] commit message
-These are analogous to submit@bugs.debian.org, nnn@bugs.debian.org,
-and control@bugs.debian.org respectively.
+by procmail, with matching emails being piped into ``be-handle-mail``
+for execution.
+
+Once ``be-handle-mail`` receives the email, the parsing method is
+selected according to the subject tag that procmail used grab the
+email in the first place.  There are four parsing styles:
+
+    +--------------------+----------------------------------+
+    | Style              | Subject                          |
+    +====================+==================================+
+    | creating bugs      | [be-bug:submit] new bug summary  |
+    +--------------------+----------------------------------+
+    | commenting on bugs | [be-bug:<bug-id>] commit message |
+    +--------------------+----------------------------------+
+    | control            | [be-bug] commit message          |
+    +--------------------+----------------------------------+
+
+These are analogous to ``submit@bugs.debian.org``,
+``nnn@bugs.debian.org``, and ``control@bugs.debian.org`` respectively.
 
 Creating bugs
 =============
 
 This interface creates a bug whose summary is given by the email's
 post-tag subject.  The body of the email must begin with a
-pseudo-header containing at least the "Version" field.  Anything after
-the pseudo-header and before a line starting with '--' is, if present,
-attached as the bug's first comment.
+pseudo-header containing at least the ``Version`` field.  Anything after
+the pseudo-header and before a line starting with ``--`` is, if present,
+attached as the bug's first comment.::
 
     From jdoe@example.com Fri Apr 18 12:00:00 2008
     From: John Doe <jdoe@example.com>
@@ -51,22 +57,22 @@ attached as the bug's first comment.
     Severity: minor
     
     Someone should write up a series of test emails to send into
-    be-handle mail so we can test changes quickly without having to
+    be-handle-mail so we can test changes quickly without having to
     use procmail.
     
     --
     Goofy tagline not included.
 
-Available pseudo-headers are Version, Reporter, Assign, Depend,
-Severity, Status, Tag, and Target.
+Available pseudo-headers are ``Version``, ``Reporter``, ``Assign``,
+``Depend``, ``Severity``, ``Status``, ``Tag``, and ``Target``.
 
 Commenting on bugs
 ==================
 
 This interface appends a comment to the bug specified in the subject
 tag.  The the first non-multipart body is attached with the
-appropriate content-type.  In the case of "text/plain" contents,
-anything following a line starting with '--' is stripped.
+appropriate content-type.  In the case of ``text/plain`` contents,
+anything following a line starting with ``--`` is stripped.::
 
     From jdoe@example.com Fri Apr 18 12:00:00 2008
     From: John Doe <jdoe@example.com>
@@ -85,11 +91,11 @@ Controlling bugs
 ================
 
 This interface consists of a list of allowed be commands, with one
-command per line.  Blank lines and lines beginning with '#' are
-ignored, as well anything following a line starting with '--'.  All
+command per line.  Blank lines and lines beginning with ``#`` are
+ignored, as well anything following a line starting with ``--``.  All
 the listed commands are executed in order and their output returned.
 The commands are split into arguments with the POSIX-compliant
-shlex.split().
+shlex.split().::
 
     From jdoe@example.com Fri Apr 18 12:00:00 2008
     From: John Doe <jdoe@example.com>
@@ -109,37 +115,42 @@ shlex.split().
 Example emails
 ==============
 
-Take a look at my interfaces/email/interactive/examples for some
+Take a look at ``interfaces/email/interactive/examples`` for some
 more examples.
 
 Procmail rules
 ==============
 
-The file _procmailrc as it stands is fairly appropriate for as a
-dedicated user's ~/.procmailrc.  It forwards matching mail to
-be-handle-mail, which should be installed somewhere in the user's
-path.  All non-matching mail is dumped into /dev/null.  Everything
-procmail does will be logged to ~/be-mail/procmail.log.
+The file ``_procmailrc`` as it stands is fairly appropriate for as a
+dedicated user's ``~/.procmailrc``.  It forwards matching mail to
+``be-handle-mail``, which should be installed somewhere in the user's
+path.  All non-matching mail is dumped into ``/dev/null``.  Everything
+procmail does will be logged to ``~/be-mail/procmail.log``.
 
 If you're piggybacking the interface on top of an existing account,
-you probably only need to add the be-handle-mail stanza to your
-existing ~/.procmailrc, since you will still want to receive non-bug
-emails.
+you probably only need to add the ``be-handle-mail`` stanza to your
+existing ``~/.procmailrc``, since you will still want to receive
+non-bug emails.
 
-Note that you will probably have to add a
-  --be-dir /path/to/served/repository
-option to the be-handle-mail invocation so it knows what repository to
+Note that you will probably have to add a::
+
+    --repo /path/to/served/repository
+
+option to the ``be-handle-mail`` invocation so it knows what repository to
 serve.
 
 Multiple repositories may be served by the same email address by adding
-multiple be-handle-mail stanzas, each matching a different tag, for
-example the "[be-bug" portion of the stanza could be "[projectX-bug",
-"[projectY-bug", etc.  If you change the base tag, be sure to add a
-  --tag-base "projectX-bug"
-or equivalent to your be-handle-mail invocation.
+multiple ``be-handle-mail`` stanzas, each matching a different tag, for
+example the ``[be-bug`` portion of the stanza could be ``[projectX-bug``,
+``[projectY-bug``, etc.  If you change the base tag, be sure to add a::
+
+    --tag-base "projectX-bug"
+
+or equivalent to your ``be-handle-mail`` invocation.
 
 Testing
 =======
 
-Send test emails in to be-handle-mail with something like
-  cat examples/blank | ./be-handle-mail -o -l - -a
+Send test emails in to ``be-handle-mail`` with something like::
+
+    cat examples/blank | ./be-handle-mail -o -l - -a