Update docs (things have changed in the meantime)

4 files changed, 113 insertions, 96 deletions

diff --git a/doc/building.txt b/doc/building.txt
index 9aaa6c18b..76f949166 100644
--- a/doc/building.txt
+++ b/doc/building.txt
@@ -13,14 +13,13 @@ The currently supported document types are:
 ================
 
 The build dependencies depend on which document types you wish to generate:
-all     : dpkg-dev, docbook, docbook-xml, docbook-xsl, xsltproc, poxml
+all     : docbook, docbook-xml, docbook-xsl, xsltproc, poxml
 html    : (no additional packages required)
-pdf     : docbook-dsssl, ghostscript, dblatex
+pdf     : docbook-dsssl, ghostscript, dblatex, texlive-lang-*
 txt     : w3m
 
-For some languages additional packages are needed to build pdf:
-ko      : fonts-wqy-microhei
-ru      : cm-super (type1 fonts)
+For some languages additional font packages are needed to build pdf:
+ko      : fonts-nanum-coding
 zh      : fonts-wqy-microhei
 ja      : fonts-vlgothic
 
diff --git a/doc/cheatsheet.xml b/doc/cheatsheet.xml
index 0f7eee0da..768e8b54f 100644
--- a/doc/cheatsheet.xml
+++ b/doc/cheatsheet.xml
@@ -17,7 +17,7 @@
  <title>First Level Section</title>
 <para>
 
-A paragraph explaining something In this manual we will make extensive
+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
diff --git a/doc/translations.txt b/doc/translations.txt
index 4ea383b1a..39fdb92a6 100644
--- a/doc/translations.txt
+++ b/doc/translations.txt
@@ -2,7 +2,8 @@ Debian Installation Guide - notes for translation
 --------------------------------------------------
 
 !!! Please note, that this file mostly documents xml-based
-!!! translations. This is, however, no longer supported.
+!!! translations. This is, however, no longer supported and therefore this
+!!! file is partly of-out-date.
 !!! Thus, some of the scripts mentioned below no longer work as expected!
 !!! You can now translate this manual via po files.
 !!! This is documented in the file translations_po.txt in this directory.
@@ -11,19 +12,63 @@ Debian Installation Guide - 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 git repository on salsa.debian.org
-as part of the Debian Installer (d-i) project.
+as part of the Debian Installer (d-i) project (under
+https://salsa.debian.org/installer-team/installation-guide).
 
-The manual and its translations can be found in ./installation-guide.
+The translations can be found in ./po.
 
 Use
 'git clone git@salsa.debian.org:installer-team/installation-guide.git'
 to checkout the sources with git.
 
 
+How to get write access to the git repository
+=============================================
+
+  1) Installing git
+  ------------------------
+
+  You need to install subversion on your system. Just do
+     apt install git
+  
+  2) Getting write access to the git repository
+  ----------------------------------------------------
+
+  If you are not a Debian Developer, you first need to create a guest account
+  on https://salsa.debian.org/, than ask on debian-boot@lists.debian.org
+  for somebody to add your guest account to the debian-installer project.
+ 
+  3) Using git to get files
+  --------------------------------
+
+  Once your account is allowed to write to the project, you can retrieve the
+  installation-guide using this:
+    git clone git@salsa.debian.org:installer-team/installation-guide.git
+
+  4) Commit your changed translation files to git
+  -----------------------------------------------
+
+  After you have finished editing your translation, use
+    git add path-to-file(s)
+    git commit -m "Your comment about this commit"
+    git push
+  to commit your changes to the git repository.
+
+
+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.
+
+
+
 How to join the translation effort for an existing translation
 ==============================================================
 
@@ -224,45 +269,6 @@ 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 git repository
-=============================================
-
-  1) Installing git
-  ------------------------
-
-  You need to install subversion on your system. Just do
-     apt install git
-  
-  2) Getting write access to the git repository
-  ----------------------------------------------------
-
-  If you are not a Debian Developer, you first need to create a guest account
-  on https://salsa.debian.org/, than ask on debian-boot@lists.debian.org
-  for somebody to add your guest account to the debian-installer project.
- 
-  3) Using git to get files
-  --------------------------------
-
-  Once your account is allowed to write to the project, you can retrieve the
-  installation-guide using this:
-    git clone git@salsa.debian.org:installer-team/installation-guide.git
-
-  4) Commit your changed translation files to git
-  -----------------------------------------------
-
-  After you have finished editing your translation, use
-    git add path-to-file(s)
-    git commit -m "Your comment about this commit"
-    git push
-  to commit your changes to the git repository.
-
-
-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.
 
 --------------------------------------------------------------------------
 
diff --git a/doc/translations_po.txt b/doc/translations_po.txt
index b6de69bbf..25a8e4a0e 100644
--- a/doc/translations_po.txt
+++ b/doc/translations_po.txt
@@ -10,49 +10,6 @@ This is now officially supported and the recommended way.
 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 16 large files.
-
-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 ./installation-guide directory and take the language as
-parameter.
-
 
 Starting a new translation
 ==========================
@@ -70,7 +27,7 @@ Example for a Dutch translation:
   - 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.
+Use your favorite PO file editor (like lokalize or poedit) 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.
 
@@ -82,12 +39,12 @@ The translation can be committed to d-i's git repository using:
   2. git commit -m "<some comment describing the changes>"
   2. git push
 
-Tip: use the command 'git diff -u' before you commit your changes (step 2),
+Tip: use the command 'git diff' before the git add command (step 1),
 to check what you are committing.
 
 
-Updating your translation
-=========================
+Updating your translation from the english original
+===================================================
 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 the i18n
@@ -144,12 +101,63 @@ out of your po files.
 However, the update_pot and update_pot functions from above's step 1-3 are
 performed in a temporary directory, so buildone_ng.sh cannot be used to update
 your translation po files!
-For this, you need to still follow the chapter "Updating your translation".
+For this, you need to still follow the chapter "Updating your translation
+from the english original".
 The intention of buildone_ng.sh is just, to provide an easy method for
 translators, to build the manual for testing their translation.
 
+
+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 16 large files.
+
+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 ./installation-guide directory and take the language as
+parameter.
+
+
 Converting an existing translation from .xml files to .po files
 ===============================================================
+
+!!! This paragraph only exists for historical reasons. There is no need for
+!!! this operations anymore, since all translations have been converted into
+!!! po files in the meantime.
+
 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:
@@ -291,6 +299,10 @@ If you find any errors in this file, please fix them.
 --------------------------------------------------------------------------
 Changelog:
 
+2019-12-21 Holger Wansing
+ - Update content (there are no xml-based translations anymore, po-based is
+   the default).
+
 2018/06/03 Holger Wansing
            Samuel Thibault
  - Updating (most) content on git migration