Re: [Announce] mutt-1.5.12 is available

[David Champion <dgc@xxxxxxxxxxxx>]

* On 2006.07.14, in <20060714213420.GB21693@xxxxxxxxxxxxxxxx>,
*       "Jean-Pierre Radley" <jpr@xxxxxxx> wrote:
> | 
> | Works for me. Note that you need to have the DocBook XML V4.2 style
> | sheets installed and registered in your catalog.
> 
> I know nothing about XML and such a catalog.
> Please point me somewhere for an education.

I meant to write a mini-doc on this some time ago, and I forgot.  It's
not obvious how to do this, and AFAIK it only "just works" on systems
that have a wealth of pre-bundled packages. :) Here's how I worked it on
on my Solaris system.  There are other ways to accomplish it, but this
seemed simplest to me, starting from scratch and not meaning to invest a
lot of time in Docbook.

Thomas, Brendan, you're welcome to commit this to CVS under whatever
filename works for you, if it helps.

-- 
 -D.    dgc@xxxxxxxxxxxx        NSIT    University of Chicago

GENERATING MUTT DOCUMENTATION FROM SOURCE

To translate Mutt's Docbook XML documentation into HTML (and then text),
you'll need one tool and two sets of data which you may need to download
and install.  The tool is xsltproc, and it's a command-line program for
performing XSL transformations on XML documents.  The data sets are the
Docbook XML and Docbook XSL libraries.  You can download these from:

  . xsltproc
    http://xmlsoft.org/
    ftp://xmlsoft.org/libxslt/libxslt-1.1.17.tar.gz

  . docbook-xml-4.2
    http://www.docbook.org/
    http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip

  . docbook-xsl-1.70.1
    http://docbook.sourceforge.net/
    http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.70.1.zip


First, build and install libxslt to obtain xsltproc, if you don't
already have it.

Next, obtain and unpack the two docbook archives.  You can unpack these
anywhere that you want to have them installed -- there's no installation
procedure other than unarchival.  On my Solaris system, I install
packages under /opt/pkgs/packagename-version, so I unpacked these ZIP
archives to /opt/pkgs/docbook-xml-4.2 and /opt/pkgs/docbook-xsl-1.70.1.

Now you need to create (and export) an environment variable to process
the manuals.  The environment variable will contain a space-separated
list of "catalog" files for the two docbook archives, so substitute
the path where you unpacked them below:
    sh$ XML_CATALOG_FILES="/path/to/docbook-xml-4.2/catalog.xml 
/path/to/docbook-xsl-1.70.1/catalog.xml"; export XML_CATALOG_FILES
or
    csh$ setenv XML_CATALOG_FILES "/path/to/docbook-xml-4.2/catalog.xml 
/path/to/docbook-xsl-1.70.1/catalog.xml"

Once all these are installed and XML_CATALOG_FILES is set, you should be
able to generate manual.html with a simple "make" -- all as a part of
the mutt compilation.

The Makefile depends upon lynx (or any other text-mode web browser)
to turn the HTML into text, so if that fails you may need to install
something else.