**
** xmlmp - simple XML-based man-page authoring tools
**
** by Nick Patavalis (npat@efault.net)
**

** What?

[xmlmp] is a 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" DTD, and provides tools
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 groff, should not be an excuse for not writing one.

** Whence?

The latest version of [xmlmp] can be downloaded from:

  http://efault.net/npat/hacks/xmlmp

** Requirements

It 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 which can be downloaded from:

  http://pyxml.sourceforge.net/

Again, this is _OPTIONAL_.
  
** Installation

To install [xmlmp] globaly (must be root), say:

  python2.3 setup.py install

To install [xmlmp] in your home directory (namely in: "$HOME/bin",
"$HOME/lib/python", and "$HOME/man"), say instead:

  python2.3 setup.py install --home=$HOME

In this latter case, the directory "$HOME/lib/python", must be in your
PYTHOPATH. You can put it there by adding the following lines to your
login-script (assuming a bourne-like shell):

  PYTHONPATH=$PYTHONPATH:$HOME/lib/python
  export PYTHONPATH

_Alternativelly_, you can install it manually like this:

  - copy the "xmlmp" directory some where in your python path:

    cp -a xmlmp-X.Y/xmlmp /somewhere/in/python/path

  - copy the scripts in the directory "scripts" somewhere in your
    executable path, and make sure their first lines match the
    location of your python interpreter:

    cp xmlmp-X.Y/scripts/xmlmp2* /somewhere/in/your/exec/path
    vi /somewhere/in/your/exec/path/xmlmp2man
    vi /somewhere/in/your/exec/path/xmlmp2html

** Using it:

Make a scratch directory:
    
    mkdir mydir
    cd mydir

Copy an example XML file, and the DTD 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 the xmlmp 1.1 DTD online, at:

    http://efault.net/npat/dtds/xmlmp/xmlmp-1.1.dtd

If you want to use a local copy instead, then edit the SYSTEM
identifier in the first line of the respective XML document. The
SYSTEM identifier can be any url, or a 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"

** That's all

Please send corrections, comments, and suggestions to the author's
email-address found at the top of this file.

/npat
