DocBook (was Re: [TriLUG] Linux for Newbies)

[Mark Johnson]

On Tuesday, May 21, rpjday wrote:
> On Tue, 21 May 2002, M. Mueller wrote:
> 
> > Is there an equivalent to "hello world" for DocBook?  Having to amass 5-6 
> > tools and use a non-trivial makefile to create a document from a document 
> > about a document is not for the faint of heart or over-committed or 
> > disorganized (here, here, and here).  Maybe there's just no way to make it 
> > simple?
> 
> this is a non-trivial project you're looking at here.  keep in mind that
> the whole point of writing something in docbook is that you want to
> be able to generate various output formats.  so even a simple example
> will involve XML, XSL, DocBook, an XSL-T processor like xsltproc,
> PassiveTeX for DVI, PDF and PostScript output, and so on.  not to
> mention tim's xmlto front-end which really does make life
> simpler.
> 
> sorry, there's no magic "hello, world" to get you started.

Well, there are some tools that come very, very close to a Hello World
program, but their use (and level of brokenness) is somewhat
distribution dependent. 

The process may be more easily looked at in two stages: (1) authoring,
and (2) processing.

(1) The authoring issue/problem quickly leads to the old editor war
    flaming, so I won't even go there. Except to say that one _really_
    needs a DTD-aware editor to truly learn the structure of
    DocBook. This constraint rules out a very large number of popular
    editors. Then again, one can always work from templates and not
    bother trying to grok DocBook in all its complexity (~400
    elements.)

(2) If you can somehow create a valid DocBook doc, then you should be
    able to easily generate HTML from the XML source using the old
    sgml standby known as 'jade' or 'openjade' and the frontend tools
    known collectively as docbook-utils (formerly docbook-tools).

    Try something like 

    $ docbook2html sourcefile.xml, or

    $ db2html /path/to/xml.dcl sourcefile.xml

    Or use Daniel Veillard's libxml/xslt tools:
 
    $ xsltproc /path/to/docbook-xsl/html/chunk.xsl sourcefile.xml

    I've also packaged stuff for debian that provides wrappers for
    some common xslt processors. For example, on debian you can type: 

    $ saxoncat docbook sourcefile.xml 


The point being that getting up & running with DocBook is not as hard
as it may sound. Ya just gotta know the right people;-)

Cheers,
Mark

_____________________________________
Mark Johnson        <mark at duke.edu>
Debian SGML         <mrj at debian.org>
Home Page:          <http://dulug.duke.edu/~mark/>
GPG fp: 50DF A22D 5119 3485 E9E4  89B2 BCBC B2C8 2BE2 FE81