blog/2013_03_24_docbook_shortstory.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" dir="ltr">
   4   <head>
   5     <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
   6     <title>Petter Reinholdtsen: 2013-03-24-docbook-shortstory</title>
   7     <link rel="stylesheet" type="text/css" media="screen" href="http://people.skolelinux.org/pere/blog/style.css" />
   8     <link rel="stylesheet" type="text/css" media="screen" href="http://people.skolelinux.org/pere/blog/vim.css" />
   9
  10
  11   </head>
  12   <body>
  13     <div class="title">
  14  <h1>
  15      <a href="http://people.skolelinux.org/pere/blog/">Petter Reinholdtsen</a>
  16
  17  </h1>
  18
  19 </div>
  20
  21
  22     <div class="entry">
  23       <div class="title">2013-03-24-docbook-shortstory</div>
  24       <div class="date">24th March 2013</div>
  25       <div class="body"><p>A few days ago, during a discussion in
  26 <ahref="http://www.efn.no/">EFN</a> about interesting books to read
  27 about copyright and the data retention directive, a suggestion to read
  28 the old 1968 short story Kodémus by Tore Åge Bringsværd came up.  The
  29 text is only available in old paper books, and thus hard to read for
  30 the current and future generations.  Some of the people participating
  31 in the discussion contacted the author, and reported back 2013-03-19
  32 that he was ok with releasing the short story using a Creative Commons
  33 license (CC-BY-NC-ND).  The text was quickly scanned and OCR-ed, and
  34 we were ready to start on the editing and typesetting.</p>
  35
  36 <p>As I already had some experience formatting text in my project to
  37 provide a Norwegian version of the Free Culture book by Lawrence
  38 Lessig, I chipped in and set up a
  39 <ahref="http://www.docbook.org/">DocBook</a> processing framework to
  40 generate a PDF, HTML and EPUB version of the short story.  The tools
  41 to transform DocBook to different formats are already in my Linux
  42 distribution of choice, <ahref="http://www.debian.org/">Debian</a>, so
  43 all I had to do was to use the dblatex, dbtoepub and xmlto tools to do
  44 the conversion.  After a few days, we decided to replace dblatex with
  45 xsltproc/fop (aka docbook-xsl), to get the copyright information to
  46 show up in the PDF and to get a nicer &lt;variablelist&gt;
  47 typesetting.</p>
  48
  49 <p>There were a few challenges, of course.  We want to typeset the
  50 short story to look like the original, and that require fairly good
  51 control over the layout.  The original short story have three
  52 parts/scenes separated by a single horizontally centred star (*), and
  53 the paragraphs do not contain only flowing text, but dialogs and text
  54 that started on a new line in the middle of the paragraph.</p>
  55
  56 <p>I initially solved the first challenge by using a paragraph with a
  57 single star in it, ie &lt;para&gt;*&lt;/para&gt;.  This did not look
  58 too good without the centring.  The next approach was to create a new
  59 preprocessor directive &lt;?newscene?&gt;, mapping to "&lt;hr/&gr;"
  60 for HTML and "&lt;fo:block text-align="center"&gt;&lt;fo:leader
  61 leader-pattern="rule" rule-thickness="0.5pt"/&gt;&lt;/fo:block&gt;"
  62 for FO/PDF output (did not try to implement this in dblatex, as we had
  63 switched at this time).  The HTML XSL file looked like this:</p>
  64
  65 <p><blockquote><pre>
  66 &lt;?xml version='1.0'?&gt;
  67 &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'&gt;
  68   &lt;xsl:template match="processing-instruction('newscene')"&gt;
  69     &lt;hr/&gt;
  70   &lt;/xsl:template&gt;
  71 &lt;/xsl:stylesheet&gt;
  72 </pre></blockquote></p>
  73
  74 <p>And the FO/PDF XSL file looked like this:</p>
  75
  76 <p><blockquote><pre>
  77 &lt;?xml version='1.0'?&gt;
  78 &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'&gt;
  79   &lt;xsl:template match="processing-instruction('newscene')"&gt;
  80     &lt;fo:block text-align="center"&gt;
  81       &lt;fo:leader leader-pattern="rule" rule-thickness="0.5pt"/&gt;
  82     &lt;/fo:block&gt;
  83   &lt;/xsl:template&gt;
  84 &lt;/xsl:stylesheet&gt;
  85 </pre></blockquote></p>
  86
  87 <p>Finally, I came across the &lt;bridgehead&gt; tag, which seem to be
  88 a good fit for the task at hand, and I replaced &lt;?newscene?&gt;
  89 with &lt;bridgehead&gt;*&lt;/bridgehead&gt;.  It isn't centered, but
  90 we can fix that with XSL rules if the current visual layout isn't
  91 enough.</p>
  92
  93 <p>I did not find a good DocBook compliant way to solve the
  94 linebreak/paragraph challenge, so I ended up creating a new processor
  95 directive &lt;?linebreak?&gt;, mapping to &lt;br/&gt; in HTML, and
  96 &lt;fo:block/&gr; in FO/PDF.  I suspect there are better ways to do
  97 this, and welcome ideas and patches on github.  The HTML XSL file now
  98 look like this:</p>
  99
 100 <p><blockquote><pre>
 101 &lt;?xml version='1.0'?&gt;
 102 &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'&gt;
 103   &lt;xsl:template match="processing-instruction('linebreak)"&gt;
 104     &lt;br/&gt;
 105   &lt;/xsl:template&gt;
 106 &lt;/xsl:stylesheet&gt;
 107 </pre></blockquote></p>
 108
 109 <p>And the FO/PDF XSL file looked like this:</p>
 110
 111 <p><blockquote><pre>
 112 &lt;?xml version='1.0'?&gt;
 113 &lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'
 114   xmlns:fo="http://www.w3.org/1999/XSL/Format"&gt;
 115   &lt;xsl:template match="processing-instruction('linebreak)"&gt;
 116     &lt;fo:block/&gt;
 117   &lt;/xsl:template&gt;
 118 &lt;/xsl:stylesheet&gt;
 119 </pre></blockquote></p>
 120
 121 <p>One unsolved challenge is our wish to expose different ISBN numbers
 122 per publication format, while keeping all of them in some conditional
 123 structure in the DocBook source.  No idea how to do this, so we ended
 124 up listing all the ISBN numbers next to their format in the colophon
 125 page.</p>
 126
 127 <p>If you want to check out the finished result, check out the
 128 <ahref="https://github.com/sickel/kodemus">source repository at
 129 github</a> (<ahref="https://github.com/EFN/kodemus">future/new
 130 repository</a>).</p>
 131
 132
 133
 134
 135 </div>
 136
 137
 138     </div>
 139
 140
 141
 142
 143     <div id="sidebar">
 144
 145
 146
 147 <h2>Archive</h2>
 148 <ul>
 149
 150 <li>2013
 151 <ul>
 152
 153 <li><a href="http://people.skolelinux.org/pere/blog/archive/2013/01/">January (11)</a></li>
 154
 155 <li><a href="http://people.skolelinux.org/pere/blog/archive/2013/02/">February (9)</a></li>
 156
 157 <li><a href="http://people.skolelinux.org/pere/blog/archive/2013/03/">March (7)</a></li>
 158
 159 </ul></li>
 160
 161 <li>2012
 162 <ul>
 163
 164 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/01/">January (7)</a></li>
 165
 166 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/02/">February (10)</a></li>
 167
 168 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/03/">March (17)</a></li>
 169
 170 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/04/">April (12)</a></li>
 171
 172 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/05/">May (12)</a></li>
 173
 174 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/06/">June (20)</a></li>
 175
 176 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/07/">July (17)</a></li>
 177
 178 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/08/">August (6)</a></li>
 179
 180 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/09/">September (9)</a></li>
 181
 182 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/10/">October (17)</a></li>
 183
 184 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/11/">November (10)</a></li>
 185
 186 <li><a href="http://people.skolelinux.org/pere/blog/archive/2012/12/">December (7)</a></li>
 187
 188 </ul></li>
 189
 190 <li>2011
 191 <ul>
 192
 193 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/01/">January (16)</a></li>
 194
 195 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/02/">February (6)</a></li>
 196
 197 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/03/">March (6)</a></li>
 198
 199 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/04/">April (7)</a></li>
 200
 201 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/05/">May (3)</a></li>
 202
 203 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/06/">June (2)</a></li>
 204
 205 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/07/">July (7)</a></li>
 206
 207 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/08/">August (6)</a></li>
 208
 209 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/09/">September (4)</a></li>
 210
 211 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/10/">October (2)</a></li>
 212
 213 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/11/">November (3)</a></li>
 214
 215 <li><a href="http://people.skolelinux.org/pere/blog/archive/2011/12/">December (1)</a></li>
 216
 217 </ul></li>
 218
 219 <li>2010
 220 <ul>
 221
 222 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/01/">January (2)</a></li>
 223
 224 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/02/">February (1)</a></li>
 225
 226 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/03/">March (3)</a></li>
 227
 228 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/04/">April (3)</a></li>
 229
 230 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/05/">May (9)</a></li>
 231
 232 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/06/">June (14)</a></li>
 233
 234 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/07/">July (12)</a></li>
 235
 236 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/08/">August (13)</a></li>
 237
 238 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/09/">September (7)</a></li>
 239
 240 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/10/">October (9)</a></li>
 241
 242 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/11/">November (13)</a></li>
 243
 244 <li><a href="http://people.skolelinux.org/pere/blog/archive/2010/12/">December (12)</a></li>
 245
 246 </ul></li>
 247
 248 <li>2009
 249 <ul>
 250
 251 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/01/">January (8)</a></li>
 252
 253 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/02/">February (8)</a></li>
 254
 255 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/03/">March (12)</a></li>
 256
 257 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/04/">April (10)</a></li>
 258
 259 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/05/">May (9)</a></li>
 260
 261 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/06/">June (3)</a></li>
 262
 263 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/07/">July (4)</a></li>
 264
 265 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/08/">August (3)</a></li>
 266
 267 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/09/">September (1)</a></li>
 268
 269 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/10/">October (2)</a></li>
 270
 271 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/11/">November (3)</a></li>
 272
 273 <li><a href="http://people.skolelinux.org/pere/blog/archive/2009/12/">December (3)</a></li>
 274
 275 </ul></li>
 276
 277 <li>2008
 278 <ul>
 279
 280 <li><a href="http://people.skolelinux.org/pere/blog/archive/2008/11/">November (5)</a></li>
 281
 282 <li><a href="http://people.skolelinux.org/pere/blog/archive/2008/12/">December (7)</a></li>
 283
 284 </ul></li>
 285
 286 </ul>
 287
 288
 289
 290 <h2>Tags</h2>
 291 <ul>
 292
 293  <li><a href="http://people.skolelinux.org/pere/blog/tags/3d-printer">3d-printer (13)</a></li>
 294
 295  <li><a href="http://people.skolelinux.org/pere/blog/tags/amiga">amiga (1)</a></li>
 296
 297  <li><a href="http://people.skolelinux.org/pere/blog/tags/aros">aros (1)</a></li>
 298
 299  <li><a href="http://people.skolelinux.org/pere/blog/tags/bankid">bankid (4)</a></li>
 300
 301  <li><a href="http://people.skolelinux.org/pere/blog/tags/bitcoin">bitcoin (6)</a></li>
 302
 303  <li><a href="http://people.skolelinux.org/pere/blog/tags/bootsystem">bootsystem (12)</a></li>
 304
 305  <li><a href="http://people.skolelinux.org/pere/blog/tags/bsa">bsa (2)</a></li>
 306
 307  <li><a href="http://people.skolelinux.org/pere/blog/tags/debian">debian (70)</a></li>
 308
 309  <li><a href="http://people.skolelinux.org/pere/blog/tags/debian edu">debian edu (121)</a></li>
 310
 311  <li><a href="http://people.skolelinux.org/pere/blog/tags/digistan">digistan (10)</a></li>
 312
 313  <li><a href="http://people.skolelinux.org/pere/blog/tags/docbook">docbook (7)</a></li>
 314
 315  <li><a href="http://people.skolelinux.org/pere/blog/tags/drivstoffpriser">drivstoffpriser (4)</a></li>
 316
 317  <li><a href="http://people.skolelinux.org/pere/blog/tags/english">english (183)</a></li>
 318
 319  <li><a href="http://people.skolelinux.org/pere/blog/tags/fiksgatami">fiksgatami (21)</a></li>
 320
 321  <li><a href="http://people.skolelinux.org/pere/blog/tags/fildeling">fildeling (12)</a></li>
 322
 323  <li><a href="http://people.skolelinux.org/pere/blog/tags/freeculture">freeculture (10)</a></li>
 324
 325  <li><a href="http://people.skolelinux.org/pere/blog/tags/frikanalen">frikanalen (11)</a></li>
 326
 327  <li><a href="http://people.skolelinux.org/pere/blog/tags/intervju">intervju (33)</a></li>
 328
 329  <li><a href="http://people.skolelinux.org/pere/blog/tags/isenkram">isenkram (5)</a></li>
 330
 331  <li><a href="http://people.skolelinux.org/pere/blog/tags/kart">kart (18)</a></li>
 332
 333  <li><a href="http://people.skolelinux.org/pere/blog/tags/ldap">ldap (8)</a></li>
 334
 335  <li><a href="http://people.skolelinux.org/pere/blog/tags/lenker">lenker (6)</a></li>
 336
 337  <li><a href="http://people.skolelinux.org/pere/blog/tags/ltsp">ltsp (1)</a></li>
 338
 339  <li><a href="http://people.skolelinux.org/pere/blog/tags/multimedia">multimedia (25)</a></li>
 340
 341  <li><a href="http://people.skolelinux.org/pere/blog/tags/norsk">norsk (226)</a></li>
 342
 343  <li><a href="http://people.skolelinux.org/pere/blog/tags/nuug">nuug (151)</a></li>
 344
 345  <li><a href="http://people.skolelinux.org/pere/blog/tags/offentlig innsyn">offentlig innsyn (7)</a></li>
 346
 347  <li><a href="http://people.skolelinux.org/pere/blog/tags/open311">open311 (2)</a></li>
 348
 349  <li><a href="http://people.skolelinux.org/pere/blog/tags/opphavsrett">opphavsrett (42)</a></li>
 350
 351  <li><a href="http://people.skolelinux.org/pere/blog/tags/personvern">personvern (65)</a></li>
 352
 353  <li><a href="http://people.skolelinux.org/pere/blog/tags/raid">raid (1)</a></li>
 354
 355  <li><a href="http://people.skolelinux.org/pere/blog/tags/reprap">reprap (11)</a></li>
 356
 357  <li><a href="http://people.skolelinux.org/pere/blog/tags/rfid">rfid (2)</a></li>
 358
 359  <li><a href="http://people.skolelinux.org/pere/blog/tags/robot">robot (6)</a></li>
 360
 361  <li><a href="http://people.skolelinux.org/pere/blog/tags/rss">rss (1)</a></li>
 362
 363  <li><a href="http://people.skolelinux.org/pere/blog/tags/ruter">ruter (4)</a></li>
 364
 365  <li><a href="http://people.skolelinux.org/pere/blog/tags/scraperwiki">scraperwiki (2)</a></li>
 366
 367  <li><a href="http://people.skolelinux.org/pere/blog/tags/sikkerhet">sikkerhet (29)</a></li>
 368
 369  <li><a href="http://people.skolelinux.org/pere/blog/tags/sitesummary">sitesummary (4)</a></li>
 370
 371  <li><a href="http://people.skolelinux.org/pere/blog/tags/skepsis">skepsis (4)</a></li>
 372
 373  <li><a href="http://people.skolelinux.org/pere/blog/tags/standard">standard (41)</a></li>
 374
 375  <li><a href="http://people.skolelinux.org/pere/blog/tags/stavekontroll">stavekontroll (3)</a></li>
 376
 377  <li><a href="http://people.skolelinux.org/pere/blog/tags/stortinget">stortinget (6)</a></li>
 378
 379  <li><a href="http://people.skolelinux.org/pere/blog/tags/surveillance">surveillance (15)</a></li>
 380
 381  <li><a href="http://people.skolelinux.org/pere/blog/tags/sysadmin">sysadmin (1)</a></li>
 382
 383  <li><a href="http://people.skolelinux.org/pere/blog/tags/valg">valg (7)</a></li>
 384
 385  <li><a href="http://people.skolelinux.org/pere/blog/tags/video">video (38)</a></li>
 386
 387  <li><a href="http://people.skolelinux.org/pere/blog/tags/vitenskap">vitenskap (4)</a></li>
 388
 389  <li><a href="http://people.skolelinux.org/pere/blog/tags/web">web (26)</a></li>
 390
 391 </ul>
 392
 393
 394     </div>
 395     <p style="text-align: right">
 396  Created by <a href="http://steve.org.uk/Software/chronicle">Chronicle v4.6</a>
 397 </p>
 398
 399   </body>
 400 </html>