Use Docutils' rst2doc instead of DocBook XML to generate man page.

5 files changed, 94 insertions, 179 deletions

diff --git a/Makefile b/Makefile
index f7937f8..fce6060 100644
--- a/Makefile
+++ b/Makefile
@@ -27,10 +27,8 @@
 
 SHELL = /bin/bash
 RM = /bin/rm
-DB2MAN = http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
-DB2HTML = http://docbook.sourceforge.net/release/xsl-ns/current/html/docbook.xsl
-XP = /usr/bin/xsltproc --nonet --param man.charmap.use.subset "0" \
-	--param make.year.ranges "1" --param make.single.year.ranges "1"
+RST2MAN = /usr/bin/rst2man
+RST2HTML = /usr/bin/rst2html
 
 #PATH = /usr/bin:/bin  # must include sphinx-build for 'sphinx' target.
 
@@ -50,7 +48,8 @@ LIBBE_VERSION := libbe/_version.py
 GENERATED_FILES := build $(LIBBE_VERSION)
 
 MANPAGE_FILES = $(patsubst %,${MAN_DIR}/%,${MANPAGES})
-GENERATED_FILES += ${MANPAGE_FILES}
+MANPAGE_HTML =  $(patsubst %,${MAN_DIR}/%.html,${MANPAGES})
+GENERATED_FILES += ${MANPAGE_FILES} ${MANPAGE_HTML}
 
 
 .PHONY: all
@@ -84,10 +83,10 @@ libbe/_version.py:
 .PHONY: man
 man: ${MANPAGE_FILES}
 
-%.1: %.1.xml
-	$(XP) -o $@ $(DB2MAN) $<
-%.1.html: %.1.xml
-	$(XP) -o $@ $(DB2HTML) $<
+%.1: %.1.txt
+	$(RST2MAN) $< > $@
+%.1.html: %.1.txt
+	$(RST2HTML) $< > $@
 
 .PHONY: sphinx
 sphinx:
diff --git a/doc/doc.txt b/doc/doc.txt
index 1b2b5aa..e57b1f7 100644
--- a/doc/doc.txt
+++ b/doc/doc.txt
@@ -25,20 +25,12 @@ syntax.
 Man page
 ========
 
-The man-page source :file:`be.1.xml` is writen in DocBook 5 [#DB5]_
-format.  The :file:`Makefile` converts it to :manpage:`roff(7)` format
-using an XSLT stylesheet.  See DocBook XSL [#DBXSL]_ for details.
-See :doc:`install` for suggestions on setting up a DocBook 5 toolchain
-in several distributions.
+The man-page source :file:`be.1.txt` is writen in reStructuredText.
+The :file:`Makefile` converts it to :manpage:`roff(7)` format using
+Docutils_ ``rst2man``.
 
 The man page should conform to `Debian policy`_.
 
-.. [#DB5]
-   See Norman Walsh's `DocBook 5: The Definitive Guide
-   <http://www.docbook.org/>`_
-
-.. [#DBXSL]
-   See Bob Stayton's `DocBook XSL: The Complete Guide
-   <http://www.sagehill.net/book-description.html>`_
-
-.. _Debian policy: http://www.debian.org/doc/debian-policy/ch-docs.html#s12.1
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Debian policy:
+  http://www.debian.org/doc/debian-policy/ch-docs.html
diff --git a/doc/install.txt b/doc/install.txt
index 5752566..c7b9171 100644
--- a/doc/install.txt
+++ b/doc/install.txt
@@ -5,34 +5,19 @@ Installing BE
 Dependencies
 ============
 
-==============  =======================  =============  ===========================
-Package         Role                     Debian         Gentoo
-==============  =======================  =============  ===========================
-PyYAML_         serialized data storage  python-yaml    dev-python/pyyaml
-Sphinx_         see :doc:`doc`           python-sphinx  dev-python/sphinx
+==============  =======================  ===============  ===========================
+Package         Role                     Debian           Gentoo
+==============  =======================  ===============  ===========================
+PyYAML_         serialized data storage  python-yaml      dev-python/pyyaml
+Sphinx_         see :doc:`doc`           python-sphinx    dev-python/sphinx
 numpydoc_       see :doc:`doc`           
-xsltproc_       see :doc:`doc`           xsltproc       dev-libs/libxslt
-==============  =======================  =============  ===========================
-
-The XSLT stylesheets reqired to generate the manpage are packaged in
-``docbook-xsl-ns`` on Debian [#debian] and
-``app-text/docbook-xsl-ns-stylesheets`` on Gentoo [#gentoo].  For
-futher details on DocBook publishing, see the DocBook wiki pages on
-tools_ and stylesheets_.
+Docutils_       manpage generation       python-docutils  dev-python/docutils
+==============  =======================  ===============  ===========================
 
 .. _PyYAML: http://pyyaml.org/
 .. _Sphinx: http://sphinx.pocoo.org/
 .. _numpydoc: http://pypi.python.org/pypi/numpydoc
-.. _xsltproc: http://www.xmlsoft.org/XSLT/
-.. [#debian] See bugs `490716
-  <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=490716>`_
-  and `447959
-  <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=447959>`_.
-.. [#gentoo] See Diego Elio Pettenò's `blog entry
-  <http://blog.flameeyes.eu/2008/09/22/docbook-5-and-gentoo>`_.
-.. _tools: http://wiki.docbook.org/topic/DocBookPublishingTools
-.. _stylesheets: http://wiki.docbook.org/topic/DocBookXslStylesheets
-
+.. _Docutils: http://docutils.sourceforge.net/
 
 Git repository
 ==============
diff --git a/doc/man/be.1.txt b/doc/man/be.1.txt
new file mode 100644
index 0000000..a636a18
--- /dev/null
+++ b/doc/man/be.1.txt
@@ -0,0 +1,72 @@
+==
+be
+==
+
+----------------------------------------------
+distributed bug tracking from the command line
+----------------------------------------------
+
+:Author: wking@drexel.edu
+:Date:   2011-01-10
+:Copyright: Permission is granted to copy, distribute and/or modify
+  this document under the terms of the GNU General Public License,
+  Version 2 or (at your option) any later version published by the
+  Free Software Foundation.
+:Version: 0.2
+:Manual section: 1
+:Manual group: distributed bug tracker
+
+SYNOPSIS
+========
+
+be [options] [command] [command_options] [commands_args...]
+
+DESCRIPTION
+===========
+
+``be`` allows commandline interaction with the Bugs Everywhere
+database in a project tree.
+
+To avoid bit-rotted documentation, we do not describe all available
+commands and options in this manpage.  Run ``be help`` for accurate
+documentation.  See the `Bugs Everywhere Manual`_ for more detailed
+documentation and tutorials.
+
+.. _Bugs Everywhere Manual: http://docs.bugseverywhere.org/
+
+COMMANDS
+========
+
+help
+    Print help for ``be`` and a list of all available commands.
+
+Run ``be help`` for a complete list.
+
+EXAMPLES
+========
+
+be help
+    Show general help and a list of all commands.
+
+be help init
+    Show help for the ``init`` command.
+
+be init
+    Initialize a new Bugs Everywhere database.
+
+BUGS
+====
+
+The Bugs Everywhere uses Bugs Everywhere to track its bugs.  You can
+submit bugs directly using ``be``::
+
+  % be --repo http://bugs.bugseverywhere.org/ new "The demuxulizer is broken"           
+  Created bug with ID bea/abc
+  % be --repo http://bugs.bugseverywhere.org/ comment bea/abc
+  <Describe bug>
+  % be --repo http://bugs.bugseverywhere.org/ commit "Reported bug in demuxulizer" 
+
+Or send an email to the mailing list at `be-devel@bugseverywhere.org`_.
+
+.. _be-devel@bugseverywhere.org:
+  http://void.printf.net/cgi-bin/mailman/listinfo/be-devel
diff --git a/doc/man/be.1.xml b/doc/man/be.1.xml
deleted file mode 100644
index 3b5c8d0..0000000
--- a/doc/man/be.1.xml
+++ /dev/null
@@ -1,133 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE article [
-  <!ENTITY dhfirstname "Ben">
-  <!ENTITY dhsurname   "Finney">
-  <!ENTITY dhusername  "&dhfirstname; &dhsurname;">
-  <!ENTITY dhemail     "ben+debian@benfinney.id.au">
-  <!ENTITY dhdate      "2010-09-28">
-  <!ENTITY dhsection   "1">
-  <!ENTITY pkgfullname "Bugs Everywhere">
-  <!ENTITY uccmdname   "BE">
-  <!ENTITY cmdname     "be">
-]>
-
-<article xmlns="http://docbook.org/ns/docbook" version="5.0"
-	 xmlns:xlink="http://www.w3.org/TR/xlink/">
-<title>&pkgfullname; Refentries</title>
-<refentry>
-  <info>
-    <productname>Debian</productname>
-    <date>&dhdate;</date>
-    <address>
-      <email>&dhemail;</email>
-    </address>
-    <authorgroup>
-      <author>
-	<firstname>&dhfirstname;</firstname>
-	<surname>&dhsurname;</surname>
-	<contrib>Created the initial SGML version of this manpage for
-	  the Debian system.</contrib>
-	<address>
-          <email>&dhemail;</email>
-	</address>
-      </author>
-      <author>
-	<firstname>W. Trevor</firstname>
-	<surname>King</surname>
-	<contrib>Converted this manpage to DocBook 5 XML and extended
-	  following
-	  <citerefentry>
-            <refentrytitle>dh_make</refentrytitle>
-            <manvolnum>8</manvolnum>
-	  </citerefentry>'s
-	  <filename>manpage.xml.ex</filename>.</contrib>
-	<address>
-          <email>&dhemail;</email>
-	</address>
-      </author>
-    </authorgroup>
-    <copyright>
-      <year>2009</year>
-      <year>2010</year>
-      <holder>&dhusername;</holder>
-    </copyright>
-    <legalnotice>
-      <para>This manual page was written for the Debian system
-        (and may be used by others).</para>
-      <para>Permission is granted to copy, distribute and/or modify this
-        document under the terms of the GNU General Public License,
-        Version 2 or (at your option) any later version published by
-        the Free Software Foundation.</para>
-      <para>On Debian systems, the complete text of the GNU General Public
-        License can be found in
-        <filename>/usr/share/common-licenses/GPL</filename>.</para>
-    </legalnotice>
-  </info>
-  <refmeta>
-    <refentrytitle>&uccmdname;</refentrytitle>
-    <manvolnum>&dhsection;</manvolnum>
-  </refmeta>
-  <refnamediv>
-    <refname>&cmdname;</refname>
-    <refpurpose>distributed bug tracker</refpurpose>
-  </refnamediv>
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>&cmdname;</command>
-      <arg><replaceable>options</replaceable></arg>
-      <arg><replaceable>command</replaceable></arg>
-      <arg><replaceable>command_options</replaceable></arg>
-      <arg rep="repeat"><replaceable>command_args</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-  <refsect1 id="description">
-    <title>DESCRIPTION</title>
-
-    <para>This manual page documents briefly the
-      <command>&cmdname;</command> command, part of the &pkgfullname;
-      package.</para>
-
-    <para><command>&cmdname;</command> allows commandline interaction
-      with the &pkgfullname; database in a project tree.</para>
-
-    <para>To avoid bit-rotted documentation, we do not describe all
-      available commands and options in this manpage.
-      Run <command>&cmdname; help</command> for accurate
-      documentation.  See
-      the <link xlink:href="http://docs.bugseverywhere.org/">&pkgfullname;
-      Manual</link> for more detailed documentation and
-      tutorials.</para>
-
-  </refsect1>
-  <refsect1 id="commands">
-    <title>COMMANDS</title>
-    <variablelist>
-      <varlistentry>
-        <term><command>help</command>
-        </term>
-        <listitem>
-          <para>Print help for <command>be</command> and a list of all
-            available commands.</para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-  </refsect1>
-  <refsect1 id="examples">
-    <title>EXAMPLES</title>
-    <glosslist>
-      <glossentry>
-        <glossterm><command>&cmdname; help</command></glossterm>
-        <glossdef>
-	  <para>Show general help and a list of all commands.</para>
-	</glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><command>&cmdname; help init</command></glossterm>
-        <glossdef>
-	  <para>Show help for the <command>init</command> command.</para>
-	</glossdef>
-      </glossentry>
-    </glosslist>
-  </refsect1>
-</refentry>
-</article>