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
steps:
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
format.
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
know.
* * *
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
--
Gruß/Regards
Thomas Schraitle
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
