prepare for upload

[developers-reference.git] / best-pkging-practices.dbk

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index ca9f149c9d8eed0733df213bd95913e1788a184c..4f47a696a2cabb836b65aec3552ef1f057f114bf 100644 (file)
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -567,9 +567,9 @@ inserting the title of each different bug.
 <para>
 Important news about changes in a package can also be put in
 <filename>NEWS.Debian</filename> files.
-The news will be displayed by tools like apt-listchanges, before all the rest
+The news will be displayed by tools like <systemitem role="package">apt-listchanges</systemitem>, before all the rest
 of the changelogs.  This is the preferred means to let the user know about
-significant changes in a package.  It is better than using debconf notes since
+significant changes in a package.  It is better than using <systemitem role="package">debconf</systemitem> notes since
 it is less annoying and the user can go back and refer to the
 <filename>NEWS.Debian</filename> file after the install.  And it's better than listing
 major changes in <filename>README.Debian</filename>, since the user can easily
@@ -1117,7 +1117,7 @@ description is in the Description: line of the template.
 </para>
 <para>
 The short description should be kept short (50 characters or so) so that it may
-be accomodated by most debconf interfaces.  Keeping it short also helps
+be accommodated by most debconf interfaces.  Keeping it short also helps
 translators, as usually translations tend to end up being longer than the
 original.
 </para>
@@ -1224,7 +1224,7 @@ strongly discouraged.
 The short description should be phrased in the form of a question which should
 be kept short and should generally end with a question mark.  Terse writing
 style is permitted and even encouraged if the question is rather long (remember
-that translations are often longer than original versions)
+that translations are often longer than original versions).
 </para>
 </listitem>
 <listitem>
@@ -1350,7 +1350,7 @@ translated.
 If the default value may vary depending on language/country (for instance the
 default value for a language choice), consider using the special _Default
 type documented in <citerefentry> <refentrytitle>po-debconf</refentrytitle>
-<manvolnum>7</manvolnum> </citerefentry>).
+<manvolnum>7</manvolnum> </citerefentry>.
 </para>
 </section>
 
@@ -1360,6 +1360,13 @@ type documented in <citerefentry> <refentrytitle>po-debconf</refentrytitle>
 
 <section id="bpp-i18n">
 <title>Internationalization</title>
+<para>
+This section contains global information for developers to make translators'
+life easier.  More information for translators and developers interrested
+in internationalization are available in the <ulink
+url="&url-i18n-l10n;">Internationalisation and localisation in Debian</ulink>
+documentation.
+</para>
 <section id="bpp-i18n-debconf">
 <title>Handling debconf translations</title>
 <para>
@@ -1421,6 +1428,14 @@ language-independent information and define those as entities in a separate
 file which is included by all the different translations.  This makes it much
 easier, for instance, to keep URLs up to date across multiple files.
 </para>
+<para>
+Some tools (e.g. <systemitem role="package">po4a</systemitem>, <systemitem
+role="package">poxml</systemitem>, or the <systemitem
+role="package">translate-toolkit</systemitem>) are specialized in extracting
+the translatable material from different formats.  They produce PO files, a
+format quite common to translators, which permits to see what needs to be
+retranslated when the translated document is updated.
+</para>
 </section>
 
 </section>