X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=po4a%2Fpo%2Fbest-pkging-practices.pot;h=ffe7e72031d83a84976f88120c230930928ce032;hb=dd09147814be411e5c238732230be88cf2f54dd4;hp=d65c41ddda7c7b3720fa3222d5bd045917ccae3d;hpb=77cab965d9dbb3b3ec96b588c612b3dba78efb3a;p=developers-reference.git diff --git a/po4a/po/best-pkging-practices.pot b/po4a/po/best-pkging-practices.pot index d65c41d..ffe7e72 100644 --- a/po4a/po/best-pkging-practices.pot +++ b/po4a/po/best-pkging-practices.pot @@ -1,25 +1,27 @@ # SOME DESCRIPTIVE TITLE # Copyright (C) YEAR Free Software Foundation, Inc. +# This file is distributed under the same license as the PACKAGE package. # FIRST AUTHOR , YEAR. -# +# #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" -"POT-Creation-Date: 2007-07-01 21:01+0000\n" +"POT-Creation-Date: 2011-09-10 16:28-0400\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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: +#. 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 " @@ -31,7 +33,7 @@ msgid "" "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 " @@ -40,12 +42,12 @@ msgid "" "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> " @@ -54,18 +56,18 @@ msgid "" "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 " @@ -74,7 +76,7 @@ msgid "" "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 " @@ -84,7 +86,7 @@ msgid "" "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 " @@ -102,7 +104,7 @@ msgid "" "<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> " @@ -110,15 +112,15 @@ msgid "" "<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 " @@ -128,12 +130,12 @@ msgid "" "<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 " @@ -145,45 +147,55 @@ msgid "" "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 " @@ -192,8 +204,8 @@ msgid "" "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 " @@ -204,8 +216,8 @@ msgid "" "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 " @@ -214,13 +226,13 @@ msgid "" "<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 " @@ -228,8 +240,8 @@ msgid "" "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 " @@ -240,13 +252,13 @@ msgid "" "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, " @@ -255,8 +267,8 @@ msgid "" "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 " @@ -264,8 +276,8 @@ msgid "" "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 — " @@ -274,16 +286,16 @@ msgid "" "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 " @@ -292,94 +304,102 @@ msgid "" "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 " @@ -387,13 +407,13 @@ msgid "" "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 " @@ -401,8 +421,8 @@ msgid "" "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 " @@ -412,8 +432,8 @@ msgid "" "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 " @@ -421,152 +441,117 @@ msgid "" "<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 " @@ -580,8 +565,8 @@ msgid "" "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 " @@ -594,57 +579,59 @@ msgid "" "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 " @@ -652,8 +639,8 @@ msgid "" "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 " @@ -662,8 +649,8 @@ msgid "" "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 " @@ -671,8 +658,8 @@ msgid "" "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 " @@ -680,21 +667,21 @@ msgid "" "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 " @@ -704,16 +691,16 @@ msgid "" "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 " @@ -726,8 +713,8 @@ msgid "" "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 " @@ -735,88 +722,88 @@ msgid "" "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 " @@ -826,49 +813,53 @@ msgid "" "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" @@ -879,34 +870,37 @@ msgid "" " 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 " @@ -916,23 +910,23 @@ msgid "" "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 " @@ -941,8 +935,8 @@ msgid "" "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 " @@ -951,8 +945,8 @@ msgid "" "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 " @@ -960,38 +954,38 @@ msgid "" "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> " @@ -1001,15 +995,15 @@ msgid "" "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 " @@ -1019,8 +1013,8 @@ msgid "" "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> " @@ -1029,8 +1023,8 @@ msgid "" "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 " @@ -1038,13 +1032,13 @@ msgid "" "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 " @@ -1052,17 +1046,17 @@ msgid "" "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> " @@ -1070,39 +1064,39 @@ msgid "" "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 " @@ -1110,170 +1104,292 @@ msgid "" "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 " @@ -1281,127 +1397,173 @@ msgid "" "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 " @@ -1410,59 +1572,59 @@ msgid "" "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 " @@ -1470,15 +1632,15 @@ msgid "" "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 " @@ -1487,16 +1649,16 @@ msgid "" "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 " @@ -1504,82 +1666,82 @@ msgid "" "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 " @@ -1587,8 +1749,8 @@ msgid "" "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 " @@ -1596,34 +1758,34 @@ msgid "" "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 " @@ -1631,8 +1793,8 @@ msgid "" "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 " @@ -1640,77 +1802,80 @@ msgid "" "(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" @@ -1722,64 +1887,74 @@ msgid "" "(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 " @@ -1787,8 +1962,8 @@ msgid "" "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, " @@ -1801,11 +1976,11 @@ msgid "" "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 " @@ -1818,38 +1993,38 @@ msgid "" "</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 " @@ -1857,18 +2032,29 @@ msgid "" "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, " @@ -1880,13 +2066,13 @@ msgid "" "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 " @@ -1894,35 +2080,35 @@ msgid "" "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 " @@ -1931,8 +2117,8 @@ msgid "" "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 " @@ -1940,20 +2126,40 @@ msgid "" "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 " @@ -1962,29 +2168,29 @@ msgid "" "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 " @@ -1992,29 +2198,29 @@ msgid "" "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, " @@ -2023,34 +2229,34 @@ msgid "" "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 " @@ -2058,8 +2264,8 @@ msgid "" "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" @@ -2071,16 +2277,16 @@ msgid "" "$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 " @@ -2089,17 +2295,17 @@ msgid "" "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: " @@ -2107,33 +2313,33 @@ msgid "" "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,lzma}</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 " @@ -2141,24 +2347,28 @@ msgid "" "<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,lzma}</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,lzma}</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 " @@ -2167,46 +2377,47 @@ msgid "" "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 " @@ -2215,83 +2426,85 @@ msgid "" "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,lzma}</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,lzma}</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,lzma}</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,lzma}</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 " @@ -2299,96 +2512,60 @@ msgid "" "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 " @@ -2400,51 +2577,89 @@ msgid "" "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 ""