The Debian Edu / Skolelinux
-project provide an instruction manual for teachers, system
-administrators and other users that contain useful tips for setting up
-and maintaining a Debian Edu installation. This text is about how the
-text processing of this manual is handled in the project.
-
-
One goal of the project is to provide information in the native
-language of its users, and for this we need to handle translations.
-But we also want to make sure each language contain the same
-information, so for this we need a good way to keep the translations
-in sync. And we want it to be easy for our users to improve the
-documentation, avoiding the need to learn special formats or tools to
-contribute, and the obvious way to do this is to make it possible to
-edit the documentation using a web browser. We also want it to be
-easy for translators to keep the translation up to date, and give them
-help in figuring out what need to be translated. Here is the list of
-tools and the process we have found trying to reach all these
-goals.
-
-
We maintain the authoritative source of our manual in the
-Debian
-wiki, as several wiki pages written in English. It consist of one
-front page with references to the different chapters, several pages
-for each chapter, and finally one "collection page" gluing all the
-chapters together into one large web page (aka
-the
-AllInOne page). The AllInOne page is the one used for further
-processing and translations. Thanks to the fact that the
-MoinMoin installation on
-wiki.debian.org support exporting pages in
-the Docbook format, we can fetch
-the list of pages to export using the raw version of the AllInOne
-page, loop over each of them to generate a Docbook XML version of the
-manual. This process also download images and transform image
-references to use the locally downloaded images. The generated
-Docbook XML files are slightly broken, so some post-processing is done
-using the documentation/scripts/get_manual program, and the
-result is a nice Docbook XML file (debian-edu-wheezy-manual.xml) and
-a handfull of images. The XML file can now be used to generate PDF, HTML
-and epub versions of the English manual. This is the basic step of
-our process, making PDF (using dblatex), HTML (using xsltproc) and
-epub (using dbtoepub) version from Docbook XML, and the resulting files
-are placed in the debian-edu-doc-en binary package.
-
-
But English documentation is not enough for us. We want translated
-documentation too, and we want to make it easy for translators to
-track the English original. For this we use the
-poxml package,
-which allow us to transform the English Docbook XML file into a
-translation file (a .pot file), usable with the normal gettext based
-translation tools used by those translating free software. The pot
-file is used to create and maintain translation files (several .po
-files), which the translations update with the native language
-translations of all titles, paragraphs and blocks of text in the
-original. The next step is combining the original English Docbook XML
-and the translation file (say debian-edu-wheezy-manual.nb.po), to
-create a translated Docbook XML file (in this case
-debian-edu-wheezy-manual.nb.xml). This translated (or partly
-translated, if the translation is not complete) Docbook XML file can
-then be used like the original to create a PDF, HTML and epub version
-of the documentation.
-
-
The translators use different tools to edit the .po files. We
-recommend using
-lokalize,
-while some use emacs and vi, others can use web based editors like
-Poodle or
-Transifex. All we care about
-is where the .po file end up, in our git repository. Updated
-translations can either be committed directly to git, or submitted as
-bug reports
-against the debian-edu-doc package.
-
-
One challenge is images, which both might need to be translated (if
-they show translated user applications), and are needed in different
-formats when creating PDF and HTML versions (epub is a HTML version in
-this regard). For this we transform the original PNG images to the
-needed density and format during build, and have a way to provide
-translated images by storing translated versions in
-images/$LANGUAGECODE/. I am a bit unsure about the details here. The
-package maintainers know more.
-
-
If you wonder what the result look like, we provide
-the content
-of the documentation packages on the web. See for example the
-Italian
-PDF version or the
-German
-HTML version. We do not yet build the epub version by default,
-but perhaps it will be done in the future.
-
-
To learn more, check out
-the
-debian-edu-doc package,
-the
-manual on the wiki and
-the
-translation instructions in the manual.
-
