xmlmp

[efault : npat : hacks : xmlmp ]

What?

xmlmp is a small Python package (and a couple of simple scripts using it), that facilitates the authoring of unix man-pages (the ugly groff things), using XML. It defines the xmlmp 1.1 DTD, and provides filters that convert documents complying with it to either unix man-pages, or HTML documents.

Why?

Because no unix executable should be without a manpage, and because not-knowing, or hating groff should not be an excuse for avoiding to write one.

Whence?

The latest version of xmlmp can always be downloaded from here.

News

version 1.1

changed a stupid mistake in the xmlmp 1.0 DTD, thus creating the xmlmp 1.1 DTD.

version 1.0

Initial Release

Requirements

xmlmp should work with any reasonably-modern Python installation (say, 2.x) wihout any additional packages. It was tested with Python-2.3.1. The optional "xmlproc_val" command mentioned in the examples below, requires the PyXML package. Again, this is OPTIONAL.

How?

Assuming you have installed xmlmp successfully (instructions are included in the distribution), here's how using it feels like. [[ All the example files linked below, are also included in the xmlmp source distribution. The links below are just for easy reference, you don't have to save them separately ]]:

Make a scratch directory:

    mkdir mydir
    cd mydir

Copy an example XML file, and the DTD from the source distribution, in the scratch dir:

    cp xmlmp-X.Y/examples/picocom.8.xml .
    cp xmlmp-X.Y/dtds/xmlmp-1.1.dtd .

OPTIONALLY validate the XML file (to see that it is really ok):

    xmlproc_val picocom.8.xml

Convert it to a man-page, a postscipt document, and an HTML document:

    xmlmp2man < picocom.8.xml > picocom.8
    groff -Tps -mandoc picocom.8 > picocom.8.ps
    xmlmp2html < picocom.8.html > picocom.8.html

ATTENTION: The example XML documents in the xmlmp distribution search for the xmlmp 1.1 DTD online. If you want to use a local copy instead (and you probably should), then edit the SYSTEM identifier in the first line of the respective XML document. The SYSTEM identifier can be any url, or any valid relative or absolute local path. If the DTD is in the same directory as the XML document it can simply be: "xmlmp-1.1.dtd"

Feedback

Please send fixes, comments, suggestions, and modifications to:

Nick Patavalis <npat [at] efault [dot] net>

Origin

xmlmp was inspired by a similar package, called xmltoman, writen by Oliver Kurth.

License and warranty

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA