separate patches: the patch files are shipped within the Debian patch file
(<filename>.diff.gz</filename>), usually within the
<filename>debian/</filename> directory. The only difference is that they
-aren't applied immediately by dpkg-source, but by the <literal>build</literal>
-rule of <filename>debian/rules</filename>. Conversely, they are reverted in
-the <literal>clean</literal> rule.
+aren't applied immediately by dpkg-source,
+but by the <literal>build</literal>
+rule of <filename>debian/rules</filename>,
+through a dependency on the <literal>patch</literal> rule.
+Conversely, they are reverted in
+the <literal>clean</literal> rule,
+through a dependency on the <literal>unpatch</literal> rule.
</para>
<para>
-<command>dbs</command> is one of the more popular approaches to this. It does
-all of the above, and provides a facility for creating new and updating old
-patches. See the package <systemitem role="package">dbs</systemitem> for more
-information and <systemitem role="package">hello-dbs</systemitem> for an
-example.
+<command>quilt</command> is the recommended tool for this.
+It does all of the above, and also allows to manage patch series.
+See the
+<systemitem role="package">quilt</systemitem> package for more information.
</para>
<para>
-<command>dpatch</command> also provides these facilities, but it's intended to
-be even easier to use. See the package <systemitem
-role="package">dpatch</systemitem> for documentation and examples (in
-<filename>/usr/share/doc/dpatch</filename>).
+There are other tools to manage patches, like <command>dpatch</command>,
+and the patch system integrated with
+<systemitem role="package">cdbs</systemitem>.
</para>
</section>
<section id="bpp-pkg-synopsis">
<title>The package synopsis, or short description</title>
<para>
-The synopsis line (the short description) should be concise. It must not
-repeat the package's name (this is policy).
+Policy says the synopsis line (the short description) must be concise, not
+repeating the package name, but also informative.
</para>
<para>
-It's a good idea to think of the synopsis as an appositive clause, not a full
-sentence. An appositive clause is defined in WordNet as a grammatical relation
-between a word and a noun phrase that follows, e.g., Rudolph the red-nosed
-reindeer. The appositive clause here is red-nosed reindeer. Since the
-synopsis is a clause, rather than a full sentence, we recommend that it neither
-start with a capital nor end with a full stop (period). It should also not
-begin with an article, either definite (the) or indefinite (a or an).
-</para>
-<para>
-It might help to imagine that the synopsis is combined with the package name in
-the following way:
+The synopsis functions as a phrase describing the package, not a complete
+sentence, so sentential punctuation is inappropriate: it does not need extra
+capital letters or a final period (full stop). It should also omit any initial
+indefinite or definite article - "a", "an", or "the". Thus for instance:
</para>
<screen>
-<replaceable>package-name</replaceable> is a <replaceable>synopsis</replaceable>.
+Package: libeg0
+Description: exemplification support library
</screen>
<para>
-Alternatively, it might make sense to think of it as
+Technically this is a noun phrase minus articles, as opposed to a verb phrase.
+A good heuristic is that it should be possible to substitute the package name
+and synopsis into this formula:
</para>
-<screen>
-<replaceable>package-name</replaceable> is <replaceable>synopsis</replaceable>.
-</screen>
<para>
-or, if the package name itself is a plural (such as developers-tools)
+The package <replaceable>name</replaceable> provides {a,an,the,some}
+<replaceable>synopsis</replaceable>.
+</para>
+<para>
+Sets of related packages may use an alternative scheme that divides the
+synopsis into two parts, the first a description of the whole suite and the
+second a summary of the package's role within it:
</para>
<screen>
-<replaceable>package-name</replaceable> are <replaceable>synopsis</replaceable>.
+Package: eg-tools
+Description: simple exemplification system (utilities)
+
+Package: eg-doc
+Description: simple exemplification system - documentation
</screen>
<para>
-This way of forming a sentence from the package name and synopsis should be
-considered as a heuristic and not a strict rule. There are some cases where it
-doesn't make sense to try to form a sentence.
+These synopses follow a modified formula. Where a package
+"<replaceable>name</replaceable>" has a synopsis
+"<replaceable>suite</replaceable> (<replaceable>role</replaceable>)" or
+"<replaceable>suite</replaceable> - <replaceable>role</replaceable>", the
+elements should be phrased so that they fit into the formula:
+</para>
+<para>
+The package <replaceable>name</replaceable> provides {a,an,the}
+<replaceable>role</replaceable> for the <replaceable>suite</replaceable>.
</para>
</section>
</para>
<para>
Avoid changing templates too often. Changing templates text induces more work
-to translators which will get their translation fuzzied. If you plan changes
-to your original templates, please contact translators. Most active
+to translators which will get their translation fuzzied. A fuzzy translation is
+a string for which the original changed since it was translated, therefore
+requiring some update by a translator to be usable. When changes are small
+enough, the original translation is kept in PO files but marked as
+<literal>fuzzy</literal>.
+</para>
+<para>
+If you plan to do changes
+to your original templates, please use the notification system provided with
+the <systemitem
+role="package">po-debconf</systemitem> package, namely the <command>
+podebconf-report-po</command>, to contact translators. Most active
translators are very responsive and getting their work included along with your
modified templates will save you additional uploads. If you use gettext-based
-templates, the translator's name and e-mail addresses are mentioned in the po
-files headers.
+templates, the translator's name and e-mail addresses are mentioned in the PO
+files headers and will be used by <command>
+podebconf-report-po</command>.
</para>
<para>
-The use of the <command>podebconf-report-po</command> from the <systemitem
-role="package">po-debconf</systemitem> package is highly recommended to warn
-translators which have incomplete translations and request them for updates.
+A recommended use of that utility is:
+</para>
+<programlisting>cd debian/po && podebconf-report-po --languageteam --withtranslators --call --deadline="+10 days"</programlisting>
+<para>
+This command will first synchronize the PO and POT files in debian/po with
+the templates files listed in <filename>debian/po/POTFILES.in</filename>.
+Then, it will send a call for translation updates to the language team
+(mentioned in the <literal>Language-Team</literal> field of each PO file)
+as well as the last translator (mentioned in
+<literal>Last-translator</literal>). Finally, it will also send a call for
+new translations, in the &email-debian-i18n; mailing list.
+</para>
+<para>
+Giving a deadline to translators is always appreciated, so that they can
+organize their work. Please remember that some translation teams have a
+formalized translate/review process and a delay lower than 10 days is
+considered as unreasonable. A shorter delay puts too much pressure on translation
+teams and should be kept for very minor changes.
</para>
<para>
If in doubt, you may also contact the translation team for a given language
(debian-l10n-xxxxx@&lists-host;), or the
&email-debian-i18n; mailing list.
</para>
-<para>
-Calls for translations posted to &email-debian-i18n; with the
-<filename>debian/po/templates.pot</filename> file attached or referenced in a
-URL are encouraged. Be sure to mentions in these calls for new translations
-which languages you have existing translations for, in order to avoid duplicate
-work.
-</para>
</section>
<section id="s6.5.2.3">
When the text of a debconf template is corrected and you are <emphasis
role="strong">sure</emphasis> that the change does <emphasis
role="strong">not</emphasis> affect translations, please be kind to translators
-and unfuzzy their translations.
+and <emphasis>unfuzzy</emphasis> their translations.
</para>
<para>
If you don't do so, the whole template will not be translated as long as a
translator will send you an update.
</para>
<para>
-To <literal>unfuzzy</literal> translations, you can proceed the
-following way:
+To <emphasis>unfuzzy</emphasis> translations, you can use two methods. The first
+method does <emphasis>preventive</emphasis> search and replace actions in the
+PO files. The latter uses <command>gettext</command> utilities to <emphasis>unfuzzy</emphasis>
+strings.
+</para>
+<para>
+<emphasis>Preventive unfuzzy</emphasis> method:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Try finding a complete translation file <emphasis role="strong"> before</emphasis>
+the change:
+</para>
+<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done</programlisting>
+<para>
+The file only showing <emphasis>translated</emphasis> items will be used
+as the reference file. If there is none (which should not happen if you take
+care to properly interact with translators), you should use the file
+with the most translated strings.
+</para>
+</listitem>
+<listitem>
+<para>
+Identify the needed change. In this example, let's assume the change is about
+fixing a typo in the word <literal>typo</literal> which was inadvertently
+written as <literal>tpyo</literal>. Therefore, the change is
+<command>s/tpyo/typo</command>.
+</para>
+</listitem>
+<listitem>
+<para>
+Check that this change is only applied to the place where you really intend
+to make it and <emphasis role="strong">not</emphasis> in any other place
+where the original string is appropriate. This specifically applies to
+change in punctuation, for instance.
+</para>
+</listitem>
+<listitem>
+<para>
+Modify all PO files by using <command>sed</command>. The use of that command
+is recommended over any text editor to guarantee that the files encoding will
+not be broken by the edit action.
+</para>
+<programlisting>
+cd debian/po
+for i in *.po; do sed -i 's/tpyo/typo/g' $i; done
+</programlisting>
+</listitem>
+<listitem>
+<para>
+Change the debconf template file to fix the typo.
+</para>
+</listitem>
+<listitem>
+<para>
+Run <command>debconf-updatepo</command>
+</para>
+</listitem>
+<listitem>
+<para>
+Check the <filename>foo.po</filename> reference file. Its statistics should
+not be changed:
+</para>
+<programlisting>
+msgfmt -o /dev/null --statistics debian/po/foo.po
+</programlisting>
+</listitem>
+<listitem>
+If the file's statistics changed, you did something wrong. Try again
+or ask for help on the &email-debian-i18n; mailing list.
+</listitem>
+</orderedlist>
+<para>
+Gettext utilities method:
</para>
<orderedlist numeration="arabic">
<listitem>
<title>Do not make assumptions about interfaces</title>
<para>
Templates text should not make reference to widgets belonging to some debconf
-interfaces. Sentences like If you answer Yes... have no meaning for users of
+interfaces. Sentences like <emphasis>If you answer Yes...</emphasis> have no meaning for users of
graphical interfaces which use checkboxes for boolean questions.
</para>
<para>
<section id="s6.5.2.5">
<title>Do not use first person</title>
<para>
-You should avoid the use of first person (I will do this... or We
-recommend...). The computer is not a person and the Debconf templates do not
+You should avoid the use of first person (<emphasis>I will do this...</emphasis> or <emphasis>We
+recommend...</emphasis>). The computer is not a person and the Debconf templates do not
speak for the Debian developers. You should use neutral construction. Those
of you who already wrote scientific publications, just write your templates
-like you would write a scientific paper. However, try using action voice if
-still possible, like Enable this if ... instead of This can be enabled if ....
+like you would write a scientific paper. However, try using active voice if
+still possible, like <emphasis>Enable this if ...</emphasis> instead of <emphasis>This can be enabled if...</emphasis>.
</para>
</section>
<para>
A choice between one of a number of values. The choices must be specified in a
field named 'Choices'. Separate the possible values with commas and spaces,
-like this: Choices: yes, no, maybe
+like this: <literal>Choices: yes, no, maybe</literal>.
+</para>
+<para>
+If choices are translatable strings, the 'Choices' field may be marked as
+translatable by using <literal>__Choices</literal>. The double underscore will split out
+each choice in a separate string.
+</para>
+<para>
+The <command>po-debconf</command> system also offers interesting possibilities
+to only mark <emphasis role="strong">some</emphasis> choices as translatable.
+Example:
+</para>
+<programlisting>
+Template: foo/bar
+Type: Select
+#flag:translate:3
+__Choices: PAL, SECAM, Other
+_Description: TV standard:
+ Please choose the TV standard used in your country.
+</programlisting>
+<para>
+In that example, only the 'Other' string is translatable while others
+are acronyms that should not be translated. The above allows only
+'Other' to be included in PO and POT files.
+</para>
+<para>
+The debconf templates flag system offers many such possibilities. The
+<citerefentry>
+<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum>
+</citerefentry> manual page lists all these possibilities.
</para>
</section>
<para>
This special field allow translators to put the most appropriate choice
according to their own language. It will become the default choice when their
-language is used while your own mentioned Default Choice will be used chan
+language is used while your own mentioned Default Choice will be used when
using English.
</para>
<para>
<footnote><para> As a special exception, if the omission of non-free files
would lead to the source failing to build without assistance from the Debian
diff, it might be appropriate to instead edit the files, omitting only the
-non-free parts of them, and/or explain the situation in a README.Debian-source
-<!-- or similarly named -->
+non-free parts of them, and/or explain the situation in a README.source
file in the root of the source tree. But in that case please also urge the
upstream author to make the non-free components easier seperable from the rest
of the source. </para> </footnote>