X-Git-Url: https://pere.pagekite.me/gitweb/homepage.git/blobdiff_plain/13ecfe10c9aef14011b39139489be0ccc9b7c858..79b17322a1499c950be4ad8799ca2ba019116b81:/blog/archive/2014/06/06.rss diff --git a/blog/archive/2014/06/06.rss b/blog/archive/2014/06/06.rss index 82442eef3b..93ec610dc4 100644 --- a/blog/archive/2014/06/06.rss +++ b/blog/archive/2014/06/06.rss @@ -6,6 +6,112 @@ http://people.skolelinux.org/pere/blog/ + + From English wiki to translated PDF and epub via Docbook + http://people.skolelinux.org/pere/blog/From_English_wiki_to_translated_PDF_and_epub_via_Docbook.html + http://people.skolelinux.org/pere/blog/From_English_wiki_to_translated_PDF_and_epub_via_Docbook.html + Tue, 17 Jun 2014 11:30:00 +0200 + <p>The <a href="http://www.skolelinux.org/">Debian Edu / Skolelinux +project</a> 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.</p> + +<p>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.</p> + +<p>We maintain the authoritative source of our manual in the +<a href="https://wiki.debian.org/DebianEdu/Documentation/Wheezy/">Debian +wiki</a>, 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 +<a href="https://wiki.debian.org/DebianEdu/Documentation/Wheezy/AllInOne">the +AllInOne page</a>). The AllInOne page is the one used for further +processing and translations. Thanks to the fact that the +<a href="http://moinmo.in/">MoinMoin</a> installation on +wiki.debian.org support exporting pages in +<a href="http://www.docbook.org/">the Docbook format</a>, 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 <tt>documentation/scripts/get_manual</tt> 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.</p> + +<p>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 +<a href="http://packages.qa.debian.org/p/poxml.html">poxml</a> 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.</p> + +<p>The translators use different tools to edit the .po files. We +recommend using +<a href="http://www.kde.org/applications/development/lokalize/">lokalize</a>, +while some use emacs and vi, others can use web based editors like +<a href="http://pootle.translatehouse.org/">Poodle</a> or +<a href="https://www.transifex.com/">Transifex</a>. 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 +<a href="https://bugs.debian.org/src:debian-edu-doc">bug reports +against the debian-edu-doc package</a>.</p> + +<p>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.</p> + +<p>If you wonder what the result look like, we provide +<a href="http://maintainer.skolelinux.org/debian-edu-doc/">the content +of the documentation packages on the web</a>. See for example the +<a href="http://maintainer.skolelinux.org/debian-edu-doc/it/debian-edu-wheezy-manual.pdf">Italian +PDF version</a> or the +<a href="http://maintainer.skolelinux.org/debian-edu-doc/de/debian-edu-wheezy-manual.html">German +HTML version</a>. We do not yet build the epub version by default, +but perhaps it will be done in the future.</p> + +<p>To learn more, check out +<a href="http://packages.qa.debian.org/d/debian-edu-doc.html">the +debian-edu-doc package</a>, +<a href="https://wiki.debian.org/DebianEdu/Documentation/Wheezy/">the +manual on the wiki</a> and +<a href="https://wiki.debian.org/DebianEdu/Documentation/Wheezy/Translations">the +translation instructions</a> in the manual.</p> + + + Hvordan enkelt laste ned filmer fra NRK med den "nye" løsningen http://people.skolelinux.org/pere/blog/Hvordan_enkelt_laste_ned_filmer_fra_NRK_med_den__nye__l_sningen.html @@ -45,6 +151,16 @@ hvordan overvåkningen av borgerne brer om seg.</p> <p>Takk til gode venner på foreningen NUUGs IRC-kanal <a href="irc://irc.freenode.net/%23nuug">#nuug på irc.freenode.net</a> for tipsene som fikk meg i mål</a>.</p> + +<p><strong>Oppdatering 2014-06-17</strong>: Etter at jeg publiserte +denne, ble jeg tipset om bloggposten +"<a href="http://ingvar.blog.redpill-linpro.com/2012/05/31/downloading-hd-content-from-tv-nrk-no/">Downloading +HD content from tv.nrk.no</a>" av Ingvar Hagelund, som har alternativ +implementasjon og tips for å lage mkv-fil med undertekstene inkludert. +Kanskje den passer bedre for deg? I tillegg ble feilen i youtube-dl +ble fikset litt senere ut på dagen i går, samt at youtube-dl fikk +støtte for å laste ned undertitler. Takk til Anders Einar Hilden for +god innsats og youtube-dl-utviklerne for rask respons.</p>