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 keywoards 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.
+ + + +As usual, if you use Bitcoin and want to show your support of my +activities, please send Bitcoin donations to my address +15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b.
+