This mail is a follow-up on a conversation with Osamu at FOSDEM. I will try to explain the main structure of the manual itself and its buildscripts. I'll also note the main open issues and current developments. The source for the manual can be found in debian-installer's SVN repo on alioth. You can make an anonymous checkout of only the manual using: svn co svn://svn.d-i.alioth.debian.org/d-i/trunk/installer/doc/manual The ./en/ subdir contains the original English version of the manual. Currently, most translations are done by directly translating the XML files. These translations have their own directory. We are however ATM implementing the use of PO files for translation and these and the templates can be found in the ./po subdirectory. We have developed several tools to help with translations (see ./scripts). The ./build subdirectory contains everything needed to build the manual into different formats. Currently we support HTML, PDF, PS and TXT; TEX and DVI are used only as intermediate formats. Basic documentation: ./build/README: explains how to build the manual and role of files ./translations.txt: basic information for translators ./translations_po.txt: translating using PO files (will be updated soon) The main script for building the manual is ./build/buildone.sh. This builds the manual for a particular architecture/language combination. It can be executed as 'buildone.sh <architecture> <language> <format(s)>'; by default it will build the English HTML version for i386. Example: buildone.sh sparc nl "html pdf" If you read this script you will see what tools we use to generate the different formats and what special manipulations are needed in some cases. There are three "wrapper" scripts (that repeatedly call buildone.sh) in use to build multiple variants of the manual: - ./build/build.sh: official version as included on installation CDs - ./build/buildweb.sh: official version as available from www.debian.org Sarge release pages and listed on debian-doc pages - my private build scripts used for daily development builds The last set of scripts is archived in d-i's SVN repo [1]. These scripts are much more complex as they perform multiple functions: - update local SVN repo - check for changes in English version and translations - update templates and PO files (if needed); commit any changes to SVN - build the manual for languages that were changed - upload buildlogs for individual languages to my homepage at Tiscali - calculate translation statistics - generate a new index page for http://d-i.alioth.debian.org/manual/ - upload and install to alioth.debian.org - send mails to translators for languages that were built and a summary of the whole build to myself [1] http://svn.debian.org/wsvn/d-i/trunk/scripts/manual-daily/ We are not completely happy with the current PDF files. For one we can only really build langs that use Western encodings. Russian works, but is not very pretty; Japanese and Greek are currently not possible. Nikolai Prokoschenko has done a lot of work on improving db2latex for use with the manual. His work has been committed to d-i's SVN repo and can be tested by using the ./build/buildone_ng.sh script. For more info on this, I suggest you contact Nikolai (see CC for address). If you have any questions, feel free to ask. Cheers, Frans Pop
Attachment:
pgp_T_rdLMFmE.pgp
Description: PGP signature