From: W. Trevor King Date: Tue, 11 Jan 2011 03:30:11 +0000 (-0500) Subject: Use Docutils' rst2doc instead of DocBook XML to generate man page. X-Git-Tag: 1.1.0~244 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=2aeaa4e265deb093a5e37c5973deb8d932974491;p=be.git Use Docutils' rst2doc instead of DocBook XML to generate man page. --- 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 - `_ - -.. [#DBXSL] - See Bob Stayton's `DocBook XSL: The Complete Guide - `_ - -.. _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 - `_ - and `447959 - `_. -.. [#gentoo] See Diego Elio Pettenò's `blog entry - `_. -.. _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 + + % 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 @@ - - - - - - - - - - -]> - -
-&pkgfullname; Refentries - - - Debian - &dhdate; -
- &dhemail; -
- - - &dhfirstname; - &dhsurname; - Created the initial SGML version of this manpage for - the Debian system. -
- &dhemail; -
- - - W. Trevor - King - Converted this manpage to DocBook 5 XML and extended - following - - dh_make - 8 - 's - manpage.xml.ex. -
- &dhemail; -
- - - - 2009 - 2010 - &dhusername; - - - This manual page was written for the Debian system - (and 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 (at your option) any later version published by - the Free Software Foundation. - On Debian systems, the complete text of the GNU General Public - License can be found in - /usr/share/common-licenses/GPL. - - - - &uccmdname; - &dhsection; - - - &cmdname; - distributed bug tracker - - - - &cmdname; - options - command - command_options - command_args - - - - DESCRIPTION - - This manual page documents briefly the - &cmdname; command, part of the &pkgfullname; - package. - - &cmdname; allows commandline interaction - with the &pkgfullname; database in a project tree. - - To avoid bit-rotted documentation, we do not describe all - available commands and options in this manpage. - Run &cmdname; help for accurate - documentation. See - the &pkgfullname; - Manual for more detailed documentation and - tutorials. - - - - COMMANDS - - - help - - - Print help for be and a list of all - available commands. - - - - - - EXAMPLES - - - &cmdname; help - - Show general help and a list of all commands. - - - - &cmdname; help init - - Show help for the init command. - - - - - -