# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR Free Software Foundation, Inc.
+# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
-#
+#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2007-07-01 21:01+0000\n"
+"POT-Creation-Date: 2011-10-12 09:49+0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=utf-8\n"
-"Content-Transfer-Encoding: ENCODING"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
-# type: Content of: <chapter><title>
+#. type: Content of: <chapter><title>
#: best-pkging-practices.dbk:7
msgid "Best Packaging Practices"
msgstr ""
-# type: Content of: <chapter><para>
+#
. type: Content of: <chapter><para>
#: best-pkging-practices.dbk:9
msgid ""
"Debian's quality is largely due to the <ulink "
"create and maintain excellent packages."
msgstr ""
-# type: Content of: <chapter><para>
+#
. type: Content of: <chapter><para>
#: best-pkging-practices.dbk:18
msgid ""
"This chapter provides some best practices for Debian developers. All "
"developers. Feel free to pick and choose whatever works best for you."
msgstr ""
-# type: Content of: <chapter><section><title>
+#. type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:24
msgid "Best practices for <filename>debian/rules</filename>"
msgstr ""
-# type: Content of: <chapter><section><para>
+#
. type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:26
msgid ""
"The following recommendations apply to the <filename>debian/rules</filename> "
"it's usually the file maintainers spend the most time on."
msgstr ""
-# type: Content of: <chapter><section><section><title>
+#. type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:32
msgid "Helper scripts"
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:34
msgid ""
"The rationale for using helper scripts in <filename>debian/rules</filename> "
"is that they let maintainers use and share common logic among many "
"packages. Take for instance the question of installing menu entries: you "
-"need to put the file into <filename>/usr/lib/menu</filename> (or "
+"need to put the file into <filename>/usr/share/menu</filename> (or "
"<filename>/usr/lib/menu</filename> for executable binary menufiles, if this "
"is needed), and add commands to the maintainer scripts to register and "
"unregister the menu entries. Since this is a very common thing for packages "
"have to be changed."
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:45
msgid ""
"Helper scripts take care of these issues. Assuming you comply with the "
"changes."
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:52
msgid ""
"<xref linkend=\"tools\"/> contains a couple of different helpers. The most "
"<filename>debian/rules</filename>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:66
msgid ""
"You can get started with <systemitem role=\"package\">debhelper</systemitem> "
"<manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that "
"come with the package. <command>dh_make</command>, from the <systemitem "
"role=\"package\">dh-make</systemitem> package (see <xref "
-"linkend=\"dh-make\"/> ), can be used to convert a vanilla source package to "
-"a <systemitem role=\"package\">debhelper</systemitem>ized package. This "
+"linkend=\"dh-make\"/>), can be used to convert a vanilla source package to a "
+"<systemitem role=\"package\">debhelper</systemitem>ized package. This "
"shortcut, though, should not convince you that you do not need to bother "
"understanding the individual <command>dh_*</command> helpers. If you are "
"going to use a helper, you do need to take the time to learn to use that "
"helper, to learn its expectations and behavior."
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:79
msgid ""
"Some people feel that vanilla <filename>debian/rules</filename> files are "
"<ulink url=\"&url-rules-files;\"></ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><title>
+#. type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:88
msgid "Separating your patches into multiple files"
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:90
msgid ""
"Big, complex packages may have many bugs that you need to deal with. If you "
"out which patch sets to back out as a unit as bugs are fixed upstream."
msgstr ""
-# type: Content of: <chapter><section><section><para>
+#
. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:99
msgid ""
-"Unfortunately, the packaging system as such currently doesn't provide for "
-"separating the patches into several files. Nevertheless, there are ways to "
-"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."
+"Fortunately, with the source format “3.0 (quilt)” it is now possible to keep "
+"patches separate without having to modify <filename>debian/rules</filename> "
+"to setup a patch system. Patches are stored in "
+"<filename>debian/patches/</filename> and when the source package is unpacked "
+"patches listed in <filename>debian/patches/series</filename> are "
+"automatically applied. As the name implies, patches can be managed with "
+"<command>quilt</command>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:109
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:107
msgid ""
-"<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."
+"When using the older source “1.0”, it's also possible to separate patches "
+"but a dedicated patch system must be used: 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 <command>dpkg-source</command>, 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."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:116
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:119
msgid ""
-"<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>)."
+"<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."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:124
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:125
+msgid ""
+"There are other tools to manage patches, like <command>dpatch</command>, and "
+"the patch system integrated with <systemitem "
+"role=\"package\">cdbs</systemitem>."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:132
msgid "Multiple binary packages"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:126
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:134
msgid ""
"A single source package will often build several binary packages, either to "
"provide several flavors of the same software (e.g., the <systemitem "
"needed, and thus save some disk space)."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:133
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:141
msgid ""
"The second case can be easily managed in <filename>debian/rules</filename>. "
"You just need to move the appropriate files from the build directory into "
"inter-package dependencies set right in <filename>debian/control</filename>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:142
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:150
msgid ""
"The first case is a bit more difficult since it involves multiple recompiles "
"of the same software but with different configuration options. The "
"<filename>debian/rules</filename> file."
msgstr ""
-# type: Content of: <chapter><section><title>
-#: best-pkging-practices.dbk:154
+#. type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:162
msgid "Best practices for <filename>debian/control</filename>"
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:156
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:164
msgid ""
"The following practices are relevant to the "
"<filename>debian/control</filename> file. They supplement the <ulink "
"descriptions</ulink>."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:162
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:170
msgid ""
"The description of the package, as defined by the corresponding field in the "
"<filename>control</filename> file, contains both the package synopsis and "
"guidelines specific to the description."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:171
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:179
msgid "General guidelines for package descriptions"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:173
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:181
msgid ""
"The package description should be written for the average likely user, the "
"average person who will use and benefit from the package. For instance, "
"written for a less technical user."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:180
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:188
msgid ""
"Our review of package descriptions lead us to conclude that most package "
"descriptions are technical, that is, are not written to make sense for "
"users, this is a problem."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:186
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:194
msgid ""
"How do you write for non-technical users? Avoid jargon. Avoid referring to "
"other applications or frameworks that the user might not be familiar with — "
"must use technical terms, introduce them."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:193
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:201
msgid ""
"Be objective. Package descriptions are not the place for advocating your "
"package, no matter how much you love it. Remember that the reader may not "
"care about the same things you care about."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:198
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:206
msgid ""
"References to the names of any other software packages, protocol names, "
"standards, or specifications should use their canonical forms, if one "
"Use PostScript, not Postscript or postscript."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:205
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:213
msgid ""
"If you are having problems writing your description, you may wish to send it "
"along to &email-debian-l10n-english; and request feedback."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:211
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:219
msgid "The package synopsis, or short description"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:213
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:221
msgid ""
-"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."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:217
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:225
msgid ""
-"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)."
+"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:"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:226
-msgid ""
-"It might help to imagine that the synopsis is combined with the package name "
-"in the following way:"
-msgstr ""
-
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:230
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:231
#, no-wrap
msgid ""
-"<replaceable>package-name</replaceable> is a "
-"<replaceable>synopsis</replaceable>."
+"Package: libeg0\n"
+"Description: exemplification support library\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:233
-msgid "Alternatively, it might make sense to think of it as"
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:235
+msgid ""
+"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 <replaceable>name</replaceable> and "
+"<replaceable>synopsis</replaceable> into this formula:"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:236
-#, no-wrap
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:240
msgid ""
-"<replaceable>package-name</replaceable> is "
+"The package <replaceable>name</replaceable> provides {a,an,the,some} "
"<replaceable>synopsis</replaceable>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:239
-msgid "or, if the package name itself is a plural (such as developers-tools)"
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:244
+msgid ""
+"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:"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:242
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:249
#, no-wrap
msgid ""
-"<replaceable>package-name</replaceable> are "
-"<replaceable>synopsis</replaceable>."
+"Package: eg-tools\n"
+"Description: simple exemplification system (utilities)\n"
+"\t\t\t \n"
+"Package: eg-doc\n"
+"Description: simple exemplification system - documentation\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:245
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:256
msgid ""
-"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:"
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:252
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:263
+msgid ""
+"The package <replaceable>name</replaceable> provides {a,an,the} "
+"<replaceable>role</replaceable> for the <replaceable>suite</replaceable>."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:269
msgid "The long description"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:254
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:271
msgid ""
"The long description is the primary information available to the user about "
"a package before they install it. It should provide all the information "
"the user has already read the package synopsis."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:260
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:277
msgid "The long description should consist of full and complete sentences."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:263
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:280
msgid ""
"The first paragraph of the long description should answer the following "
"questions: what does the package do? what task does it help the user "
"of course the audience for the package is necessarily technical."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:269
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:286
msgid ""
"The following paragraphs should answer the following questions: Why do I as "
"a user need this package? What other features does the package have? What "
"is the client for the foo server)?"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:277
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:294
msgid ""
"Be careful to avoid spelling and grammar mistakes. Ensure that you "
"spell-check it. Both <command>ispell</command> and "
"<filename>debian/control</filename> files:"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:282
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:299
#, no-wrap
-msgid "ispell -d american -g debian/control"
+msgid "ispell -d american -g debian/control\n"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:285
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:302
#, no-wrap
-msgid "aspell -d en -D -c debian/control"
+msgid "aspell -d en -D -c debian/control\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:288
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:305
msgid ""
"Users usually expect these questions to be answered in the package "
"description:"
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:293
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:310
msgid ""
"What does the package do? If it is an add-on to another package, then the "
"short description of the package we are an add-on to should be put in here."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:299
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:316
msgid ""
"Why should I want this package? This is related to the above, but not the "
"same (this is a mail user agent; this is cool, fast, interfaces with PGP and "
"LDAP and IMAP, has features X, Y, and Z)."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:306
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:323
msgid ""
"If this package should not be installed directly, but is pulled in by "
"another package, this should be mentioned."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:312
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:329
msgid ""
-"If the package is experimental, or there are other reasons it should not be "
-"used, if there are other packages that should be used instead, it should be "
-"here as well."
+"If the package is <literal>experimental</literal>, or there are other "
+"reasons it should not be used, if there are other packages that should be "
+"used instead, it should be here as well."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:319
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:336
msgid ""
"How is this package different from the competition? Is it a better "
"implementation? more features? different features? Why should I choose this "
"package."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:332
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:349
msgid "Upstream home page"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:334
-msgid ""
-"We recommend that you add the URL for the package's home page to the package "
-"description in <filename>debian/control</filename>. This information should "
-"be added at the end of description, using the following format:"
-msgstr ""
-
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:339
-#, no-wrap
-msgid ""
-".\n"
-" Homepage: http://some-project.some-place.org/"
-msgstr ""
-
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:343
-msgid ""
-"Note the spaces prepending the line, which serves to break the lines "
-"correctly. To see an example of how this displays, see <ulink "
-"url=\"&url-eg-desc-upstream-info;\"></ulink>."
-msgstr ""
-
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:348
-msgid ""
-"If there is no home page for the software, this should naturally be left "
-"out."
-msgstr ""
-
-# type: Content of: <chapter><section><section><para>
+#. type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:351
msgid ""
-"Note that we expect this field will eventually be replaced by a proper "
-"<filename>debian/control</filename> field understood by "
-"<command>dpkg</command> and <literal>&packages-host;</literal>. If you "
-"don't want to bother migrating the home page from the description to this "
-"field, you should probably wait until that is available. Please make sure "
-"that this line matches the regular expression <literal>/^ Homepage: [^ "
-"]*$/</literal>, as this allows <filename>&packages-host;</filename> to parse "
-"it correctly."
+"We recommend that you add the URL for the package's home page in the "
+"<literal>Homepage</literal> field of the <literal>Source</literal> section "
+"in <filename>debian/control</filename>. Adding this information in the "
+"package description itself is considered deprecated."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:362
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:359
msgid "Version Control System location"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:364
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:361
msgid ""
"There are additional fields for the location of the Version Control System "
"in <filename>debian/control</filename>."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:368
-msgid "XS-Vcs-Browser"
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:365
+msgid "Vcs-Browser"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:370
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:367
msgid ""
"Value of this field should be a <literal>http://</literal> URL pointing to a "
"web-browsable copy of the Version Control System repository used to maintain "
"the given package, if available."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:375
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:372
msgid ""
"The information is meant to be useful for the final user, willing to browse "
"the latest work done on the package (e.g. when looking for the patch fixing "
"a bug tagged as <literal>pending</literal> in the bug tracking system)."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:382
-msgid "XS-Vcs-*"
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:379
+msgid "Vcs-*"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:384
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:381
msgid ""
"Value of this field should be a string identifying unequivocally the "
"location of the Version Control System repository used to maintain the given "
"interface."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:395
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:392
msgid ""
"The information is meant to be useful for a user knowledgeable in the given "
"Version Control System and willing to build the current version of a package "
"repository instead of pointing to an SSH-accessible version of the same."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:406
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:403
msgid ""
"In the following example, an instance of the field for a Subversion "
"repository of the <systemitem role=\"package\">vim</systemitem> package is "
"shown. Note how the URL is in the <literal>svn://</literal> scheme (instead "
"of <literal>svn+ssh://</literal>) and how it points to the "
"<filename>trunk/</filename> branch. The use of the "
-"<literal>XS-Vcs-Browser</literal> field described above is also shown."
+"<literal>Vcs-Browser</literal> and <literal>Homepage</literal> fields "
+"described above is also shown."
msgstr ""
-# type: Content of: <chapter><section><section><section><screen>
-#: best-pkging-practices.dbk:414
+#. type: Content of: <chapter><section><section><section><screen>
+#: best-pkging-practices.dbk:412
#, no-wrap
msgid ""
-"Source: vim\n"
+" Source: vim\n"
" Section: editors\n"
" Priority: optional\n"
" <snip>\n"
-" XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
-" XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim"
+" Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
+" Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim\n"
+" Homepage: http://www.vim.org\n"
msgstr ""
-# type: Content of: <chapter><section><title>
-#: best-pkging-practices.dbk:428
+#. type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:427
msgid "Best practices for <filename>debian/changelog</filename>"
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:430
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:429
msgid ""
"The following practices supplement the <ulink "
"url=\"&url-debian-policy;ch-docs.html#s-changelogs\">Policy on changelog "
"files</ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:435
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:434
msgid "Writing useful changelog entries"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:437
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:436
msgid ""
"The changelog entry for a package revision documents changes in that "
"revision, and only them. Concentrate on describing significant and "
"user-visible changes that were made since the last version."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:442
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:441
msgid ""
"Focus on <emphasis>what</emphasis> was changed — who, how and when are "
"usually less important. Having said that, remember to politely attribute "
"have sent in patches)."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:448
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:447
msgid ""
"There's no need to elaborate the trivial and obvious changes. You can also "
"aggregate several changes in one entry. On the other hand, don't be overly "
"explanations, use the <filename>README.Debian</filename> file."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:455
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:454
msgid ""
"Use common English so that the majority of readers can comprehend it. Avoid "
"abbreviations, tech-speak and jargon when explaining changes that close "
"particularly technically savvy. Be polite, don't swear."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:461
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:460
msgid ""
"It is sometimes desirable to prefix changelog entries with the names of the "
"files that were changed. However, there's no need to explicitly list each "
"or repetitive. You may use wildcards."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:467
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:466
msgid ""
"When referring to bugs, don't assume anything. Say what the problem was, "
"how it was fixed, and append the closes: #nnnnn string. See <xref "
"linkend=\"upload-bugfix\"/> for more information."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:474
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:473
msgid "Common misconceptions about changelog entries"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:476
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:475
msgid ""
"The changelog entries should <emphasis role=\"strong\">not</emphasis> "
"document generic packaging issues (Hey, if you're looking for foo.conf, it's "
"file."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:484
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:483
msgid ""
"The only bugs closed with a changelog entry should be those that are "
"actually fixed in the same package revision. Closing unrelated bugs in the "
-"changelog is bad practice. See <xref linkend=\"upload-bugfix\"/> ."
+"changelog is bad practice. See <xref linkend=\"upload-bugfix\"/>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:489
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:488
msgid ""
"The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
"used for random discussion with bug reporters (I don't see segfaults when "
"more information on how to use the bug tracking system."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:500
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:499
msgid ""
"It is an old tradition to acknowledge bugs fixed in non-maintainer uploads "
"in the first changelog entry of the proper maintainer upload. As we have "
"just mention this fact in your own changelog entry."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:508
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:507
msgid "Common errors in changelog entries"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:510
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:509
msgid ""
"The following examples demonstrate some common errors or examples of bad "
"style in changelog entries."
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:514
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:513
#, no-wrap
-msgid "* Fixed all outstanding bugs."
+msgid " * Fixed all outstanding bugs.\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:517
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:516
msgid "This doesn't tell readers anything too useful, obviously."
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:520
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:519
#, no-wrap
-msgid "* Applied patch from Jane Random."
+msgid " * Applied patch from Jane Random.\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:523
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:522
msgid "What was the patch about?"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:526
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:525
#, no-wrap
-msgid "* Late night install target overhaul."
+msgid " * Late night install target overhaul.\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:529
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:528
msgid ""
"Overhaul which accomplished what? Is the mention of late night supposed to "
"remind us that we shouldn't trust that code?"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:533
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:532
#, no-wrap
-msgid "* Fix vsync FU w/ ancient CRTs."
+msgid " * Fix vsync FU w/ ancient CRTs.\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:536
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:535
msgid ""
"Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a "
"curse word!) was actually about, or how it was fixed."
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:540
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:539
#, no-wrap
-msgid "* This is not a bug, closes: #nnnnnn."
+msgid " * This is not a bug, closes: #nnnnnn.\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:543
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:542
msgid ""
"First of all, there's absolutely no need to upload the package to convey "
"this information; instead, use the bug tracking system. Secondly, there's "
"no explanation as to why the report is not a bug."
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:548
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:547
#, no-wrap
-msgid "* Has been fixed for ages, but I forgot to close; closes: #54321."
+msgid " * Has been fixed for ages, but I forgot to close; closes: #54321.\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:551
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:550
msgid ""
"If for some reason you didn't mention the bug number in a previous changelog "
"entry, there's no problem, just close the bug normally in the BTS. There's "
"changelog)."
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:558
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:557
#, no-wrap
-msgid "* Closes: #12345, #12346, #15432"
+msgid " * Closes: #12345, #12346, #15432\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:561
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:560
msgid ""
"Where's the description? If you can't think of a descriptive message, start "
"by inserting the title of each different bug."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:567
-msgid "Supplementing changelogs with NEWS.Debian files"
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:566
+msgid "Supplementing changelogs with <filename>NEWS.Debian</filename> files"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:569
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:568
msgid ""
-"Important news about changes in a package can also be put in NEWS.Debian "
-"files. The news will be displayed by tools like apt-listchanges, before all "
+"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 <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 it is less annoying and the user can go back and refer "
-"to the NEWS.Debian file after the install. And it's better than listing "
-"major changes in README.Debian, since the user can easily miss such notes."
+"<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 miss such notes."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:578
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:579
msgid ""
"The file format is the same as a debian changelog file, but leave off the "
"asterisks and describe each news item with a full paragraph when necessary "
"rather than the more concise summaries that would go in a changelog. It's a "
-"good idea to run your file through dpkg-parsechangelog to check its "
-"formatting as it will not be automatically checked during build as the "
-"changelog is. Here is an example of a real NEWS.Debian file:"
+"good idea to run your file through <literal>dpkg-parsechangelog</literal> to "
+"check its formatting as it will not be automatically checked during build as "
+"the changelog is. Here is an example of a real "
+"<filename>NEWS.Debian</filename> file:"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:586
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:588
#, no-wrap
msgid ""
"cron (3.0pl1-74) unstable; urgency=low\n"
" package.\n"
"\n"
" -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 "
-"-0500"
+"-0500\n"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:596
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:598
msgid ""
-"The NEWS.Debian file is installed as "
-"/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and always "
-"has that name even in Debian native packages. If you use debhelper, "
-"dh_installchangelogs will install debian/NEWS files for you."
+"The <filename>NEWS.Debian</filename> file is installed as "
+"<filename>/usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>. "
+"It is compressed, and always has that name even in Debian native packages. "
+"If you use <literal>debhelper</literal>, "
+"<literal>dh_installchangelogs</literal> will install "
+"<filename>debian/NEWS</filename> files for you."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:602
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:605
msgid ""
-"Unlike changelog files, you need not update NEWS.Debian files with every "
-"release. Only update them if you have something particularly newsworthy "
-"that user should know about. If you have no news at all, there's no need to "
-"ship a NEWS.Debian file in your package. No news is good news!"
+"Unlike changelog files, you need not update <filename>NEWS.Debian</filename> "
+"files with every release. Only update them if you have something "
+"particularly newsworthy that user should know about. If you have no news at "
+"all, there's no need to ship a <filename>NEWS.Debian</filename> file in your "
+"package. No news is good news!"
msgstr ""
-# type: Content of: <chapter><section><title>
-#: best-pkging-practices.dbk:623
+#. type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:627
msgid "Best practices for maintainer scripts"
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:625
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:629
msgid ""
"Maintainer scripts include the files <filename>debian/postinst</filename>, "
"<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
"supplement the <ulink url=\"&url-debian-policy;\">Debian Policy</ulink>."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:633
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:637
msgid ""
"Maintainer scripts must be idempotent. That means that you need to make "
"sure nothing bad will happen if the script is called twice where it would "
"usually be called once."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:638
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:642
msgid ""
"Standard input and output may be redirected (e.g. into pipes) for logging "
"purposes, so don't rely on them being a tty."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:642
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:646
msgid ""
"All prompting or interactive configuration should be kept to a minimum. "
"When it is necessary, you should use the <systemitem "
"stage of the <filename>postinst</filename> script."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:649
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:653
msgid ""
"Keep the maintainer scripts as simple as possible. We suggest you use pure "
"POSIX shell scripts. Remember, if you do need any bash features, the "
"role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:656
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:660
msgid ""
"If you change your maintainer scripts, be sure to test package removal, "
"double installation, and purging. Be sure that a purged package is "
"indirectly, in any maintainer script."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:662
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:666
msgid ""
"If you need to check for the existence of a command, you should use "
"something like"
msgstr ""
-# type: Content of: <chapter><section><programlisting>
-#: best-pkging-practices.dbk:665
+#
. type: Content of: <chapter><section><programlisting>
+#: best-pkging-practices.dbk:669
#, no-wrap
msgid "if [ -x /usr/sbin/install-docs ]; then ..."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:667
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:671
msgid ""
"If you don't wish to hard-code the path of a command in your maintainer "
"script, the following POSIX-compliant shell function may help:"
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:672
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:676
msgid ""
-"You can use this function to search <literal>$PATH</literal> for a command "
+"You can use this function to search <varname>$PATH</varname> for a command "
"name, passed as an argument. It returns true (zero) if the command was "
"found, and false if not. This is really the most portable way, since "
"<literal>command -v</literal>, <command>type</command>, and "
"<command>which</command> are not POSIX."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:679
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:683
msgid ""
"While <command>which</command> is an acceptable alternative, since it is "
"from the required <systemitem role=\"package\">debianutils</systemitem> "
"partition is mounted. Most scripts won't have this problem, though."
msgstr ""
-# type: Content of: <chapter><section><title>
-#: best-pkging-practices.dbk:689
+#. type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:693
msgid ""
"Configuration management with <systemitem "
"role=\"package\">debconf</systemitem>"
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:691
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:695
msgid ""
"<systemitem role=\"package\">Debconf</systemitem> is a configuration "
"management system which can be used by all the various packaging scripts "
"interaction. This will enable non-interactive installations in the future."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:699
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:703
msgid ""
"Debconf is a great tool but it is often poorly used. Many common mistakes "
"are listed in the <citerefentry> "
"to use debconf. Also, we document some best practices here."
msgstr ""
-# type: Content of: <chapter><section><para>
-#: best-pkging-practices.dbk:706
+#
. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:710
msgid ""
"These guidelines include some writing style and typography recommendations, "
"general considerations about debconf usage as well as more specific "
"for instance)."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:712
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:716
msgid "Do not abuse debconf"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:714
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:718
msgid ""
"Since debconf appeared in Debian, it has been widely abused and several "
"criticisms received by the Debian distribution come from debconf abuse with "
"thing installed."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:720
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:724
msgid ""
-"Keep usage notes to what they belong: the NEWS.Debian, or README.Debian "
-"file. Only use notes for important notes which may directly affect the "
-"package usability. Remember that notes will always block the install until "
-"confirmed or bother the user by email."
+"Keep usage notes to what they belong: the <filename>NEWS.Debian</filename>, "
+"or <filename>README.Debian</filename> file. Only use notes for important "
+"notes which may directly affect the package usability. Remember that notes "
+"will always block the install until confirmed or bother the user by email."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:726
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:730
msgid ""
"Carefully choose the questions priorities in maintainer scripts. See "
"<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
"questions should use medium and low priorities."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:734
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:738
msgid "General recommendations for authors and translators"
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:736
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:740
msgid "Write correct English"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:738
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:742
msgid ""
"Most Debian package maintainers are not native English speakers. So, "
"writing properly phrased templates may not be easy for them."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:742
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:746
msgid ""
"Please use (and abuse) &email-debian-l10n-english; mailing list. Have your "
"templates proofread."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:746
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:750
msgid ""
-"Badly written templates give a poor image of your package, of your work...or "
-"even of Debian itself."
+"Badly written templates give a poor image of your package, of your "
+"work... or even of Debian itself."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:750
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:754
msgid ""
"Avoid technical jargon as much as possible. If some terms sound common to "
"you, they may be impossible to understand for others. If you cannot avoid "
"try to balance between verbosity and simplicity."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:758
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:762
msgid "Be kind to translators"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:760
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:764
msgid ""
"Debconf templates may be translated. Debconf, along with its sister package "
"<command>po-debconf</command> offers a simple framework for getting "
"templates translated by translation teams or even individuals."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:765
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:769
msgid ""
"Please use gettext-based templates. Install <systemitem "
"role=\"package\">po-debconf</systemitem> on your development system and read "
-"its documentation (man po-debconf is a good start)."
+"its documentation (<command>man po-debconf</command> is a good start)."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:770
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:774
msgid ""
"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 "
+"work 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>."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:782
+msgid ""
+"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."
+"mentioned in the PO files headers and will be used by "
+"<command>podebconf-report-po</command>."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:794
+msgid "A recommended use of that utility is:"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:779
+#. type: Content of: <chapter><section><section><section><programlisting>
+#: best-pkging-practices.dbk:796
+#, no-wrap
msgid ""
-"The use of the <command>podebconf-report-po</command> from the po-debconf "
-"package is highly recommended to warn translators which have incomplete "
-"translations and request them for updates."
+"cd debian/po && podebconf-report-po --call --languageteam "
+"--withtranslators --deadline=\"+10 days\""
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:784
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:798
msgid ""
-"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."
+"This command will first synchronize the PO and POT files in "
+"<filename>debian/po</filename> with the templates files listed in "
+"<filename>debian/po/POTFILES.in</filename>. Then, it will send a call for "
+"new translations, in the &email-debian-i18n; mailing list. Finally, it will "
+"also 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>)."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:789
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:807
msgid ""
-"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."
+"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."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:798
+#. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:814
+msgid ""
+"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."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:821
msgid "Unfuzzy complete translations when correcting typos and spelling"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:800
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:823
msgid ""
"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."
+"translators and <emphasis>unfuzzy</emphasis> their translations."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:806
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:829
msgid ""
"If you don't do so, the whole template will not be translated as long as a "
"translator will send you an update."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:810
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:833
msgid ""
-"To <emphasis role=\"strong\">unfuzzy</emphasis> 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."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:816
+#. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:839
+msgid "<emphasis>Preventive unfuzzy</emphasis> method:"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:844
msgid ""
-"Put all incomplete PO files out of the way. You can check the completeness "
-"by using (needs the <systemitem role=\"package\">gettext</systemitem> "
-"package installed):"
+"Try finding a complete translation file <emphasis "
+"role=\"strong\">before</emphasis> the change:"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
-#: best-pkging-practices.dbk:820
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
+#: best-pkging-practices.dbk:847 best-pkging-practices.dbk:918
#, no-wrap
msgid ""
-"for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null\n"
-"--statistics $i; done"
+"for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics "
+"$i; done"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:849
+msgid ""
+"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."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:825
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:857
msgid ""
-"move all files which report either fuzzy strings to a temporary place. "
+"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>."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:865
+msgid ""
+"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."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:873
+msgid ""
+"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:"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
+#: best-pkging-practices.dbk:878
+#, no-wrap
+msgid ""
+"cd debian/po\n"
+"for i in *.po; do sed -i 's/tpyo/typo/g' $i; done\n"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:884
+msgid "Change the debconf template file to fix the typo."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:889
+msgid "Run <command>debconf-updatepo</command>."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:894
+msgid ""
+"Check the <filename>foo.po</filename> reference file. Its statistics should "
+"not be changed:"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
+#: best-pkging-practices.dbk:898
+#, no-wrap
+msgid "msgfmt -o /dev/null --statistics debian/po/foo.po\n"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:903
+msgid ""
+"If the file's statistics changed, you did something wrong. Try again or ask "
+"for help on the &email-debian-i18n; mailing list."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:909
+msgid "Gettext utilities method:"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:914
+msgid ""
+"Put all incomplete PO files out of the way. You can check the completeness "
+"by using (needs the <systemitem role=\"package\">gettext</systemitem> "
+"package installed):"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:922
+msgid ""
+"Move all files which report either fuzzy strings to a temporary place. "
"Files which report no fuzzy strings (only translated and untranslated) will "
"be kept in place."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:832
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:929
msgid ""
-"now <emphasis role=\"strong\">and now only</emphasis>, modify the template "
+"Now <emphasis role=\"strong\">and now only</emphasis>, modify the template "
"for the typos and check again that translation are not impacted (typos, "
-"spelling errors, sometimes typographical corrections are usually OK)"
+"spelling errors, sometimes typographical corrections are usually OK)."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:839
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:936
msgid ""
-"run <command>debconf-updatepo</command>. This will fuzzy all strings you "
-"modified in translations. You can see this by running the above again"
+"Run <command>debconf-updatepo</command>. This will fuzzy all strings you "
+"modified in translations. You can see this by running the above again."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:845
-msgid "use the following command:"
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:942
+msgid "Use the following command:"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
-#: best-pkging-practices.dbk:847
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
+#: best-pkging-practices.dbk:944
#, no-wrap
msgid "for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:851
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:948
msgid ""
-"move back to debian/po the files which showed fuzzy strings in the first "
-"step"
+"Move back to <filename>debian/po</filename> the files which showed fuzzy "
+"strings in the first step."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:856
-msgid "run <command>debconf-updatepo</command> again"
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:953
+msgid "Run <command>debconf-updatepo</command> again."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:863
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:960
msgid "Do not make assumptions about interfaces"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:865
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:962
msgid ""
"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 graphical interfaces which use checkboxes for boolean "
-"questions."
+"debconf interfaces. Sentences like <emphasis>If you answer "
+"Yes...</emphasis> have no meaning for users of graphical interfaces which "
+"use checkboxes for boolean questions."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:870
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:967
msgid ""
"String templates should also avoid mentioning the default values in their "
"description. First, because this is redundant with the values seen by the "
"maintainer choices (for instance, when the debconf database was preseeded)."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:876
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:973
msgid ""
"More generally speaking, try to avoid referring to user actions. Just give "
"facts."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:882
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:979
msgid "Do not use first person"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:884
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:981
msgid ""
-"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 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 ...."
+"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 active voice if still "
+"possible, like <emphasis>Enable this if ...</emphasis> instead of "
+"<emphasis>This can be enabled if...</emphasis>."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:894
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:991
msgid "Be gender neutral"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:896
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:993
msgid ""
"The world is made of men and women. Please use gender-neutral constructions "
"in your writing."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:904
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1001
msgid "Templates fields definition"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:906
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1003
msgid ""
"This part gives some information which is mostly taken from the "
"<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
"<manvolnum>7</manvolnum> </citerefentry> manual page."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:911
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1008
msgid "Type"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:913
-msgid "string:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1010
+msgid "string"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:915
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1012
msgid "Results in a free-form input field that the user can type any string into."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:920
-msgid "password:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1017
+msgid "password"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:922
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1019
msgid ""
"Prompts the user for a password. Use this with caution; be aware that the "
"password the user enters will be written to debconf's database. You should "
"probably clean that value out of the database as soon as is possible."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:929
-msgid "boolean:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1026
+msgid "boolean"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:931
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1028
msgid ""
"A true/false choice. Remember: true/false, <emphasis role=\"strong\">not "
"yes/no</emphasis>..."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:937
-msgid "select:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1034
+msgid "select"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:939
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1036
msgid ""
"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"
+"spaces, like this: <literal>Choices: yes, no, maybe</literal>."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:946
-msgid "multiselect:"
+#. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1041
+msgid ""
+"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."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:948
+#. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1046
+msgid ""
+"The <command>po-debconf</command> system also offers interesting "
+"possibilities to only mark <emphasis role=\"strong\">some</emphasis> choices "
+"as translatable. Example:"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><section><programlisting>
+#: best-pkging-practices.dbk:1051
+#, no-wrap
+msgid ""
+"Template: foo/bar\n"
+"Type: Select\n"
+"#flag:translate:3\n"
+"__Choices: PAL, SECAM, Other\n"
+"_Description: TV standard:\n"
+" Please choose the TV standard used in your country.\n"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1059
+msgid ""
+"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."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1064
+msgid ""
+"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."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1072
+msgid "multiselect"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1074
msgid ""
"Like the select data type, except the user can choose any number of items "
"from the choices list (or chose none of them)."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:954
-msgid "note:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1080
+msgid "note"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:956
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1082
msgid ""
"Rather than being a question per se, this datatype indicates a note that can "
"be displayed to the user. It should be used only for important notes that "
"mailing the note to them in some cases."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:965
-msgid "text:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1091
+msgid "text"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:967
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1093
msgid "This type is now considered obsolete: don't use it."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:972
-msgid "error:"
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1098
+msgid "error"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:974
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1100
msgid ""
"This type is designed to handle error messages. It is mostly similar to the "
"note type. Frontends may present it differently (for instance, the dialog "
"frontend of cdebconf draws a red screen instead of the usual blue one)."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><para>
-#: best-pkging-practices.dbk:979
+#
. type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:1105
msgid ""
"It is recommended to use this type for any message that needs user attention "
"for a correction of any kind."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:987
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1113
msgid "Description: short and extended description"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:989
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1115
msgid ""
"Template descriptions have two parts: short and extended. The short "
"description is in the Description: line of the template."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:993
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1119
msgid ""
"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 "
+"may be accommodated by most debconf interfaces. Keeping it short also helps "
"translators, as usually translations tend to end up being longer than the "
"original."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:999
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1125
msgid ""
"The short description should be able to stand on its own. Some interfaces "
"do not show the long description by default, or only if the user explicitely "
"want to do?"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1005
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1131
msgid ""
"The short description does not necessarily have to be a full sentence. This "
"is part of the keep it short and efficient recommendation."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1009
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1135
msgid ""
"The extended description should not repeat the short description word for "
"word. If you can't think up a long description, then first, think some "
"up with anything, leave it blank."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1016
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1142
msgid ""
"The extended description should use complete sentences. Paragraphs should "
"be kept short for improved readability. Do not mix two ideas in the same "
"paragraph but rather use another paragraph."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1021
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1147
msgid ""
"Don't be too verbose. User tend to ignore too long screens. 20 lines are "
"by experience a border you shouldn't cross, because that means that in the "
"just don't do that."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1027
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1153
msgid ""
"The extended description should <emphasis role=\"strong\">never</emphasis> "
"include a question."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1031
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1157
msgid ""
"For specific rules depending on templates type (string, boolean, etc.), "
"please read below."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1037
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1163
msgid "Choices"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1039
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1165
msgid ""
-"This field should be used for Select and Multiselect types. It contains the "
+"This field should be used for select and multiselect types. It contains the "
"possible choices which will be presented to users. These choices should be "
"separated by commas."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1046
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1172
msgid "Default"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1048
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1174
msgid ""
"This field is optional. It contains the default answer for string, select "
"and multiselect templates. For multiselect templates, it may contain a "
"comma-separated list of choices."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1057
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1183
msgid "Templates fields specific style guide"
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1059
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1185
msgid "Type field"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1061
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1187
msgid ""
"No specific indication except: use the appropriate type by referring to the "
"previous section."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1067
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1193
msgid "Description field"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1069
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1195
msgid ""
"Below are specific instructions for properly writing the Description (short "
"and extended) depending on the template type."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:1073
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1199
msgid "String/password templates"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1077
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1203
msgid ""
"The short description is a prompt and <emphasis "
"role=\"strong\">not</emphasis> a title. Avoid question style prompts (IP "
"recommended."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1084
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1210
msgid ""
"The extended description is a complement to the short description. In the "
"extended part, explain what is being asked, rather than ask the same "
"style is strongly discouraged."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:1094
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1220
msgid "Boolean templates"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1098
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1224
msgid ""
"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)"
+"long (remember that translations are often longer than original versions)."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1106
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1232
msgid ""
"Again, please avoid referring to specific interface widgets. A common "
"mistake for such templates is if you answer Yes-type constructions."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:1114
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1240
msgid "Select/Multiselect"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1118
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1244
msgid ""
"The short description is a prompt and <emphasis "
"role=\"strong\">not</emphasis> a title. Do <emphasis "
"Users are clever enough to figure out they have to choose something...:)"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1126
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1252
msgid ""
"The extended description will complete the short description. It may refer "
"to the available choices. It may also mention that the user may choose more "
"(although the interface often makes this clear)."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><title>
-#: best-pkging-practices.dbk:1136
+#. type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1262
msgid "Notes"
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1140
-msgid "The short description should be considered to be a *title*."
+#. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1266
+msgid ""
+"The short description should be considered to be a <emphasis "
+"role=\"strong\">title</emphasis>."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1145
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1271
msgid ""
"The extended description is what will be displayed as a more detailed "
"explanation of the note. Phrases, no terse writing style."
msgstr ""
-# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1151
+#
. type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1277
msgid ""
"<emphasis role=\"strong\">Do not abuse debconf.</emphasis> Notes are the "
"most common way to abuse debconf. As written in debconf-devel manual page: "
"it's best to use them only for warning about very serious problems. The "
-"NEWS.Debian or README.Debian files are the appropriate location for a lot of "
-"notes. If, by reading this, you consider converting your Note type "
-"templates to entries in NEWS/Debian or README.Debian, plus consider keeping "
-"existing translations for the future."
+"<filename>NEWS.Debian</filename> or <filename>README.Debian</filename> files "
+"are the appropriate location for a lot of notes. If, by reading this, you "
+"consider converting your Note type templates to entries in "
+"<filename>NEWS.Debian</filename> or <filename>README.Debian</filename>, plus "
+"consider keeping existing translations for the future."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1166
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1292
msgid "Choices field"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1168
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1294
msgid ""
"If the Choices are likely to change often, please consider using the "
"__Choices trick. This will split each individual choice into a single "
"string, which will considerably help translators for doing their work."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1175 best-pkging-practices.dbk:1213
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1301 best-pkging-practices.dbk:1339
msgid "Default field"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1177
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1303
msgid ""
"If the default value, for a select template, is likely to vary depending on "
"the user language (for instance, if the choice is a language choice), please "
-"use the _DefaultChoice trick."
+"use the _Default trick."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1182
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1308
msgid ""
"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 using English."
+"when using English."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1188
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1314
msgid "Example, taken from the geneweb package templates:"
msgstr ""
-# type: Content of: <chapter><section><section><section><screen>
-#: best-pkging-practices.dbk:1191
+#. type: Content of: <chapter><section><section><section><screen>
+#: best-pkging-practices.dbk:1317
#, no-wrap
msgid ""
"Template: geneweb/lang\n"
"(ro), Russian (ru), Spanish (es), Swedish (sv)\n"
"# This is the default choice. Translators may put their own language here\n"
"# instead of the default.\n"
-"# WARNING : you MUST use the ENGLISH FORM of your language\n"
+"# WARNING : you MUST use the ENGLISH NAME of your language\n"
"# For instance, the french translator will need to put French (fr) here.\n"
-"_DefaultChoice: English (en)[ translators, please see comment in PO files]\n"
-"_Description: Geneweb default language:"
+"_Default: English[ translators, please see comment in PO files]\n"
+"_Description: Geneweb default language:\n"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1202
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1328
msgid ""
"Note the use of brackets which allow internal comments in debconf fields. "
"Also note the use of comments which will show up in files the translators "
"will work with."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1207
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1333
msgid ""
-"The comments are needed as the DefaultChoice trick is a bit confusing: the "
+"The comments are needed as the _Default trick is a bit confusing: the "
"translators may put their own choice"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1215
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1341
msgid ""
"Do NOT use empty default field. If you don't want to use default values, do "
"not use Default at all."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1219
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1345
msgid ""
"If you use po-debconf (and you <emphasis role=\"strong\">should</emphasis>, "
-"see 2.2), consider making this field translatable, if you think it may be "
-"translated."
+"see <xref linkend=\"s6.5.2.2\"/>), consider making this field translatable, "
+"if you think it may be translated."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1224
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1350
msgid ""
"If the default value may vary depending on language/country (for instance "
"the default value for a language choice), consider using the special "
-"_DefaultChoice type documented in <citerefentry> "
+"_Default type documented in <citerefentry> "
"<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
-"</citerefentry>)."
+"</citerefentry>."
msgstr ""
-# type: Content of: <chapter><section><title>
-#: best-pkging-practices.dbk:1236
+#. type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:1362
msgid "Internationalization"
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1238
+#. type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:1364
+msgid ""
+"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."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1371
msgid "Handling debconf translations"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1240
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1373
msgid ""
"Like porters, translators have a difficult task. They work on many packages "
"and must collaborate with many different maintainers. Moreover, most of the "
"particularly patient with them."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1246
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1379
msgid ""
"The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
"packages configuration easier for maintainers and for users. Originally, "
"provided."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1256
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1389
msgid ""
"Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
-"is stored in <filename>po</filename> files (drawing from "
+"is stored in <filename>.po</filename> files (drawing from "
"<command>gettext</command> translation techniques). Special template files "
"contain the original messages and mark which fields are translatable. When "
"you change the value of a translatable field, by calling "
"</citerefentry> manual page for details."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1272
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1405
msgid "Internationalized documentation"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1274
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1407
msgid ""
"Internationalizing documentation is crucial for users, but a lot of labor. "
"There's no way to eliminate all that work, but you can make things easier "
"for translators."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1279
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1412
msgid ""
-"If you maintain documentation of any size, its easier for translators if "
+"If you maintain documentation of any size, it is easier for translators if "
"they have access to a source control system. That lets translators see the "
"differences between two versions of the documentation, so, for instance, "
"they can see what needs to be retranslated. It is recommended that the "
"translated documentation maintain a note about what source control revision "
"the translation is based on. An interesting system is provided by <ulink "
"url=\"&url-i18n-doc-check;\">doc-check</ulink> in the <systemitem "
-"role=\"package\">boot-floppies</systemitem> package, which shows an overview "
-"of the translation status for any given language, using structured comments "
-"for the current revision of the file to be translated and, for a translated "
-"file, the revision of the original file the translation is based on. You "
-"might wish to adapt and provide that in your CVS area."
+"role=\"package\">debian-installer</systemitem> package, which shows an "
+"overview of the translation status for any given language, using structured "
+"comments for the current revision of the file to be translated and, for a "
+"translated file, the revision of the original file the translation is based "
+"on. You might wish to adapt and provide that in your VCS area."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1293
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1426
msgid ""
"If you maintain XML or SGML documentation, we suggest that you isolate any "
"language-independent information and define those as entities in a separate "
"much easier, for instance, to keep URLs up to date across multiple files."
msgstr ""
-# type: Content of: <chapter><section><title>
-#: best-pkging-practices.dbk:1303
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1432
+msgid ""
+"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."
+msgstr ""
+
+#. type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:1444
msgid "Common packaging situations"
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1314
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1455
msgid "Packages using <command>autoconf</command>/<command>automake</command>"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1316
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1457
msgid ""
"Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
"<filename>config.guess</filename> files up to date is critical for porters, "
"recommendations."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1328
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1469
msgid "Libraries"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1330
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1471
msgid ""
"Libraries are always difficult to package for various reasons. The policy "
"imposes many constraints to ease their maintenance and to make sure upgrades "
"in a library can result in dozens of dependent packages breaking."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1336
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1477
msgid ""
"Good practices for library packaging have been grouped in <ulink "
"url=\"&url-libpkg-guide;\">the library packaging guide</ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1343
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1484
msgid "Documentation"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1345
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1486
msgid ""
"Be sure to follow the <ulink url=\"&url-debian-policy;ch-docs.html\">Policy "
"on documentation</ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1350
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1491
msgid ""
"If your package contains documentation built from XML or SGML, we recommend "
"you not ship the XML or SGML source in the binary package(s). If users want "
"the source of the documentation, they should retrieve the source package."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1355
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1496
msgid ""
"Policy specifies that documentation should be shipped in HTML format. We "
"also recommend shipping documentation in PDF and plain text format if "
"source format is HTML."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1362
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1503
msgid ""
"Major shipped manuals should register themselves with <systemitem "
"role=\"package\">doc-base</systemitem> on installation. See the <systemitem "
"information."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1370
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1509
+msgid ""
+"Debian policy (section 12.1) directs that manual pages should accompany "
+"every program, utility, and function, and suggests them for other objects "
+"like configuration files. If the work you are packaging does not have such "
+"manual pages, consider writing them for inclusion in your package, and "
+"submitting them upstream."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1516
+msgid ""
+"The manpages do not need to be written directly in the troff format. "
+"Popular source formats are Docbook, POD and reST, which can be converted "
+"using <command>xsltproc</command>, <command>pod2man</command> and "
+"<command>rst2man</command> respectively. To a lesser extent, the "
+"<command>help2man</command> program can also be used to write a stub."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1525
msgid "Specific types of packages"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1372
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1527
msgid ""
"Several specific types of packages have special sub-policies and "
"corresponding packaging rules and practices:"
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1378
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1533
msgid ""
"Perl related packages have a <ulink url=\"&url-perl-policy;\">Perl "
"policy</ulink>, some examples of packages following that policy are "
"independent perl module)."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1387
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1542
msgid ""
"Python related packages have their python policy; see &file-python-policy; "
"in the <systemitem role=\"package\">python</systemitem> package."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1394
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1549
msgid ""
"Emacs related packages have the <ulink url=\"&url-emacs-policy;\">emacs "
"policy</ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1401
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1556
msgid ""
"Java related packages have their <ulink url=\"&url-java-policy;\">java "
"policy</ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1408
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1563
msgid ""
"Ocaml related packages have their own policy, found in &file-ocaml-policy; "
"from the <systemitem role=\"package\">ocaml</systemitem> package. A good "
"package."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1416
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1571
msgid ""
"Packages providing XML or SGML DTDs should conform to the recommendations "
"found in the <systemitem role=\"package\">sgml-base-doc</systemitem> "
"package."
msgstr ""
-# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
-#: best-pkging-practices.dbk:1422
+#
. type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1577
msgid ""
"Lisp packages should register themselves with <systemitem "
"role=\"package\">common-lisp-controller</systemitem>, about which see "
"&file-lisp-controller;."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1452
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1607
msgid "Architecture-independent data"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1454
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1609
msgid ""
"It is not uncommon to have a large amount of architecture-independent data "
"packaged with a program. For example, audio files, a collection of icons, "
"best to keep it all in a single package."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1461
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1616
msgid ""
"However, if the size of the data is considerable, consider splitting it out "
-"into a separate, architecture-independent package (_all.deb). By doing "
-"this, you avoid needless duplication of the same data into eleven or more "
-".debs, one per each architecture. While this adds some extra overhead into "
-"the <filename>Packages</filename> files, it saves a lot of disk space on "
-"Debian mirrors. Separating out architecture-independent data also reduces "
-"processing time of <command>lintian</command> or <command>linda</command> "
-"(see <xref linkend=\"tools-lint\"/> ) when run over the entire Debian "
-"archive."
-msgstr ""
-
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1473
+"into a separate, architecture-independent package "
+"(<filename>_all.deb</filename>). By doing this, you avoid needless "
+"duplication of the same data into eleven or more .debs, one per each "
+"architecture. While this adds some extra overhead into the "
+"<filename>Packages</filename> files, it saves a lot of disk space on Debian "
+"mirrors. Separating out architecture-independent data also reduces "
+"processing time of <command>lintian</command> (see <xref "
+"linkend=\"tools-lint\"/>) when run over the entire Debian archive."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1628
msgid "Needing a certain locale during build"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1475
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1630
msgid ""
"If you need a certain locale during build, you can create a temporary file "
"via this trick:"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1479
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1634
msgid ""
"If you set <varname>LOCPATH</varname> to the equivalent of "
"<filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the "
"root. Something like this:"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:1484
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:1639
#, no-wrap
msgid ""
"LOCALE_PATH=debian/tmpdir/usr/lib/locale\n"
"$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
"\n"
"# Using the locale\n"
-"LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date"
+"LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date\n"
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1497
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1652
msgid "Make transition packages deborphan compliant"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1499
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1654
msgid ""
"Deborphan is a program for helping users to detect which packages can safely "
"be removed from the system, i.e. the ones that have no packages depending "
"argument, it tries to catch other useless packages."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1506
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1661
msgid ""
-"For example, with --guess-dummy, deborphan tries to search all transitional "
-"packages which were needed for upgrade but which can now safely be removed. "
-"For that, it looks for the string dummy or transitional in their short "
-"description."
+"For example, with <literal>--guess-dummy</literal>, "
+"<command>deborphan</command> tries to search all transitional packages which "
+"were needed for upgrade but which can now safely be removed. For that, it "
+"looks for the string dummy or transitional in their short description."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1512
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1668
msgid ""
"So, when you are creating such a package, please make sure to add this text "
"to your short description. If you are looking for examples, just run: "
"search .|grep transitional</command>."
msgstr ""
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1520
-msgid "Best practices for <filename>orig.tar.gz</filename> files"
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1674
+msgid ""
+"Also, it is recommended to adjust its section to <literal>oldlibs</literal> "
+"and its priority to <literal>extra</literal> in order to ease "
+"<command>deborphan</command>'s job."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1683
+msgid "Best practices for <filename>.orig.tar.{gz,bz2,xz}</filename> files"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1522
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1685
msgid ""
"There are two kinds of original source tarballs: Pristine source and "
"repackaged upstream source."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1526
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1689
msgid "Pristine source"
msgstr ""
-# type: Content of: <chapter><section><section><section><para><footnote>
-#: best-pkging-practices.dbk:1528
-msgid ""
-"The defining characteristic of a pristine source tarball is that the "
-".orig.tar.gz file is byte-for-byte identical to a tarball officially "
-"distributed by the upstream author. <footnote>"
-msgstr ""
-
-# type: Content of: <chapter><section><section><section><para><footnote><para>
-#: best-pkging-practices.dbk:1530
+#. type: Content of: <chapter><section><section><section><para><footnote><para>
+#: best-pkging-practices.dbk:1693
msgid ""
"We cannot prevent upstream authors from changing the tarball they distribute "
"without also incrementing the version number, so there can be no guarantee "
"<emphasis>currently</emphasis> distributing at any point in time. All that "
"can be expected is that it is identical to something that upstream once "
"<emphasis>did</emphasis> distribute. If a difference arises later (say, if "
-"upstream notices that he wasn't using maximal comression in his original "
-"distribution and then re-<literal>gzip</literal>s it), that's just too bad. "
-"Since there is no good way to upload a new .orig.tar.gz for the same "
-"version, there is not even any point in treating this situation as a bug."
+"upstream notices that he wasn't using maximal compression in his original "
+"distribution and then re-<command>gzip</command>s it), that's just too bad. "
+"Since there is no good way to upload a new "
+"<filename>.orig.tar.{gz,bz2,xz}</filename> for the same version, there is "
+"not even any point in treating this situation as a bug."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1540
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1691
msgid ""
-"</footnote> This makes it possible to use checksums to easily verify that "
-"all changes between Debian's version and upstream's are contained in the "
-"Debian diff. Also, if the original source is huge, upstream authors and "
-"others who already have the upstream tarball can save download time if they "
-"want to inspect your packaging in detail."
+"The defining characteristic of a pristine source tarball is that the "
+"<filename>.orig.tar.{gz,bz2,xz}</filename> file is byte-for-byte identical "
+"to a tarball officially distributed by the upstream author.<placeholder "
+"type=\"footnote\" id=\"0\"/> This makes it possible to use checksums to "
+"easily verify that all changes between Debian's version and upstream's are "
+"contained in the Debian diff. Also, if the original source is huge, "
+"upstream authors and others who already have the upstream tarball can save "
+"download time if they want to inspect your packaging in detail."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1548
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1711
msgid ""
"There is no universally accepted guidelines that upstream authors follow "
"regarding to the directory structure inside their tarball, but "
"following:"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1556
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1719
msgid "It unpacks the tarball in an empty temporary directory by doing"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
-#: best-pkging-practices.dbk:1559
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
+#: best-pkging-practices.dbk:1722
#, no-wrap
msgid ""
-"zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar "
-"xf -"
+"zcat "
+"path/to/<replaceable>packagename</replaceable>_<replaceable>upstream-version</replaceable>.orig.tar.gz "
+"| tar xf -\n"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1564
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1727
msgid ""
"If, after this, the temporary directory contains nothing but one directory "
"and no other files, <command>dpkg-source</command> renames that directory to "
-"<literal><packagename>-<upstream-version>(.orig)</literal>. The "
-"name of the top-level directory in the tarball does not matter, and is "
+"<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>(.orig)</filename>. "
+"The name of the top-level directory in the tarball does not matter, and is "
"forgotten."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1573
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1736
msgid ""
"Otherwise, the upstream tarball must have been packaged without a common "
"top-level directory (shame on the upstream author!). In this case, "
"<command>dpkg-source</command> renames the temporary directory "
"<emphasis>itself</emphasis> to "
-"<literal><packagename>-<upstream-version>(.orig)</literal>."
+"<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>(.orig)</filename>."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1584
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1747
msgid "Repackaged upstream source"
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1586
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1749
msgid ""
"You <emphasis role=\"strong\">should</emphasis> upload packages with a "
"pristine source tarball if possible, but there are various reasons why it "
"non-DFSG-free material that you must remove before uploading."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1593
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1756
msgid ""
-"In these cases the developer must construct a suitable .orig.tar.gz file "
-"himself. We refer to such a tarball as a repackaged upstream source. Note "
-"that a repackaged upstream source is different from a Debian-native "
-"package. A repackaged source still comes with Debian-specific changes in a "
-"separate <literal>.diff.gz</literal> and still has a version number composed "
-"of <literal><upstream-version></literal> and "
-"<literal><debian-revision></literal>."
+"In these cases the developer must construct a suitable "
+"<filename>.orig.tar.{gz,bz2,xz}</filename> file himself. We refer to such a "
+"tarball as a repackaged upstream source. Note that a repackaged upstream "
+"source is different from a Debian-native package. A repackaged source still "
+"comes with Debian-specific changes in a separate "
+"<filename>.diff.gz</filename> or "
+"<filename>.debian.tar.{gz,bz2,xz}</filename> and still has a version number "
+"composed of <replaceable>upstream-version</replaceable> and "
+"<replaceable>debian-version</replaceable>."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1602
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1765
msgid ""
"There may be cases where it is desirable to repackage the source even though "
-"upstream distributes a <literal>.tar.gz</literal> that could in principle be "
-"used in its pristine form. The most obvious is if "
+"upstream distributes a <filename>.tar.{gz,bz2,xz}</filename> that could in "
+"principle be used in its pristine form. The most obvious is if "
"<emphasis>significant</emphasis> space savings can be achieved by "
"recompressing the tar archive or by removing genuinely useless cruft from "
"the upstream archive. Use your own discretion here, but be prepared to "
"defend your decision if you repackage source that could have been pristine."
msgstr ""
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1611
-msgid "A repackaged .orig.tar.gz"
+#
. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1774
+msgid "A repackaged <filename>.orig.tar.{gz,bz2,xz}</filename>"
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1616
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1779
msgid ""
-"<emphasis role=\"strong\">must</emphasis> contain detailed information how "
-"the repackaged source was obtained, and how this can be reproduced in the "
+"<emphasis role=\"strong\">should</emphasis> be documented in the resulting "
+"source package. Detailed information on how the repackaged source was "
+"obtained, and on how this can be reproduced should be provided in "
"<filename>debian/copyright</filename>. It is also a good idea to provide a "
"<literal>get-orig-source</literal> target in your "
"<filename>debian/rules</filename> file that repeats the process, as "
"described in the Policy Manual, <ulink "
"url=\"&url-debian-policy;ch-source.html#s-debianrules\">Main building "
-"script: debian/rules</ulink>."
+"script: <filename>debian/rules</filename></ulink>."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote>
-#: best-pkging-practices.dbk:1628
-msgid ""
-"<emphasis role=\"strong\">should not</emphasis> contain any file that does "
-"not come from the upstream author(s), or whose contents has been changed by "
-"you. <footnote>"
-msgstr ""
-
-#. or similarly named
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para>
-#: best-pkging-practices.dbk:1630
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para>
+#: best-pkging-practices.dbk:1794
msgid ""
"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 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."
+"them, and/or explain the situation in a <filename>README.source</filename> "
+"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 separable from the "
+"rest of the source."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1642
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1792
+msgid ""
+"<emphasis role=\"strong\">should not</emphasis> contain any file that does "
+"not come from the upstream author(s), or whose contents has been changed by "
+"you.<placeholder type=\"footnote\" id=\"0\"/>"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1805
msgid ""
"<emphasis role=\"strong\">should</emphasis>, except where impossible for "
"legal reasons, preserve the entire building and portablility infrastructure "
"provided by the upstream author. For example, it is not a sufficient reason "
"for omitting a file that it is used only when building on MS-DOS. "
-"Similarly, a Makefile provided by upstream should not be omitted even if the "
-"first thing your <filename>debian/rules</filename> does is to overwrite it "
-"by running a configure script."
+"Similarly, a <filename>Makefile</filename> provided by upstream should not "
+"be omitted even if the first thing your <filename>debian/rules</filename> "
+"does is to overwrite it by running a configure script."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1651
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1814
msgid ""
"(<emphasis>Rationale:</emphasis> It is common for Debian users who need to "
"build software for non-Debian platforms to fetch the source from a Debian "
"point)."
msgstr ""
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1658
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1821
msgid ""
"<emphasis role=\"strong\">should</emphasis> use "
-"<literal><packagename>-<upstream-version>.orig</literal> as the "
-"name of the top-level directory in its tarball. This makes it possible to "
-"distinguish pristine tarballs from repackaged ones."
-msgstr ""
-
-# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
-#: best-pkging-practices.dbk:1666
-msgid ""
-"<emphasis role=\"strong\">should</emphasis> be gzipped with maximal "
-"compression."
+"<filename><replaceable>packagename</replaceable>-<replaceable>upstream-version</replaceable>.orig</filename> "
+"as the name of the top-level directory in its tarball. This makes it "
+"possible to distinguish pristine tarballs from repackaged ones."
msgstr ""
-#
type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1671
+#
. type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:1829
msgid ""
-"The canonical way to meet the latter two points is to let "
-"<literal>dpkg-source -b</literal> construct the repackaged tarball from an "
-"unpacked directory."
+"<emphasis role=\"strong\">should</emphasis> be gzipped or bzipped with "
+"maximal compression."
msgstr ""
-# type: Content of: <chapter><section><section><section><title>
-#: best-pkging-practices.dbk:1677
-msgid "Changing binary files in <literal>diff.gz</literal>"
+#. type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1836
+msgid "Changing binary files"
msgstr ""
-# type: Content of: <chapter><section><section><section><para><footnote>
-#: best-pkging-practices.dbk:1679
+#. type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1838
msgid ""
"Sometimes it is necessary to change binary files contained in the original "
-"tarball, or to add binary files that are not in it. If this is done by "
-"simply copying the files into the debianized source tree, "
-"<command>dpkg-source</command> will not be able to handle this. On the "
-"other hand, according to the guidelines given above, you cannot include such "
-"a changed binary file in a repackaged <filename>orig.tar.gz</filename>. "
-"Instead, include the file in the <filename>debian</filename> directory in "
-"<command>uuencode</command>d (or similar) form <footnote>"
-msgstr ""
-
-# type: Content of: <chapter><section><section><section><para><footnote><para>
-#: best-pkging-practices.dbk:1686
-msgid ""
-"The file should have a name that makes it clear which binary file it "
-"encodes. Usually, some postfix indicating the encoding should be appended "
-"to the original filename. Note that you don't need to depend on <systemitem "
-"role=\"package\">sharutils</systemitem> to get the "
-"<command>uudecode</command> program if you use <command>perl</command>'s "
-"<literal>pack</literal> function. The code could look like"
-msgstr ""
-
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1694
-msgid ""
-"&example-uu; </footnote>. The file would then be decoded and copied to its "
-"place during the build process. Thus the change will be visible quite easy."
-msgstr ""
-
-# type: Content of: <chapter><section><section><section><para>
-#: best-pkging-practices.dbk:1700
-msgid ""
-"Some packages use <command>dbs</command> to manage patches to their upstream "
-"source, and always create a new <literal>orig.tar.gz</literal> file that "
-"contains the real <literal>orig.tar.gz</literal> in its toplevel directory. "
-"This is questionable with respect to the preference for pristine source. On "
-"the other hand, it is easy to modify or add binary files in this case: Just "
-"put them into the newly created <literal>orig.tar.gz</literal> file, besides "
-"the real one, and copy them to the right place during the build process."
-msgstr ""
-
-# type: Content of: <chapter><section><section><title>
-#: best-pkging-practices.dbk:1713
+"tarball, or to add binary files that are not in it. This is fully supported "
+"when using source packages in “3.0 (quilt)” format, see the "
+"<citerefentry><refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum></citerefentry> "
+"manual page for details. When using the older format “1.0”, binary files "
+"can't be stored in the <filename>.diff.gz</filename> so you must store an "
+"<command>uuencode</command>d (or similar) version of the file(s) and decode "
+"it at build time in <filename>debian/rules</filename> (and move it in its "
+"official location)."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1853
msgid "Best practices for debug packages"
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1715
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1855
msgid ""
"A debug package is a package with a name ending in -dbg, that contains "
-"additional information that gdb can use. Since Debian binaries are stripped "
-"by default, debugging information, including function names and line "
-"numbers, is otherwise not available when running gdb on Debian binaries. "
-"Debug packages allow users who need this additional debugging information to "
-"install it, without bloating a regular system with the information."
+"additional information that <command>gdb</command> can use. Since Debian "
+"binaries are stripped by default, debugging information, including function "
+"names and line numbers, is otherwise not available when running "
+"<command>gdb</command> on Debian binaries. Debug packages allow users who "
+"need this additional debugging information to install it, without bloating a "
+"regular system with the information."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1723
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1863
msgid ""
"It is up to a package's maintainer whether to create a debug package or "
"not. Maintainers are encouraged to create debug packages for library "
"apache and the X server are also good candidates for debug packages."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1733
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1873
msgid ""
"Some debug packages may contain an entire special debugging build of a "
"library or other binary, but most of them can save space and build time by "
-"instead containing separated debugging symbols that gdb can find and load on "
-"the fly when debugging a program or library. The convention in Debian is to "
-"keep these symbols in <filename>/usr/lib/debug/path</filename>, where "
-"<emphasis>path</emphasis> is the path to the executable or library. For "
-"example, debugging symbols for <filename>/usr/bin/foo</filename> go in "
+"instead containing separated debugging symbols that <command>gdb</command> "
+"can find and load on the fly when debugging a program or library. The "
+"convention in Debian is to keep these symbols in "
+"<filename>/usr/lib/debug/<replaceable>path</replaceable></filename>, where "
+"<replaceable>path</replaceable> is the path to the executable or library. "
+"For example, debugging symbols for <filename>/usr/bin/foo</filename> go in "
"<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for "
"<filename>/usr/lib/libfoo.so.1</filename> go in "
"<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1745
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1885
msgid ""
-"The debugging symbols can be extracted from an object file using objcopy "
-"--only-keep-debug. Then the object file can be stripped, and objcopy "
-"--add-gnu-debuglink used to specify the path to the debugging symbol file. "
-"<citerefentry> <refentrytitle>objcopy</refentrytitle> "
-"<manvolnum>1</manvolnum> </citerefentry> explains in detail how this works."
+"The debugging symbols can be extracted from an object file using "
+"<command>objcopy --only-keep-debug</command>. Then the object file can be "
+"stripped, and <command>objcopy --add-gnu-debuglink</command> used to specify "
+"the path to the debugging symbol file. <citerefentry> "
+"<refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum> "
+"</citerefentry> explains in detail how this works."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1752
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1893
msgid ""
-"The dh_strip command in debhelper supports creating debug packages, and can "
-"take care of using objcopy to separate out the debugging symbols for you. "
-"If your package uses debhelper, all you need to do is call dh_strip "
-"--dbg-package=libfoo-dbg, and add an entry to debian/control for the debug "
-"package."
+"The <command>dh_strip</command> command in <systemitem "
+"role=\"package\">debhelper</systemitem> supports creating debug packages, "
+"and can take care of using <command>objcopy</command> to separate out the "
+"debugging symbols for you. If your package uses <systemitem "
+"role=\"package\">debhelper</systemitem>, all you need to do is call "
+"<command>dh_strip --dbg-package=libfoo-dbg</command>, and add an entry to "
+"<filename>debian/control</filename> for the debug package."
msgstr ""
-# type: Content of: <chapter><section><section><para>
-#: best-pkging-practices.dbk:1759
+#
. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1900
msgid ""
-"Note that the Debian package should depend on the package that it provides "
+"Note that the debug package should depend on the package that it provides "
"debugging symbols for, and this dependency should be versioned. For "
"example:"
msgstr ""
-# type: Content of: <chapter><section><section><screen>
-#: best-pkging-practices.dbk:1763
+#. type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:1904
#, no-wrap
-msgid "Depends: libfoo-dbg (= ${binary:Version})"
+msgid "Depends: libfoo (= ${binary:Version})\n"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1908
+msgid "Best practices for meta-packages"
+msgstr ""
+
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1910
+msgid ""
+"A meta-package is a mostly empty package that makes it easy to install a "
+"coherent set of packages that can evolve over time. It achieves this by "
+"depending on all the packages of the set. Thanks to the power of APT, the "
+"meta-package maintainer can adjust the dependencies and the user's system "
+"will automatically get the supplementary packages. The dropped packages that "
+"were automatically installed will be also be marked as removal candidates "
+"(and are even automatically removed by <command>aptitude</command>). "
+"<systemitem role=\"package\">gnome</systemitem> and <systemitem "
+"role=\"package\">linux-image-amd64</systemitem> are two examples of "
+"meta-packages (built by the source packages <systemitem "
+"role=\"package\">meta-gnome2</systemitem> and <systemitem "
+"role=\"package\">linux-latest</systemitem>)."
+msgstr ""
+
+#. type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1924
+msgid ""
+"The long description of the meta-package must clearly document its purpose "
+"so that the user knows what he will lose if he removes the package. Being "
+"explicit about the consequences is recommended. This is particularly "
+"important for meta-packages which are installed during initial installation "
+"and that have not been explicitly installed by the user. Those tend to be "
+"important to ensure smooth system upgrades and the user should be "
+"discouraged from uninstalling them to avoid potential breakages."
msgstr ""
~ianmdlvl / developers-reference.git / blobdiff