Move documentation files to separate directory

5 files changed, 909 insertions, 0 deletions

diff --git a/doc/building-ng.txt b/doc/building-ng.txt
new file mode 100644
index 000000000..0c9d5027a
--- /dev/null
+++ b/doc/building-ng.txt
@@ -0,0 +1,56 @@
+--------------------------------------------
+Build Scripts NG for Debian Installer Manual
+--------------------------------------------
+
+=====================================================================
+The development of the db2latex solution has completely stalled and
+therefore been deleted from the repository. The last version is still
+available from:
+svn://svn.debian.org/svn/d-i/tags/manual/20060102
+=====================================================================
+
+
+NG == 'new-generation'
+
+The NG scripts are the extremely experimental version of the original
+build scripts for the Debian Installer Manual.
+
+The main purpose for NG is to be able to generate print-ready
+documentation in non-latin-based languages, like Russian, Japanese,
+Greek etc. The ultimate goal could be creating a common base for
+generating good-looking print documentation from DocBook using only free
+(as in 'DFSG-free') software.
+
+****
+WARNING:
+THIS IS HIGHLY EXPERIMENTAL. USE IT ONLY IF YOU KNOW WHAT YOU ARE DOING!
+****
+
+The main change consists in scrapping OpenJade and JadeTeX and moving to
+using DB2LaTeX, which should be a more flexible solution anyway. Other
+possible solutions like XSL:FO are not yet feasible, as all the
+renderers are either proprietary or written in Java.
+
+The necessary parts of the package are:
+- build_ng.sh
+- buildone_ng.sh
+- templates/driver.xsl.template
+- stylesheets/style-pdf.xsl
+- stylesheets/lang-drivers/
+- stylesheets/db2latex/
+
+The last directory contains the current db2latex distribution. The main
+reason for putting it here is the need to implement some features not
+yet available through the upstream version. As soon as they are stable,
+they will eventually get integrated into the main db2latex package and
+removed from the SVN.
+
+Currently, not everything works as expected. The biggest problem is
+getting the tables right - current db2latex does not support the
+morerows property, which is actually quite useful. A patch needs to get
+written to support that, but I currently lack the necessary time to
+learn XSL to the extend needed and implement the changes. Thus, the
+project is currently in pre-alpha state, so don't expect usable results
+right now.
+
+Nikolai Prokoschenko (nikolai at prokoschenko dot de)
diff --git a/doc/building.txt b/doc/building.txt
new file mode 100644
index 000000000..b3f533572
--- /dev/null
+++ b/doc/building.txt
@@ -0,0 +1,112 @@
+This document describes how the scripts in this directory can be used for
+building the Debian Installer Manual.
+
+The scripts support building the manual for different architectures, in
+different languages and in different document types.
+The currently supported document types are:
+- html
+- pdf
+- ps
+- txt
+
+Note: Building pdf and ps versions of the manual is not supported for some
+      languages. Reason is that we have not yet figured out how to use the
+      required fonts in the build process.
+
+
+1. Requirements:
+================
+
+The build dependencies depend on which document types you wish to generate:
+all     : docbook, docbook-xml, docbook-xsl, xsltproc
+html    : (no additional packages required)
+pdf, ps : openjade, jadetex, docbook-dsssl
+pdf     : gs-common
+txt     : w3m
+
+For some languages additional packages are needed to build pdf:
+ko      : latex-hangul-ucs-hlatex
+ru      : cm-super (type1 fonts)
+
+Note: It's not possible to build the documentation on Woody as packages are
+      required that are not available for Woody.
+Note: jadetex depends on tetex-bin which unfortunately depends on some X libs,
+      so installing jadetex will pull in a basic X installation.
+      There are several open bugs about this (the oldest over 3 years old, but
+      it seems nobody cares enough to fix it (see #223728).
+
+2. Included Files:
+==================
+
+SCRIPTS
+-------
+buildone.sh: For given architecture and language builds one set of
+    documentation in .html, .fo (and sometimes .pdf).
+
+build.sh: For each language and architecture calls buildone.sh, moves
+    rendered documentation somewhere and cleans after that.
+
+clear.sh: Does the actual cleaning.
+
+In ./templates
+--------------
+install.xml.template: Main xml file used to aggregate various parts into
+    one big whole. This is a bit customized compared to the original
+    (changed SYSTEM entities, hardcode local path to docbook dtd -- broken
+    system xml catalogs?)
+
+docstruct.ent: Describes physical structure of documentation. Not
+    included directly (because of hardcoded en/ path), but in a form
+    of dynamic.ent (after some path replacing by sed).
+
+In ./entities
+-------------
+common.ent: Contains various entities like &num-of-distrib-packages;
+    &debian; &arch-title; ...
+
+urls.ent: Contains various urls used through the manual.
+
+dynamic.ent: Generated on-the-fly from the shell script buildone.sh.
+    Contains lang and arch specific entities which can't be profiled
+    the usual xml way.
+
+any other .ent: Location of installation files (kernels, boot disks,
+    base tarballs) for various architectures.
+
+In ./stylesheets
+----------------
+style-common.xsl: Common parameters for xsl transformation.
+
+style-html.xsl: HTML-specific parameters for xsl transformation.
+
+style-print.dsl: Parameters for dvi transformation.
+
+style-fo.xsl: FO-specific parameters for xsl transformation.
+    (currently unused)
+
+In ./arch-options
+-----------------
+A file for each architecture where architecture specific parameters
+are set.
+
+3. Building:
+============
+
+After you customize build*.sh and style-*.xsl to suit your needs
+(esp. various paths), you can run
+
+ ./buildone.sh <architecture> <language> <format(s)>
+
+to build documentation for one specific architecture and language, and
+one or more output formats.
+If you call buildone.sh without any parameters, it will build the html
+version of the English manual for i386 (equivalent to 'i386 en html').
+If you specify multiple output formats, you should put quotes around them.
+Example: ./buildone.sh sparc es "html pdf"
+
+For mass building you can use ./build.sh script.
+
+
+-- 
+05. December 2004 Frans Pop
+27. January 2004  Miroslav Kure 
diff --git a/doc/cheatsheet.xml b/doc/cheatsheet.xml
new file mode 100644
index 000000000..413a219e0
--- /dev/null
+++ b/doc/cheatsheet.xml
@@ -0,0 +1,255 @@
+<!-- -*- DocBook -*- -->
+<?xml version='1.0'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" [
+  <!ENTITY arches SYSTEM "arches.ent" >
+  <!ENTITY debianwebsite "http://www.debian.org" >
+  <!ENTITY entities "entities" >
+]>
+
+<book>
+ <title>The Title for the Book</title>
+
+<chapter>
+ <title>The Chapter Title</title>
+
+<!-- note to debiandoc users: there is no sect, start with sect1 -->
+ <sect1 id="sect1-cross-referencable-id">
+ <title>First Level Section</title>
+<para>
+
+A paragraph explaining something In this manual we will make extensive
+use of &entities;, to insert the contents of smaller independent
+files. This should help translators; any changes will be easier to
+find within the files. We will try to keep the files
+<emphasis>small</emphasis>, feel free to create new ones for new
+subjects or subtopics.
+
+</para><para>
+
+This example document contains some of the most useful types
+of xml markup for our purposes. Some quick rules: 
+
+<itemizedlist>
+ <listitem><para>
+
+All tags must be in lower case
+
+ </para></listitem>
+ <listitem><para>
+
+Every tag must have a closing tag also
+
+ </para></listitem>
+ <listitem><para>
+
+No abbreviations in the tags
+
+ </para></listitem>
+</itemizedlist>
+
+and preferences:
+
+<orderedlist>
+ <listitem><para>
+
+Keep starting tags to the left margin as much as possible
+
+ </para></listitem>
+ <listitem><para>
+
+Keep tag pairs intact on one line if it's reasonable to do so
+
+ </para></listitem>
+ <listitem><para>
+
+The right margin will not be even, it doesn't matter
+
+ </para></listitem>
+ <listitem><para>
+
+Use 1-space indentation, but don't sweat it
+
+ </para></listitem>
+ <listitem><para>
+
+Try to leave a blank line between paragraph tags and the
+words in the paragraph (this makes word wrapping much easier)
+
+ </para></listitem>
+</orderedlist>
+</para>
+
+  <sect2 id="cross-referencable-id">
+  <title>Second Level Section</title>
+<para>
+
+I use the docbookide xemacs mode to edit:
+
+<informalexample>
+ <screen>
+
+  <userinput>apt-get install docbookide</userinput>
+  or <command>apt-get install docbookide</command>
+
+ </screen>
+</informalexample>
+
+It displays syntax coloring and closes your tags if you
+are at the end of a line. Here is an internal cross reference: 
+<xref linkend="cross-referencable-id"></xref>
+and here is an external link to 
+<ulink url="http://www.debian.org">the main Debian website</ulink>. 
+Many times we will put common urls in an entity document and use
+something like a link to 
+<ulink url="&debianwebsite;">Debian Website</ulink> 
+instead of using url directly.
+
+</para><para>
+
+If you need to specify text that is only present for a certain
+condition or a given architecture, use attributes arch and 
+condition. For example, 
+
+<code>
+
+<para arch="x86">
+A paragraph only interesting for i386 users
+</para>
+
+<sect3 condition="bootable-from-hard-disk">
+A section pertaining only to computers which
+can boot from their hard disk
+</sect3>
+
+<phrase arch="powerpc">PowerPC-only text within a para</phrase>
+
+</code>
+
+</para>
+<!-- More example tags, all these must occur within a block: -->
+<para>
+
+<prompt>the command prompt text</prompt>
+<replaceable>text to be replaced by user, debiandoc var</replaceable>
+<computeroutput>that's self explanatory!</computeroutput>
+<application>abiword</application>
+<filename>/install/basedebs.tar</filename>
+<medialabel>/dev/hda1</medialabel>
+
+You can exit from GNU Emacs with 
+
+<menuchoice>
+  <shortcut>
+
+    <keycombo><keysym>C-x</keysym><keysym>C-c</keysym></keycombo>
+
+  </shortcut>
+
+  <guimenu>Files</guimenu>
+  <guimenuitem>Exit Emacs</guimenuitem>
+
+</menuchoice>.
+
+<keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>Alt</keycap>
+ <keycap>F1</keycap>
+</keycombo> selects console 1.
+
+</para>
+
+<!-- This is what used to be a taglist in debiandoc -->
+<variablelist>
+ <varlistentry>
+
+  <term>1st term to be defined</term>
+  <listitem><para>
+
+  A paragraph definition of the term.
+
+  </para></listitem>
+
+ </varlistentry>
+ <varlistentry>
+
+  <term>2nd term to be defined</term>
+
+  <listitem><para>
+
+  A paragraph definition of the 2nd term.
+
+  </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<!-- Admonitions must have paragraph level tags within them -->
+
+<tip><para>making things easier on yourself</para></tip>
+<note><para>something of interest</para></note>
+<important><para>pay attention now</para></important>
+<caution><para>watch out here</para></caution>
+<warning><para>this is really critical to success</para></warning>
+
+<informaltable>
+ <tgroup cols="2"><tbody><row>
+
+  <entry>1st row, 1st column</entry>
+  <entry>1st row, 2nd column</entry>
+
+ </row><row>
+
+  <entry>2nd row, 1st column</entry>
+  <entry>2nd row, 2nd column</entry>
+
+ </row></tbody></tgroup>
+</informaltable>
+
+<table><title>A Formal Table has a Title</title>
+ <tgroup cols="2"><tbody><row>
+
+  <entry>1st row, 1st column</entry>
+  <entry>1st row, 2nd column</entry>
+
+ </row><row>
+
+  <entry>2nd row, 1st column</entry>
+  <entry>2nd row, 2nd column</entry>
+
+ </row></tbody></tgroup>
+</table>
+
+<screenshot>
+ <graphic fileref="some-graphic-reference.jpg"></graphic>
+</screenshot>
+
+<informalfigure>
+ <graphic fileref="some-figure-reference.png"></graphic>
+</informalfigure>
+
+<figure>
+ <title>A Formal Figure has a Title (Caption)</title>
+ <graphic fileref="some-figure-reference.jpg"></graphic>
+</figure>
+
+  </sect2>
+ </sect1>
+</chapter>
+
+<glossary>
+ <glossentry>
+
+ <glossterm>some glossary entry</glossterm>
+ <glossdef><para>
+
+Some appropriate glossary definition goes here.
+
+  </para> </glossdef>
+ </glossentry>
+</glossary>
+
+</book>
+
+
+
+
+
diff --git a/doc/translations.txt b/doc/translations.txt
new file mode 100644
index 000000000..f6d32e862
--- /dev/null
+++ b/doc/translations.txt
@@ -0,0 +1,298 @@
+Debian Installation Manual - notes for translation
+--------------------------------------------------
+
+Note: if you happen to modify this file, please don't forget to
+      update the trailing changelog
+
+Where is the manual kept?
+=========================
+
+The manual is kept in a Subversion repository on svn.debian.org
+as part of the Debian Installer (d-i) project.
+
+The manual and its translations can be found in ./manual.
+
+How to join the translation effort for an existing translation
+==============================================================
+
+Try to find out who is working on the translation and contact them.
+Alternatively you can send a mail to the mailing list for your language
+(debian-l10n-<language>@lists.debian.org), if one exists or to the mailing
+list for the debian installer project: debian-boot@lists.debian.org.
+
+You should also coordinate with current translators on which parts to
+translate and how to submit your translations.
+
+How to start a new translation
+==============================
+
+Starting a translation for a new language without write access to the d-i SVN
+repository really is not practical. See the section on getting SVN access below;
+you will also have to get a local working copy of the manual as described there.
+
+  1. Create a new directory structure for your translation
+  --------------------------------------------------------
+  Use the following commands to create a copy of the English documents as a
+  base for your translation. This also ensures that your translation will be
+  complete and can be build. A text that has not be translated yet, will be
+  included in English.
+  - change directory to: ./manual/
+  - cp -R en/ <lang>
+    (where <lang> is the ISO code for your language: xx or xx_XX)
+  - find <lang> -name .svn | xargs rm -Rf
+    (this removes all .svn subdirectories)
+
+  2. Convert revision comments
+  ----------------------------
+  This enables you to track changes is the original English documents.
+  see 'Keeping your translation up to date' below for an explanation.
+  - change directory to: ./manual/
+  - ./scripts/rev-update <lang>
+
+  3. Commit the changes to SVN
+  ----------------------------
+  - change directory to: ./manual/
+  - svn add <lang>
+  - svn ci -m "Manual: creating new translation for <lang>"
+
+One more change is needed to get your translation build automatically:
+<lang> needs to be added to the 'languages' variable in build/build.sh.
+However, this is only usefull after you have translated your first couple
+of chapters. Please send a request to the debian-boot mail list for your
+language to be added.
+
+Encoding
+========
+
+The default encoding for all .xml files is UTF-8. If you want to keep your
+translation in UTF-8 encoding, you should use an editor that supports UTF-8
+and make sure that UTF-8 encoding is selected when you open a .xml document.
+
+If it is easier for you to work using another encoding, you will have to
+specify which encoding you use in the first line of each translated document.
+For example, to use ISO-8859-1 encoding (for most Western European languages),
+add the following line at the top of each .xml file:
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+The use of HTML codes (like &egrave;) is possible but not advised.
+
+Note: If you do not specify the correct encoding, your translation will fail
+      to build.
+Note: You should _not_ change the encoding of the following documents:
+      - administrativa/contributors.xml
+
+Translation order
+=================
+
+Suggested translation order:
+- ./preface.xml, ./bookinfo.xml
+- ./welcome/*.xml
+- ./using-d-i/*.xml
+- ./using-d-i/modules/*.xml
+- ./boot-new/*.xml
+- ./boot-new/modules/*.xml
+
+Note that currently (may 10, 2004) it look like there will be a fairly major
+reorganization of parts of the manual in the next month(s).
+
+Keeping your translation up to date
+===================================
+
+There are two perl scripts to help you keep track of changes in the original
+English text of the manual. These scripts make use of special revision
+comments that should be included in each file.
+
+An original English file contains something like:
+  <!-- retain these comments for translator revision tracking -->
+  <!-- $Id: preface.xml 12756 2004-04-06 22:23:56Z some-user $ -->
+
+The second line is important. It contains the filename, the revision number,
+the date and time the last revision was committed, the user that committed
+the last revision. The string '$Id:' is necessary for SVN to automatically
+update this line each time the file is committed.
+
+A document in a directory containing a translation should contain either:
+  <!-- original version: 12756 -->
+or
+  <!-- original version: 12756 untranslated -->
+
+When you translate a document, you should of course remove the word
+'untranslated' from this comment.
+
+The scripts will do several things:
+- show which translated files have a different revision number from the
+  original English files
+- show what changes have been made in the original English file
+- help you update revision comments
+- help you keep track of which files have not yet been translated
+You can find both scripts in the root directory for the manual. Both
+scripts should be run from this directory.
+
+The procedure below can be used for relatively simple changes. If there
+have been major reorganizations in the English documents, you may have to
+do additional checks to find out exactly what changes have been made.
+Use 'svn st -u' before you start this procedure to check the status of
+your working copy.
+
+  1. Update your local working copy from SVN
+  ------------------------------------------
+  - change directory to: ./manual/
+  - svn up
+
+  2. Copy new files (if any)
+  --------------------------
+  If there are any new files (marked 'A' in the output from 'svn up'),
+  copy them to the directory for your translation and then:
+  - ./scripts/rev-update <lang>
+  This will change the revision comment in the copied file to:
+  <!-- original version: ##### untranslated -->
+  You will also have to run 'svn add' for the new documents.
+
+  3. Check for other changes
+  --------------------------
+  - ./scripts/doc-check <lang>
+  If changes are listed for documents that are marked 'untranslated', you
+  can copy the new English version to the directory for your translation
+  by running:
+  - ./scripts/cp-untrans <lang>
+  (this script also runs rev-update automatically).
+  If changes are listed for documents that are not marked 'untranslated',
+  you can create a diff to find out what the changes are by running:
+  - ./scripts/doc-check -d <lang>
+  
+  4. Update your translations
+  ---------------------------
+  Edit your translations to reflect the changes in the English documents.
+  !! Don't forget to also update the revision number in the revision comment
+     after you updated a translation. The revision number should be the same
+     as the revision number in the new version of the English document.
+  You should run './scripts/doc-check <lang>' again after you finish all updates
+  and before you commit your changes to SVN; there should be no output.
+  
+  Other uses of the scripts
+  -------------------------
+  - doc-check -s <lang>: show which documents are marked untranslated
+  - rev-update -u <lang>: automatically update revision numbers in the directory
+    containing your translation to the revision numbers in the original English
+    documents (use only after you have made sure there are no changes in content)
+
+How to remain consistent with the installer
+===========================================
+
+It is important that your translation of the manual remains consistent with
+the translation of Debian Installer and packages for your languages.
+
+Probably the best way to do this, is to run the installer in 'expert' mode,
+both in English and your own language.
+
+As strings and their translations in the installer may change, you may have
+to perform an installation once in a while to check if there have been
+important changes (the main burden to check for changes in strings falls on
+the maintainers of the English original, but is you spot inconsistencies,
+please report them to the debian-boot list).
+
+You can also use the xx(_XX).po files for packages (including d-i) to see
+how strings have been translated. For more information on these files,
+please refer to the translations.txt file in the parent directory of the
+directory where this file is.
+
+You can also try contacting the translator for a package or the maillist
+for your language (debian-l10n-<language>@lists.debian.org) to try to clear
+questions about translations.
+
+How to test your work
+=====================
+
+When you have finished your translation, always re-read your file at
+least once to correct all meaning-, spelling-, grammar-, typo-, etc-
+mistakes.
+
+You can also try to build the manual (create HTML pages) for a specific
+architecture for your language.
+See ./build/README for more information on building the manual.
+
+How to get write access to the SVN repository
+=============================================
+
+  1) Installing subversion
+  ------------------------
+
+  You need to install subversion on your system. Just do
+     apt-get install subversion
+  
+  2) Getting write access to the subversion repository
+  ----------------------------------------------------
+
+  If you are not a Debian Developer, you first need to create a guest account
+  on http://alioth.debian.org/, than ask on debian-boot@lists.debian.org
+  for somebody to add your guest account to the debian-installer project.
+ 
+  3) Using subversion to get files
+  --------------------------------
+
+  Once your account is allowed to write to the project, you can retrieve the
+  full project using this:
+    svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk
+  If you only want to work on the manual, you can retrieve the relevant part
+  of the repository using:
+    svn co svn+ssh://<username>@svn.debian.org/svn/d-i/trunk/manual
+
+  4) Commit your changed translation files to SVN
+  -----------------------------------------------
+
+  After you have finished editing your translation, use
+    svn commit -m "Your comment about this commit"
+  to commit your changes to the SVN repository.
+
+  Note: it's possible, to do an anonymous checkout from the svn
+        (use svn co svn://svn.debian.org/d-i/trunk/manual).
+        However, from this local copy you aren't able to commit, it's readonly.
+        Use the commands listed under 3), if you plan to do commits in the future.
+
+
+You can find a good manual for SVN at http://svnbook.red-bean.com/.
+
+How to get help
+===============
+
+If you need further assistance, feel free to ask for help on
+debian-boot (for debian-installer related stuff) or debian-i18n (for
+l10n related questions) Debian mailing lists.
+
+--------------------------------------------------------------------------
+
+This guide is supposed to be be a first start for translators.  There
+are probably errors.  Please fix it if you find errors.
+
+--------------------------------------------------------------------------
+Changelog:
+
+2006-07-14 Frans Pop
+ - Correct and update information on subversion checkout
+
+2005-10-07 Frans Pop
+ - Location of manual changed in the d-i SVN repository
+
+2005-02-12 Frans Pop
+ - Minor corrections
+
+2004-12-27 Frans Pop
+ - Updated svn checkout info to refer to new server (costa)
+
+2004/10/26 Holger Wansing
+ - Added a chapter about how to commit + fixed the Link to the svnbook
+
+2004/09/27 Frans Pop
+ - Update in line with changes in SVN (moved files/directories)
+
+2004/09/04 Guillem Jover
+ - Refer to Adam Conrad's subversion backport instead
+
+2004/06/04 Frans Pop
+ - Added paragraph on updating translations
+
+2004/05/10 Frans Pop
+ - file creation
+
+2005/07/28 Cristian Rigamonti
+ - Added cp-untrans, fixed svn command and some typos
diff --git a/doc/translations_po.txt b/doc/translations_po.txt
new file mode 100644
index 000000000..543cc3a45
--- /dev/null
+++ b/doc/translations_po.txt
@@ -0,0 +1,188 @@
+Debian Installation Manual - notes for translation
+--------------------------------------------------
+
+This file explains how to translate the manual using .po files.
+This is now officially supported.
+
+!!! For general information on translating the manual, please see the
+!!! translations.txt file.
+
+Note: if you happen to modify this file, please don't forget to
+      update the trailing changelog
+
+Background information
+======================
+There are currently two toolsets that support translating XML files using .po
+files: KDE's poxml and po4a. We have chosen poxml as that gives better context
+(it does not split paragraphs) for translation.
+The downside of the poxml tools is that they require the .xml files to be
+"proper" XML. Because some of the individual files in the English
+original are not proper XML, we've had to "integrate" the files per chapter.
+
+This means that instead of translating about 160 small files, you will be
+translating about 15 large files.
+
+Current limitations
+===================
+Building from PO files is currently not supported in the Sarge branch of d-i's
+SVN repository. This is however not a real problem as the XML files created
+from the PO files are used to synchronise the Sarge branch from trunk.
+Therefore translators should not worry about this.
+
+Requirements
+============
+The following packages need to be installed on your system:
+- gettext
+- poxml
+- gawk
+
+If you also want to be able to build the manual, you also need to install the
+build dependencies listed in build/README.
+
+Available tools
+===============
+You will not be using poxml itself, but rather some scripts that call the
+poxml tools.
+
+- ./scripts/merge_xml  : merges the small .xml files into larger files
+- ./scripts/update_pot : creates (new) .pot templates based on integrated
+                         English .xml files
+- ./scripts/revert_pot : used to revert changes in POT files to avoid
+                         accidental commits
+- ./scripts/update_po  : updates your .po files when there are changes in the
+                         English text (the .pot templates)
+- ./scripts/create_xml : creates translated .xml files from the merged English
+                         .xml files and the translated .po files
+- ./scripts/create_po  : used to convert an existing .xml translation to
+                         using .po files
+- ./scripts/set_untranslated : used for the conversion of existing translations
+
+All scripts should be run from the ./manual directory and take the language as
+parameter.
+
+
+Starting a new translation
+==========================
+This procedure should only be used if there is no existing translation using
+XML files for your language! See the section on conversion below if you want
+to switch from translating XML files to using PO files.
+
+The template files for the manual are available in ./po/pot, so all you need
+to do is create a new directory for your language (using the official ISO
+code for your language) and copy the .pot file you want to translate to a
+.po file in that directory.
+
+Example for a Dutch translation:
+  - mkdir ./po/nl
+  - cp ./po/pot/bookinfo.pot ./po/nl/bookinfo.po
+  - <po editor> ./po/nl/bookinfo.po
+
+Use your favorite PO file editor (like kbabel) to translate the .po file.
+You don't need to copy all POT files straight away, just copy each one as you
+start translating them.
+
+  
+Committing your translation
+===========================
+The translation can be committed to d-i's SVN repository using:
+  1. svn ci ./po/<your language> -m "<some comment describing the changes>"
+
+If this is the first time you commit the translation of a file, you will need
+to run the 'svn add' command on the new files before you do 'svn ci'.
+Tip: use the commands 'svn st ' and 'svn diff' before you commit your changes
+to check what you are committing before you run the 'svn ci' command.
+
+
+Updating your translation
+=========================
+The PO files for your language and the templates for the manual are updated
+regularly when there are changes in the original English XML files.
+This is done during the "daily" builds (currently done by Frans Pop); you
+should not have to update your PO files yourself.
+Changed strings will be marked 'fuzzy' and new strings will be untranslated.
+
+After this your PO files in the ./po directory should be updated and you can
+update the translation with your favorite PO file editor. To commit the
+changes, follow again the procedure described in the previous section.
+
+To update the POT and PO files manually, use the following commands:
+  1. svn up
+  2. ./scripts/merge_xml en
+  3. ./scripts/update_pot
+  4. ./scripts/update_po <your language>
+
+NOTE
+Doing this manually may result in SVN conflicts when you next 'svn up' with
+the repository. The preferred method is to just wait until your PO files are
+updated for you.
+
+
+Building the manual yourself
+============================
+If you want to build a HTML version (or other format) of the manual yourself,
+you will have to generate the XML for your language before you can run the
+buildone.sh script. This can be useful, for example to debug build errors.
+
+Use the following commands:
+  1. ./scripts/merge_xml en
+  2. ./scripts/update_pot
+  3. ./scripts/update_po <your language>
+  4. ./scripts/revert_pot
+  5. ./scripts/create_xml <your language>
+
+Steps 2 and 3 are necessary because the English XML files may have been
+updated since the last daily build of the manual, so the POT files and your
+PO files may be out-of-date. Step 4 makes sure you do not accidentally
+update the POT files in the repository. They are not needed to create the
+XML files or build the manual.
+
+After that you can run the buildone.sh script as documented in the README in
+the ./build directory. If you run buildone.sh without first generating the
+XML files, you will either get an error message "unknown language" or build
+from an outdated version of the XML files.
+
+
+Converting an existing translation from .xml files to .po files
+===============================================================
+It is possible to convert an existing translation of the manual (where the
+individual XML files have been translated) to using PO files.
+There are two important conditions:
+- the translation must be up-to-date with the English XML files;
+- the translation must have same structure as the English XML files (i.e.
+  the translation must have the same chapters, sections, paragraphs, tables,
+  examples, etc; you can have no 'extra' paragraphs in your translation).
+
+The first condition does not mean that everything needs to be translated!
+
+The conversion is fairly difficult and some checks need to be done after some
+of the steps. Full instructions for converting a translation can be found at:
+http://lists.debian.org/debian-boot/2007/07/msg00814.html.
+
+Note that conversions are only done rarely and that the script used may
+need updating.
+
+--------------------------------------------------------------------------
+
+If you find any errors in this file, please fix them.
+
+--------------------------------------------------------------------------
+Changelog:
+
+2007-07-31 Frans Pop
+ - Add link to full conversion instructions
+
+2005-04-19 Frans Pop
+ - Finally rewrite this file following official implementation of PO file
+   translation over a month ago...
+ - Reflect the changed file structure in the ./po directory
+
+2005-02-15 Frans Pop
+ - Corrected the location where generated XML files are written
+
+2005-02-14 Frans Pop
+ - Corrected an error in the name of one script
+ - Clarified the difference between starting a new translation and
+   converting an existing one
+
+2005-02-12 Frans Pop
+ - First version