blog/archive/2023/11/11.rss

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <rss version='2.0' xmlns:lj='http://www.livejournal.org/rss/lj/1.0/'>
   3         <channel>
   4                 <title>Petter Reinholdtsen - Entries from November 2023</title>
   5                 <description>Entries from November 2023</description>
   6                 <link>https://people.skolelinux.org/pere/blog/</link>
   7
   8
   9         <item>
  10                 <title>Test framework for DocBook processors / formatters</title>
  11                 <link>https://people.skolelinux.org/pere/blog/Test_framework_for_DocBook_processors___formatters.html</link>
  12                 <guid isPermaLink="true">https://people.skolelinux.org/pere/blog/Test_framework_for_DocBook_processors___formatters.html</guid>
  13                 <pubDate>Sun, 5 Nov 2023 13:00:00 +0100</pubDate>
  14                 <description>&lt;p&gt;All the books I have published so far has been using
  15 &lt;a href=&quot;https://docbook.org/&quot;&gt;DocBook&lt;/a&gt; somewhere in the process.
  16 For the first book, the source format was DocBook, while for every
  17 later book it was an intermediate format used as the stepping stone to
  18 be able to present the same manuscript in several formats, on paper,
  19 as ebook in ePub format, as a HTML page and as a PDF file either for
  20 paper production or for Internet consumption.  This is made possible
  21 with a wide variety of free software tools with DocBook support in
  22 Debian.  The source format of later books have been docx via rst,
  23 Markdown, Filemaker and Asciidoc, and for all of these I was able to
  24 generate a suitable DocBook file for further processing using
  25 &lt;a href=&quot;https://tracker.debian.org/pkg/pandoc&quot;&gt;pandoc&lt;/a&gt;,
  26 &lt;a href=&quot;https://tracker.debian.org/pkg/asciidoc&quot;&gt;a2x&lt;/a&gt; and
  27 &lt;a href=&quot;https://tracker.debian.org/pkg/asciidoctor&quot;&gt;asciidoctor&lt;/a&gt;,
  28 as well as rendering using
  29 &lt;a href=&quot;https://tracker.debian.org/pkg/xmlto&quot;&gt;xmlto&lt;/a&gt;,
  30 &lt;a href=&quot;https://tracker.debian.org/pkg/dbtoepub&quot;&gt;dbtoepub&lt;/a&gt;,
  31 &lt;a href=&quot;https://tracker.debian.org/pkg/dblatex&quot;&gt;dblatex&lt;/a&gt;,
  32 &lt;a href=&quot;https://tracker.debian.org/pkg/docbook-xsl&quot;&gt;docbook-xsl&lt;/a&gt; and
  33 &lt;a href=&quot;https://tracker.debian.org/pkg/fop&quot;&gt;fop&lt;/a&gt;.&lt;/p&gt;
  34
  35 &lt;p&gt;Most of the &lt;a href=&quot;http://www.hungry.com/~pere/publisher/&quot;&gt;books I
  36 have published&lt;/a&gt; are translated books, with English as the source
  37 language.  The use of
  38 &lt;a href=&quot;https://tracker.debian.org/pkg/po4a&quot;&gt;po4a&lt;/a&gt; to
  39 handle translations using the gettext PO format has been a blessing,
  40 but publishing translated books had triggered the need to ensure the
  41 DocBook tools handle relevant languages correctly.  For every new
  42 language I have published, I had to submit patches dblatex, dbtoepub
  43 and docbook-xsl fixing incorrect language and country specific issues
  44 in the framework themselves.  Typically this has been missing keywords
  45 like &#39;figure&#39; or sort ordering of index entries.  After a while it
  46 became tiresome to only discover issues like this by accident, and I
  47 decided to write a DocBook &quot;test framework&quot; exercising various
  48 features of DocBook and allowing me to see all features exercised for
  49 a given language.  It consist of a set of DocBook files, a version 4
  50 book, a version 5 book, a v4 book set, a v4 selection of problematic
  51 tables, one v4 testing sidefloat and finally one v4 testing a book of
  52 articles.  The DocBook files are accompanied with a set of build rules
  53 for building PDF using dblatex and docbook-xsl/fop, HTML using xmlto
  54 or docbook-xsl and epub using dbtoepub.  The result is a set of files
  55 visualizing footnotes, indexes, table of content list, figures,
  56 formulas and other DocBook features, allowing for a quick review on
  57 the completeness of the given locale settings.  To build with a
  58 different language setting, all one need to do is edit the lang= value
  59 in the .xml file to pick a different ISO 639 code value and run
  60 &#39;make&#39;.&lt;/p&gt;
  61
  62 &lt;p&gt;The &lt;a href=&quot;https://codeberg.org/pere/docbook-example/&quot;&gt;test framework
  63 source code&lt;/a&gt; is available from Codeberg, and a generated set of
  64 presentations of the various examples is available as Codeberg static
  65 web pages at
  66 &lt;a href=&quot;https://pere.codeberg.page/docbook-example/&quot;&gt;https://pere.codeberg.page/docbook-example/&lt;/a&gt;.
  67 Using this test framework I have been able to discover and report
  68 several bugs and missing features in various tools, and got a lot of
  69 them fixed.  For example I got Northern Sami keywords added to both
  70 docbook-xsl and dblatex, fixed several typos in Norwegian bokmål and
  71 Norwegian Nynorsk, support for non-ascii title IDs added to pandoc,
  72 Norwegian index sorting support fixed in xindy and initial Norwegian
  73 Bokmål support added to dblatex.  Some issues still remains, though.
  74 Default index sorting rules are still broken in several tools, so the
  75 Norwegian letters æ, ø and å are more often than not sorted properly
  76 in the book index.&lt;/p&gt;
  77
  78 &lt;p&gt;The test framework recently received some more polish, as part of
  79 publishing my latest book.  This book contained a lot of fairly
  80 complex tables, which exposed bugs in some of the tools.  This made me
  81 add a new test file with various tables, as well as spend some time to
  82 brush up the build rules.  My goal is for the test framework to
  83 exercise all DocBook features to make it easier to see which features
  84 work with different processors, and hopefully get them all to support
  85 the full set of DocBook features.  Feel free to send patches to extend
  86 the test set, and test it with your favorite DocBook processor.
  87 Please visit these two URLs to learn more:&lt;/p&gt;
  88
  89 &lt;ul&gt;
  90 &lt;li&gt;&lt;a href=&quot;https://codeberg.org/pere/docbook-example/&quot;&gt;https://codeberg.org/pere/docbook-example/&lt;/a&gt;&lt;/li&gt;
  91 &lt;li&gt;&lt;a href=&quot;https://pere.codeberg.page/docbook-example/&quot;&gt;https://pere.codeberg.page/docbook-example/&lt;/a&gt;&lt;/li&gt;
  92 &lt;/ul&gt;
  93
  94 &lt;p&gt;If you want to learn more on Docbook and translations, I recommend
  95 having a look at the &lt;a href=&quot;https://docbook.org/&quot;&gt;the DocBook
  96 web site&lt;/a&gt;,
  97 &lt;a href=&quot;https://doccookbook.sourceforge.net/html/en/&quot;&gt;the DoCookBook
  98 site&lt;a/&gt; and my earlier blog post on
  99 &lt;a href=&quot;https://people.skolelinux.org/pere/blog/From_English_wiki_to_translated_PDF_and_epub_via_Docbook.html&quot;&gt;how
 100 the Skolelinux project process and translate documentation&lt;/a&gt;,  a talk I gave earlier this year on
 101 &lt;a href=&quot;https://www.nuug.no/aktiviteter/20230314-oversetting-og-publisering-av-b%c3%b8ker-med-fri-programvare/&quot;&gt;how
 102 to translate and publish books using free software&lt;/a&gt; (Norwegian
 103 only).&lt;/p&gt;
 104
 105 &lt;!--
 106
 107 https://github.com/docbook/xslt10-stylesheets/issues/205 (docbook-xsl: sme support)
 108 https://bugs.debian.org/968437 (xindy: index sorting rules for nb/nn)
 109 https://bugs.debian.org/856123 (pandoc: markdown to docbook with non-english titles)
 110 https://bugs.debian.org/864813 (dblatex: missing nb words)
 111 https://bugs.debian.org/756386 (dblatex: index sorting rules for nb/nn)
 112 https://bugs.debian.org/796871 (dbtoepub: index sorting rules for nb/nn)
 113 https://bugs.debian.org/792616 (dblatex: PDF metadata)
 114 https://bugs.debian.org/686908 (docbook-xsl: index sorting rules for nb/nn)
 115 https://sourceforge.net/tracker/?func=detail&amp;atid=373747&amp;aid=3556630&amp;group_id=21935 (docbook-xsl: nb/nn support)
 116 https://bugs.debian.org/684391 (dblatex: initial nb support)
 117
 118 --&gt;
 119
 120 &lt;p&gt;As usual, if you use Bitcoin and want to show your support of my
 121 activities, please send Bitcoin donations to my address
 122 &lt;b&gt;&lt;a href=&quot;bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b&quot;&gt;15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b&lt;/a&gt;&lt;/b&gt;.&lt;/p&gt;
 123 </description>
 124         </item>
 125
 126         </channel>
 127 </rss>