All the books I have published so far has been using
DocBook somewhere in the process.
For the first book, the source format was DocBook, while for every
later book it was an intermediate format used as the stepping stone to
be able to present the same manuscript in several formats, on paper,
as ebook in ePub format, as a HTML page and as a PDF file either for
paper production or for Internet consumption. This is made possible
with a wide variety of free software tools with DocBook support in
Debian. The source format of later books have been docx via rst,
Markdown, Filemaker and Asciidoc, and for all of these I was able to
generate a suitable DocBook file for further processing using
pandoc,
a2x and
asciidoctor,
as well as rendering using
xmlto,
dbtoepub,
dblatex,
docbook-xsl and
fop.
Most of the books I
have published are translated books, with English as the source
language. The use of
po4a to
handle translations using the gettext PO format has been a blessing,
but publishing translated books had triggered the need to ensure the
DocBook tools handle relevant languages correctly. For every new
language I have published, I had to submit patches dblatex, dbtoepub
and docbook-xsl fixing incorrect language and country specific issues
in the framework themselves. Typically this has been missing keywords
like 'figure' or sort ordering of index entries. After a while it
became tiresome to only discover issues like this by accident, and I
decided to write a DocBook "test framework" exercising various
features of DocBook and allowing me to see all features exercised for
a given language. It consist of a set of DocBook files, a version 4
book, a version 5 book, a v4 book set, a v4 selection of problematic
tables, one v4 testing sidefloat and finally one v4 testing a book of
articles. The DocBook files are accompanied with a set of build rules
for building PDF using dblatex and docbook-xsl/fop, HTML using xmlto
or docbook-xsl and epub using dbtoepub. The result is a set of files
visualizing footnotes, indexes, table of content list, figures,
formulas and other DocBook features, allowing for a quick review on
the completeness of the given locale settings. To build with a
different language setting, all one need to do is edit the lang= value
in the .xml file to pick a different ISO 639 code value and run
'make'.
The test framework
source code is available from Codeberg, and a generated set of
presentations of the various examples is available as Codeberg static
web pages at
https://pere.codeberg.page/docbook-example/.
Using this test framework I have been able to discover and report
several bugs and missing features in various tools, and got a lot of
them fixed. For example I got Northern Sami keywords added to both
docbook-xsl and dblatex, fixed several typos in Norwegian bokmål and
Norwegian Nynorsk, support for non-ascii title IDs added to pandoc,
Norwegian index sorting support fixed in xindy and initial Norwegian
Bokmål support added to dblatex. Some issues still remains, though.
Default index sorting rules are still broken in several tools, so the
Norwegian letters æ, ø and å are more often than not sorted properly
in the book index.
The test framework recently received some more polish, as part of
publishing my latest book. This book contained a lot of fairly
complex tables, which exposed bugs in some of the tools. This made me
add a new test file with various tables, as well as spend some time to
brush up the build rules. My goal is for the test framework to
exercise all DocBook features to make it easier to see which features
work with different processors, and hopefully get them all to support
the full set of DocBook features. Feel free to send patches to extend
the test set, and test it with your favorite DocBook processor.
Please visit these two URLs to learn more:
If you want to learn more on Docbook and translations, I recommend
having a look at the the DocBook
web site,
the DoCookBook
site and my earlier blog post on
how
the Skolelinux project process and translate documentation, a talk I gave earlier this year on
how
to translate and publish books using free software (Norwegian
only).
As usual, if you use Bitcoin and want to show your support of my
activities, please send Bitcoin donations to my address
15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.
