[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Debian Installer Manual structure and build tools

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 
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 

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.

Frans Pop

Attachment: pgp_T_rdLMFmE.pgp
Description: PGP signature

Reply to: