OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Docbook for ePub and print versions?

Hi Bob,

Am Dienstag, 18. Oktober 2011, 10:55:48 schrieb Bob Plantz:
> [...]
> Of course, I want to have only one source for the material. So I am
> looking for the best tool chain that will allow me to produce both an
> ePub and a pdf (for printing) from the same source. So far my choices
> seem to be:
> 1. Restructuredtext for the source, which would be processed with docutils.
>     I like the simplicity of Restructuredtext, but it seems to lack (at
> this time) good tools for automatically numbering figures, exercises,
> equations, etc.
> 2. DocBook for the source, which can produce both pdf and HTML.
>     I've heard that DocBook can be difficult to work with for complex
> documents.

Well, depends how you define "difficult". ;)  If you are get used to word 
processors like Open Office, Word, etc. DocBook *might* be a bit unfamiliar. 
Well, it's a completely different method to create your documentation. 
Therefor it is probably a good idea to read some introducery material about 
DocBook to understand the idea behind.

> 3. LyX for the source, which can produce both pdf and HTML.
>     The conversion from LaTeX to LyX will be as difficult as 1 and 2,
> and it seems that all I get is a somewhat WYSIWIG interface to work
> with, at the expense of adding another layer.
> As you can see from my comments, I'm leaning toward choice 2. I know
> that any of the choices will be lots of work for me. But I'm retired,
> and I enjoy doing this stuff. Also, my work may provide some input into
> the overall problem of creating technical eBooks.
> I would very much appreciate hearing thoughts about my project from
> people who have used DocBook.

Ok, here are my ideas:

Recently, I've played with plasTeX[1] and converted two medium sized books 
written in LaTeX to DocBook (and from there to EPUB). It can be done, but it's 
not a "press this button and forget" solution. :)

PlasTeX is written in Python and fairly powerful. Actually, this is one of the 
best tools for LaTeX to DocBook conversion in my opinion. However, your 
success depends on your LaTeX code and your Python knowledge. If your document 
contains highly obscure TeX or LaTeX code, you will need to invest more time 
in plasTeX (or simplify the document).

However, from the experience that I've gained, I don't think there is a better 
tool (yet). As far as I know, plasTeX is the only tool which decouples the 
parsing step from the formatting step. This makes it very flexible. Actually, 
plasTeX can not only be used to convert to DocBook, it can also create HTML 
and other formats.

When I did the conversion for a publisher, I would recommend the following 

0. Decide Your Method
   Before you start this code marathon, maybe it's worth to think about your 
options. If you don't want to bother with plasTeX, Python, and the like, maybe 
it is better to rewrite your book manually in DocBook? 
That way you get to know DocBook much better and can eliminate any 
shortcomings in the LaTeX version (both textual and technical).
On the other side, you will miss a lot of fun (and maybe frustration). ;-)

1. Convert your LaTeX Code to DocBook
   This is probably the hardest part. I found it easier to start with the 
first chapter and disable the other chapters. Use plasTeX and try to convert 
it to DocBook. It may work or fail. If it works, enable another chapter. If it 
fails, try to fix the errors (or simplify the code). Go back and forth as it 
is needed until your book is completely converted. Make sure every part of the 
book appears also in the DocBook file.

2. Make a Quality Check
   After you got your converted DocBook file, validate it. Probably you will 
face some validation errors. There are some options to handle these:

   a.) Go back to step 1 and refine your conversion process to avoid it
   b.) Handle it with XSLT
   c.) Fix it manually

Mostly I could apply a and b. Option c was only needed for things which could 
not be handled automatically. Especially for such a huge book, I would 
recommend to use as much automated processes as possible. However, sometimes 
option c is the only solution. Luckily, that was not often the case.

3. Do the DocBook Dance
   You have a valid DocBook file? Great! Now you can use all the magic of the 
DocBook XSLT stylesheets to create your PDF or EPUB. If you use the default 
layout, you need just to type one or two commands to create your target 

After the conversion was successful, your LaTeX file is not needed anymore. 
Any changes are done in your DocBook file.

4. Fine-tune your Target Formats
   Probably the default layout from step 3 is not enough. Now it is the time 
to get (really) in touch with XSLT. It needs some time to get used to it, but 
Bob Stayton's excellent book[1] will give you all the information you need to 

                          *               *               *

Apart from the above steps, I would highly recommend to install a decent XML 
editor. This makes your DocBook experience a lot smoother regardless which 
method you choose in step 0.
It may also help to read some chapters from the Definitive Guide[3].

Hope it helps. :-)

----- References:
[1] http://plastex.sourceforge.net/
[2] http://www.sagehill.net/docbookxsl/
[3] http://www.docbook.org/tdg/en/html/docbook.html

  Thomas Schraitle

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]