Converted man page source to DocBook V5.0.

This has the dual benefits of keeping up with the current DocBook
standard as well as removing the dependency on SGML parsers like
docbook-to-man and docbook2man which may not be available on all
systems.  An XSLT processor and the DocBook style sheets are easier
dependencies to satisfy.

diff --git a/Makefile b/Makefile
index 0b96832602d0a93acd46323b8dd0f3ba306515b5..c7203dfe1b3ffcfec87e3f460e3e2c325784c65d 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -26,7 +26,11 @@
 # along with Bugs Everywhere.  If not, see <http://www.gnu.org/licenses/>.
 
 SHELL = /bin/bash
-RM = rm
+RM = /bin/rm
+DB2MAN = http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
+XP = /usr/bin/xsltproc --nonet --param man.charmap.use.subset "0" \
+       --param make.year.ranges "1" --param make.single.year.ranges "1"
+
 #PATH = /usr/bin:/bin  # must include sphinx-build for 'sphinx' target.
 
 #PREFIX = /usr/local
@@ -75,8 +79,8 @@ libbe/_version.py:
 .PHONY: man
 man: ${MANPAGE_FILES}
 
-%.1: %.1.sgml
-       docbook-to-man $< > $@
+%.1: %.1.xml
+       $(XP) -o $@ $(DB2MAN) $<
 
 .PHONY: sphinx
 sphinx:

diff --git a/doc/man/be.1.sgml b/doc/man/be.1.sgml
deleted file mode 100644 (file)
index a2df21f..0000000
--- a/doc/man/be.1.sgml
+++ /dev/null
@@ -1,134 +0,0 @@
-<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-
-<!-- Process this file with docbook-to-man to generate an nroff manual
-     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
-     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
-     less'.  A typical entry in a Makefile or Makefile.am is:
-
-be.1: be.1.sgml
-       docbook-to-man $< > $@
-
-       The docbook-to-man binary is found in the docbook-to-man package.
-       Please remember that if you create the nroff version in one of the
-       debian/rules file targets (such as build), you will need to include
-       docbook-to-man in your Build-Depends control field.
-
-  -->
-
-  <!ENTITY dhfirstname "<firstname>Ben</firstname>">
-  <!ENTITY dhsurname   "<surname>Finney</surname>">
-  <!-- Please adjust the date whenever revising the manpage. -->
-  <!ENTITY dhdate      "<date>2009-06-25</date>">
-  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
-       allowed: see man(7), man(1). -->
-  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
-  <!ENTITY dhemail     "<email>ben+debian@benfinney.id.au</email>">
-  <!ENTITY dhusername  "Ben Finney">
-  <!ENTITY dhucpackage "<refentrytitle>BUGS-EVERYWHERE</refentrytitle>">
-  <!ENTITY dhpackage   "bugs-everywhere">
-  <!ENTITY pkgfullname "Bugs Everywhere">
-  <!ENTITY uccmdname   "<refentrytitle>BE</refentrytitle>">
-  <!ENTITY cmdname     "be">
-
-  <!ENTITY debian      "<productname>Debian</productname>">
-  <!ENTITY gnu         "<acronym>GNU</acronym>">
-  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
-]>
-
-<refentry>
-  <refentryinfo>
-    <address>
-      &dhemail;
-    </address>
-    <author>
-      &dhfirstname;
-      &dhsurname;
-    </author>
-    <copyright>
-      <year>2009</year>
-      <holder>&dhusername;</holder>
-    </copyright>
-    &dhdate;
-  </refentryinfo>
-  <refmeta>
-    &uccmdname;
-
-    &dhsection;
-  </refmeta>
-  <refnamediv>
-    <refname>&cmdname;</refname>
-
-    <refpurpose>distributed bug tracker</refpurpose>
-  </refnamediv>
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>&cmdname;</command>
-      <arg><replaceable>command</replaceable></arg>
-      <arg><replaceable>command_options ...</replaceable></arg>
-      <arg><replaceable>command_args ...</replaceable></arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>&cmdname; help</command>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>&cmdname; help</command>
-      <arg><replaceable>command</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-  <refsect1>
-    <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>
-
-  </refsect1>
-  <refsect1>
-    <title>COMMANDS</title>
-    <variablelist>
-      <varlistentry>
-        <term><command>help</command>
-        </term>
-        <listitem>
-          <para>Print help for be and a list of all available commands.
-          </para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-  </refsect1>
-  <refsect1>
-    <title>AUTHOR</title>
-
-    <para>This manual page was written by &dhusername; <&dhemail;> for
-      the &debian; system (but may be used by others). Permission is
-      granted to copy, distribute and/or modify this document under
-      the terms of the &gnu; General Public License, Version 2 or 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 /usr/share/common-licenses/GPL.
-       </para>
-
-  </refsect1>
-</refentry>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:2
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:nil
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
--->

diff --git a/doc/man/be.1.xml b/doc/man/be.1.xml
new file mode 100644 (file)
index 0000000..3b5c8d0
--- /dev/null
+++ b/doc/man/be.1.xml
@@ -0,0 +1,133 @@
+<?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>