blog/data/2012-03-16-skolelinux-doc.txt

   1 Title: Writing and translating documentation in Debian Edu
   2 Tags: english, debian edu
   3 Date: 2012-03-16 09:55
   4
   5 <p>Documentation in Debian Edu is provided in several languages, and
   6 it is important to make it both easy to contribute and to keep the
   7 translated versions in sync.  To do this we have come up with what we
   8 believe is a very efficient work flow.</p>
   9
  10 <ol>
  11
  12 <li>The documentation is written in a
  13 <a href="http://moinmo.in">moinmoin wiki</a> (see for example
  14 <a href="http://wiki.debian.org/DebianEdu/Documentation/Squeeze">the
  15 Squeeze release manual</a>) with support for exporting the content as
  16 docbook XML.</li>
  17
  18 <li>This docbook document is given to po4a to extract a gettext style
  19 .pot file with the content, which in turn is used to create .po files
  20 with the translated text.</li>
  21
  22 <li>The .po files are given to translators, and they can always tell
  23 which part of the original wiki document is new or changed.  They can
  24 use their normal translation tools like lokalize or poedit to write
  25 the translation.  There is even a system in place to handle translated
  26 images.</li>
  27
  28 <li>The translated .po files are combined with the original docbook
  29 XML document using po4a to create a translated docbook document.</li>
  30
  31 <li>The final step is to use all the generated docbook files and
  32 create PDF and HTML version of the original and translated documents.</li>
  33
  34 </ol>
  35
  36 <p>This setup work very well, but have a few issues.  The biggest
  37 issue is that <a href="http://moinmo.in/DocBook">the docbook support
  38 we use in moinmoin</a> is not actively maintained.  The docbook
  39 support is also buggy, and our build system contain workarounds to
  40 make sure the generated docbook is usable despite these bugs.</p>
  41
  42 <p>If you want to have a look at our setup, it is all there in the
  43 <a href="http://packages.qa.debian.org/debian-edu-doc">debian-edu-doc
  44 package</a>.</p>