Subject:
Re: Docbook, Xml, Jade etc.
From:
"Martin A. Brown" ####@####.####
Date:
28 Jul 2003 04:48:47 -0000
Message-Id: <Pine.LNX.4.55.0307272230340.1624@enclitic.wonderfrog.net>
[ Long reply. Disclaimers below signature. ]
: I've been working my way through the Author Guide and have become
: extremely frustrated.
Yes, Simon, DocBook can be rather frustrating. Indeed, terribly so
when you have to install all of the tools yourself.
: Why do I need to install all of the various elements of this
: undocumented LDP cruft then learn how to use it in order to get a
: document published?
I see you have already had one offer for markup from a list member.
If you do have something you wish to write about, feel free to
ask--there are people on the list who will provide markup for you,
and also help you get your DocBook installation working.
Note, also, in my disclaimer below--you need not learn DocBook if
you do not wish to--you could use linuxdoc, an easier markup
language. Others on this list do so, and are more familiar with
linuxdoc, so I'll continue in my determined effort as a proponent of
DocBook.
: I've looked through the necessary packages, none of which
: contains _any_ documentation on install or usage. docbook-dssl
: handily mentions an install.html file but doesn't bother to
: provide it. Some of the packages uncompress into the current
: directory and try to overwrite files from other packages. Which
: versions should I use? This thing is an complete mess!
Well....I'm not quite sure I'd agree with your assertion that there
is no documentation on installation or usage....BUT, the easily
available existing documentation is sometimes at cross purposes due
to the myriad ways in which DocBook can be used.
One beautiful thing about DocBook...it's just a bunch of files. (Of
course, I suppose you could almost say the same about Unix.)
: The Author guide is not much better; "you need this this and
: this" but not "this is how you install and configure the various
: pieces and start using them.."
:
: Everyone reads HOWTO's in html anyway, why jump through all of
: the unnecessary hoops?
Although it's true that *many* people read HOWTOs in HTML, I have
found that the most common download of my own documentation is the
PDF (which is generated from the same source DocBook files).
So, there are people who use other output formats, although I would
agree with the sentiment of your frustration--people probably read
(or refer) to the HTML documentation, not the PS or PDF output.
: Having to go through all of this rubbish to translate a perfectly
: good document from HTML into some unnecessary alternative format
: for the one in a billion people that doesn't have a browser is a
: complete waste of time.
The primary reason you might choose to write DocBook is to separate
the presentation (which will be primarily HTML) from the content and
organization, which is the DocBook SGML/XML format.
[ /me omits section on DocBook SGML, since I don't know it very
well, but it's like any other markup language you might already
have experience with. ]
So DocBook XML is an XML dialect which represents an entire book or
document in a structured manner, without hinting at the
presentation.
** High-level overview **
DocBook XML can be a bit confusing at first, so let's identify the
different files you need in order to process DocBook files.
Files in use in any DocBook processing installation
DocBook XML (processed with jade)
------------------------------------------
DTD files (you probably want 4.1.2)
DSSSL files (1.78 is current)
DocBook XML (processed with xsltproc*)
------------------------------------------
DTD files (you probably want 4.1.2)
XSLT files (1.61.3 is current)
Brief description of the purpose of these files
- DTD files define the acceptable structure and tags of any
DocBook file. The processor (jade or xsltproc) consults
the DTD files to validate any DocBook source file.
- DSSSL files are used by jade to map DocBook documents into
HTML output. If you intend to use jade, you must have the
DSSSL files in order to generate output.
- XSLT files are used by xsltproc to map DocBook XML documents
into HTML output. If you intend to use xsltproc, you must
have the XSLT files.
So, you can think of the DTD as a blueprint against which a document
is checked for validity, and you can think of the DSSSL and XSLT
files as translators or interpreters. A processor needs to compare
an input document with a validity structure and uses DSSSL/XSLT to
transform the input document into a desired output format.
That's just a touch of background.
** Preparing the support files **
Because I know I'm the only user on my workstation, I do roughly the
following (use a mirror near you):
Getting the files in one place:
$ cd $HOME
$ mkdir docbook
$ cd docbook
$ wget http://umn.dl.sourceforge.net/sourceforge/docbook/docbook-dsssl-1.78.tar.gz
$ tar xvzf docbook-dsssl-1.78.tar.gz
$ ln -s docbook-dsssl-1.78 dsssl
$ wget http://umn.dl.sourceforge.net/sourceforge/docbook/docbook-xsl-1.61.3.tar.gz
$ tar xvzf docbook-xsl-1.61.3.tar.gz
$ ln -s docbook-xsl-1.61.3 xsl
$ wget http://www.tldp.org/authors/tools/docbkx412.zip
$ mkdir -p dtds/4.1.2
$ cd dtds/4.1.2
$ unzip ../../docbkx412.zip
Now, this should give you all of the XSLT, DSSSL, and DTD files in
one centrally accessible location for your UID.
** The catalog file **
Now, there is exactly and only one tricky step left. That is the
use of a catalog file to tell your processor where to find the
required files.
Problem:
The DocBook DTDs are known by public identifiers (you have seen
these at the top of files:
-//OASIS//DTD DocBook V4.1.2//EN
-//OASIS//DTD DocBook V4.1//EN
The DocBook XSL stylesheets are known by an absolute URL.
Solution:
Make the processor capable of referring to a local file instead of
an HTTP resource or an abstract concept (a public identifier).
This is a catalog file. (Frequently called catalog.xml.)
[ Sorry for the long lines, list readers. And yes, my "nextCatalog" tag
is broken ]
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<nextCatalog catalog="@XML_CATALOG@" />
<public
publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
uri="/home/mabrown/docbook/dtds/4.1.2/docbookx.dtd"/>
<uri name="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
uri="/home/mabrown/docbook/dtds/4.1.2/docbookx.dtd"/>
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/docbook.xsl"/>
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/chunk.xsl"/>
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/profile-chunk.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/profile-chunk.xsl"/>
</catalog>
Convention may differ, but I keep the catalog file with the
documentation itself, not with the DocBook XSL, DSSL and DTD files.
So, in every project I make, I have a catalog.xml.
** Creating an ouput document (chunked HTML) **
And finally, a very simple example of using xsltproc to generate
HTML output from a DocBook XML source file. I will give you an
example of an XML catalog file I use for one of my pieces of
documentation. If you'd like to try, yourself, just grab a DocBook
XML file from the
http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ repository.
Make sure it is a DocBook XML file, this should be clear in the
header.
$ cd $DOC_SRC_DIR
$ mkdir output
$ export XML_CATALOG_FILES=catalog.xml
$ xsltproc --nonet -stringparam base.dir output \
> ~/docbook/xsl/xhtml/chunk.xsl $DOCBOOK_DOCUMENT
Now, you should have some HTML files in the directory output. And,
by the way, I'd recommend the newest version of xsltproc that you
can get your hands on. There was/is a very old version floating
around on RedHat boxen (libxslt-1.0.18, I think) which doesn't like
DocBook XSLT very much.
** Conclusion **
So, Simon--YES--DocBook is difficult and frustrating, but you will
be able to rid yourself of the drudgery of maintaining HTML files
by conquering DocBook. If you have one or two short HTML files,
DocBook is probably overkill, but for TLDP, it meets a need. Small
and simple documents like my Traffic Control with tcng and HTB can
be written in DocBook, and large and complex book-length documents
like the Advanced Bash Scripting Guide can also be written in
DocBook.
And if you have just a short item to write--feel free to write it in
text, and ask somebody on the list to tag it for you.
Good luck, and let us know how it goes,
-Martin
* There are other XSLT processors (saxon, xalan, et.al.), which
can also produce output from DocBook XML source. These XSLT
processors also need to read the XSLT and DTD files.
disclaimers:
It is not required to use DocBook. TLDP will accept submissions
in linuxdoc format, which is a much simpler markup language, and
one preferred by several regular contributors.
The above method of setting up a user for DocBook processing is
quick n' dirty, and is not suitable for a system which will
routinely be used by many to build documentation.
I did not include any examples on how to create HTML output from
and/or with jade, because this was just a crash course.
