X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=6ffa1bac9fcb450ea0d876a5b7e52cc1d1e00199;hb=a2c790cb659d425284a524ce8dfd748dbc84f511;hp=ae6336c92be814292b14b094741f4bd47814c883;hpb=e62d004aa8eb5eeb1baa74b7813f73d2d09eae49;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index ae6336c..6ffa1ba 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.140 $">
+  <!entity cvs-rev "$Revision: 1.144 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -39,11 +39,11 @@
 
       <copyright>
 	<copyrightsummary>
-copyright &copy;1998&mdash;2002 Adam Di Carlo</copyrightsummary>
+copyright &copy; 1998&mdash;2002 Adam Di Carlo</copyrightsummary>
 	<copyrightsummary>
-copyright &copy;2002 Raphaël Hertzog</copyrightsummary>
+copyright &copy; 2002 Raphaël Hertzog</copyrightsummary>
 	<copyrightsummary>
-copyright &copy;1997, 1998 Christian Schwarz</copyrightsummary>
+copyright &copy; 1997, 1998 Christian Schwarz</copyrightsummary>
 	<p>
 This manual is free software; you may redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the
@@ -397,7 +397,7 @@ the following steps:
 	    <item>
 Orphan all your packages, as described in <ref id="orphaning">.
 	    <item>
-Send an email about how you are leaving the project to
+Send an email about why you are leaving the project to
 &email-debian-private;.
 	    <item>
 Notify the Debian key ring maintainers that you are leaving by
@@ -1179,7 +1179,7 @@ recompiled on most of the architectures.
 The Package Tracking System (PTS) is basically a tool to track by mail
 the activity of a source package. You just have to subscribe
 to a source package to start getting the mails related to it. 
-You get the same mails than the maintainer. Each mail
+You get the same mails as the maintainer. Each mail
 sent through the PTS is classified and associated to one of
 the keyword listed below. This will let you select the mails that
 you want to receive.
@@ -2902,15 +2902,6 @@ anything to do with an upload of yours, do it simply by emailing an
 explanation to <email>XXX-done@bugs.debian.org</email>.
 
 
-      <sect1 id="lintian-reports">Lintian reports
-	<p>
-You should periodically get the new <package>lintian</package> from
-`unstable' and check over all your packages.  Alternatively you can
-check for your maintainer email address at the <url id="&url-lintian;"
-name="online lintian report">.  That report, which is updated
-automatically, contains <prgn>lintian</prgn> reports against the
-latest version of the distribution (usually from 'unstable') using the
-latest <package>lintian</package>.
 
 
   <chapt id="best-pkging-practices">
@@ -2933,7 +2924,7 @@ even better.
 	<p>
 To help you in your packaging effort, you can use helper scripts.
 The best scripts available are provided by <package>debhelper</package>.
-With <prgn>dh_make</prgn> (package <package>dh-make</package>), you can
+With <prgn>dh_make</prgn> (see <ref id="dh-make">), you can
 generate in a few seconds a package that is mostly ready. However that
 apparent simplicity is hiding many things done by the helper scripts.
 You have to know what is done by them, that's why you are strongly
@@ -3000,36 +2991,34 @@ hand crafted rules file.
 
 	<sect1 id="handling-debconf-translations">Handling debconf translations
 	<p>
-Like porters, translators have a difficult task.  Since they work on many
-packages, they cannot keep track of every change in packages in order to
-be informed when a translated string is outdated.  Fortunately
-<package>debconf</package> can automatically report outdated translations,
-if package maintainers follow some basic guidelines described below.
-	<p>
-Translators can use <prgn>debconf-getlang</prgn> (package
-<package>debconf-utils</package>) to write a <file>templates.xx</file>
-file containing both English and localized fields (where <em>xx</em> is
-the language code, may be followed by a country code).  This file can be
-put into the <file>debian</file> subdirectory without any change.
-	<p>
-When building a binary package, <file>debian/templates.xx</file> files are
-merged along with <file>debian/templates</file> to generate the
-<file>templates</file> file contained in the binary package.  This is
-automatically done by <prgn>dh_installdebconf</prgn> (package
-<package>debhelper</package>). If you do not use debhelper, you can
-do the same with <prgn>debconf-mergetemplate</prgn>
-(package <package>debconf-utils</package>). 
-	<p>
-When the package maintainer needs to update the templates file, they only
-change <file>debian/templates</file>.  When English strings in this file
-and in <file>debian/templates.xx</file> differ, translators do know that
-their translation is outdated.
-	<p>
-Please see the page about
-<url id="&url-debconf-l10n-help;" name="localizing debconf templates files">
-at the Debian web site, it contains more detailed instructions, including a
-full example.
-
+Like porters, translators have a difficult task.  They work on many
+packages and must collaborate with many different
+maintainers. Moreover, most of the time, they are not native English
+speaker, so you may need to be particularly patient with them.
+	<p>
+The goal of <package>debconf</package> was to make packages
+configuration easier for maintainers and for users.  Originally,
+translation of debconf templates was handled with
+<prgn>debconf-mergetemplate</prgn> from the
+<package>debconf-utils</package> package.  Since
+<package>debconf</package> version 1.2.9,
+<prgn>debconf-mergetemplate</prgn> has been deprecated and a new
+system called <package>po-debconf</package> is strongly
+encouraged. This new method is much easier both for the maintainer and
+the translators, and you should upgrade your packages to use it.
+Transition scripts are provided.
+	<p>
+Using <package>po-debconf</package>, the translation is stored in
+<file>po</file> files (drawing from <prgn>gettext</prgn> translation
+techniques).  Special template files contain the original messages and
+mark which fields should be translated. When you change the original,
+calling the <prgn>debconf-updatepo</prgn> script with no argument is
+enough to mark the translation as needing attention from the
+translators. Then, at build time, use the
+<prgn>dh_installdebconf</prgn> program take care of all the needed
+magic to add the template along with the up-to-date translations into
+the binary packages.  Refer to the <manref name="po-debconf"
+section="7"> manual page for details.
 
     <sect id="specific-practices">
 	<heading>Specific packaging practices</heading>
@@ -3218,7 +3207,7 @@ list.
 Even though there is a dedicated group of people for Quality
 Assurance, QA duties are not reserved solely for them. You can
 participate in this effort by keeping your packages as bug-free as
-possible, and as lintian-clean (see <ref id="lintian-reports">) as
+possible, and as lintian-clean (see <ref id="lintian">) as
 possible. If you do not find that possible, then you should consider
 orphaning some of your packages (see <ref
 id="orphaning">). Alternatively, you may ask the help of other people
@@ -3411,9 +3400,20 @@ they are required for any Debian maintainer.
 	<p>
 <package>Lintian</package> dissects Debian packages and reports bugs
 and policy violations. It contains automated checks for many aspects
-of Debian policy as well as some checks for common errors.  The use of
-<package>lintian</package> has already been discussed in <ref
-id="upload-checking"> and <ref id="lintian-reports">.
+of Debian policy as well as some checks for common errors.
+	<p>
+You should periodically get the newest <package>lintian</package> from
+`unstable' and check over all your packages. Notice that the <tt>-i</tt>
+option provides detailed explanations of what each error or warning means,
+what is its basis in Policy, and commonly how you can fix the problem.
+	<p>
+Refer to <ref id="upload-checking"> for more information on how and when
+to use Lintian.
+	<p>
+You can also see a summary of all problems reported by Lintian on your
+packages at <url id="&url-lintian;">. Those reports contain the latest
+<prgn>lintian</prgn> output on the whole development distribution
+("unstable").
 
 
       <sect id="debconf">
@@ -3471,6 +3471,21 @@ favor of <package>debhelper</package>.  However, it's not a bug to use
 <package>debmake</package>.
 
 
+      <sect id="dh-make">
+	<heading><package>dh-make</package>
+	<p>
+The <package/dh-make/ package contains <prgn/dh_make/, a program that
+creates a skeleton of files necessary to build a Debian package out of
+a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of
+<package/debmake/ and its template files use dh_* programs from
+<package/debhelper/.
+	<p>
+While the rules files generated by <prgn/dh_make/ are in general a
+sufficient basis for a working package, they are still just the groundwork:
+the burden still lies on the maintainer to finely tune the generated files
+and make the package entirely functional and Policy-compliant.
+
+
       <sect id="yada">
 	<heading><package>yada</package>
 	<p>