Docbook discussion

Zoltán János Jánosi | 25 May 2012 12:13

DocBook XML 4.4 + XSLT = HTML

Hi!

I am working with DocBook XML v4.4.
I'd like to show it in a browser. The CSS way is not viable because of the lack of images.
Now I am looking for some XSL files that I can set as stylesheets in the header section of the XML files to render DocBook files to HTML on the fly.
I found DocBook XSL files at sourceforge. (http://sourceforge.net/projects/docbook/files/docbook-xsl/)
I tried several different versions (1.77.0-1.70.1).
When I used the docbook.xsl the browser always stopped stating "An unknown error occured at loading the stylesheet".
When I use the html.xsl the text appears but without CSS it looks plain.

So my questions are:
1. What is the correct (and most simple) way of showing DocBook v4.4 in browsers?
2. What DocBook XSL versions should I use? (maybe the newers are for v5+ only?)

Thanx in advance!
Jazoja

headers

Thomas Schraitle | 25 May 2012 13:13

Re: DocBook XML 4.4 + XSLT = HTML

Hi Zoltán,

On Fri, 25 May 2012 12:13:52 +0200
Zoltán János Jánosi <jazoja4 <at> gmail.com> wrote:

> I am working with DocBook XML v4.4.
> I'd like to show it in a browser. 
> 
> So my questions are:
> 1. What is the correct (and most simple) way of showing DocBook v4.4
> in browsers?

Short answer: I would't do it. :)

From my point of view, this method has several drawbacks:

* Support of XSLT in browsers are limited
* The DocBook stylesheets uses some extensions which may or may not be
  available in your browser
* You can only view the document as a whole page, not in chunks
* You can't pass parameters to the original stylesheet to customize
  certain behaviours
* If your XML source is not well-formed, the hole process will break
* Whenever you show your XML in your browser, it will load the
  DocBook stylesheets first. Lots of bandwidth is wasted each time.
* It's not a very common approach in the DocBook community. I've never
  seen it (although it may be used in special cases)
* There are better approaches (see text)

(Yes, maybe my above points are not as absolute as they sound. There
might be some who use this approach, but I've never seen it in
production.)

The supported, best, simplest, and easiest approach is to transform your
DocBook source (regardless of its version) into HTML by the DocBook
stylesheet. Be it with Saxon, xsltproc, or Xalan. That gives you all
the flexibility.

Remember, a browser is a tool to show _HTML_ files most efficiently.
That's what he knows and was invented for. Some may know XML+CSS+XSLT,
but that doesn't mean it is a well-supported method. I doubt most
browsers can cope with the complexity of the DocBook stylesheets. 

> 2. What DocBook XSL versions should I use? (maybe the newers are for
> v5+ only?)

There are two incarnations of the DocBook stylesheets: the "normal" and
the NS variant. Generally, you can use both regardless of the DocBook
version. Of course, there are some differences: Internally the DocBook
namespace is added or removed. See the following details for more
information:

  http://sagehill.net/docbookxsl/ProcesingDb5.html#Db4XslForDb5

--

-- 
Gruß/Regards,
    Thomas Schraitle

headers

Dominik Psenner | 25 May 2012 14:53

RE: DocBook XML 4.4 + XSLT = HTML

>Short answer: I would't do it. :)
>
>From my point of view, this method has several drawbacks:
>
>* Support of XSLT in browsers are limited
>* The DocBook stylesheets uses some extensions which may or may not be
>  available in your browser
>* You can only view the document as a whole page, not in chunks
>* You can't pass parameters to the original stylesheet to customize
>  certain behaviours
>* If your XML source is not well-formed, the hole process will break
>* Whenever you show your XML in your browser, it will load the
>  DocBook stylesheets first. Lots of bandwidth is wasted each time.
>* It's not a very common approach in the DocBook community. I've never
>  seen it (although it may be used in special cases)
>* There are better approaches (see text)
>
>(Yes, maybe my above points are not as absolute as they sound. There
>might be some who use this approach, but I've never seen it in
>production.)
>
>The supported, best, simplest, and easiest approach is to transform your
>DocBook source (regardless of its version) into HTML by the DocBook
>stylesheet. Be it with Saxon, xsltproc, or Xalan. That gives you all
>the flexibility.

Not only to mention the impact on the server. XSL transformations are not
cheap (in the sense of computational expensive).

If you're only half as lazy as me, you would set up a deployment that bears
less hazzle as possible in the future. I for instance would set up a
mercurial repository that automatically builds the docbook to HTML whenever
I decide to publish (in terms of mercurial it would be "to push") an update.
All you need for that is a mercurial repository, a python xsl transformer as
described at [1], post push hook as described at [2] and an update hook as
described at [3]. The update hook should finally start the XSL
transformation of the docbook source.

Setting it up like this I could modify the website as needed and once I am
done with that and want to publish it, all I have to do is run:

$ hg push http://my.web.server/hg/website-repository

Cheers,
Dominik

[1] http://bytes.com/topic/python/answers/22945-xml-xslt-python
[2]
http://mercurial.selenic.com/wiki/FAQ#FAQ.2BAC8-CommonProblems.Any_way_to_.2
7hg_push.27_and_have_an_automatic_.27hg_update.27_on_the_remote_server.3F
[3]
http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html