discuss: Docbook, Xml, Jade etc.
Subject:
Re: Docbook, Xml, Jade etc.
From:
Wolfgang Fuschlberger ####@####.####
Date:
28 Jul 2003 07:09:10 -0000
Message-Id: <20030728070811.GA16516@window.dhis.org>
On Sun, 27 Jul 2003, Martin A. Brown wrote:
>
> [ 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.
The DocBook format itself is not so much of a problem to me, since I am used
to HTML. Till reading your mail I rather had difficulty in finding the right
Tools/Commands for converting the .xml-file to HTML for testing purposes. Yes,
I can read manpages, but I didn't know where to start exploring/learning on
this subject, which was entirely new to me.
> : 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.
Fortunately I wasn't so despaired yet to ask somebody else for help :-)
> 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.
If I write something for the LDP I want to use Docbook/XML, in order not to
leave more work than necessary to other people, and on the other hand to have
a good reason to learn XML :-)
> : 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!
ACK. There is so much information that one hardly cannot filter out the
relevant parts.
> 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.
Full ACK.
[snip]
> 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.
If somebody is interested I can find out the necessary packages in Debian
(woody and sarge).
> This is a catalog file. (Frequently called catalog.xml.)
This part wasn't necessary for me.
[snip]
> ** Creating an ouput document (chunked HTML) **
Ah, it's getting interesting...
> 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
Thank you. All I needed was the following:
xsltproc --nonet -o testoutput/ \
/usr/share/sgml/docbook/stylesheet/xsl/ldp/ldp-html-chunk.xsl Sample-HOWTO.xml
> 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.
One way that works is enough for me :-)
Thank you.
wolfgang
