Put in place the new developers-reference and the new refcard.

[developers-reference.git] / po4a / po / best-pkging-practices.pot

# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR Free Software Foundation, Inc.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
# 
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2007-07-01 21:01+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: ENCODING"

# type: Content of: <chapter><title>
#: best-pkging-practices.dbk:7
msgid "Best Packaging Practices"
msgstr ""

# type: Content of: <chapter><para>
#: best-pkging-practices.dbk:9
msgid ""
"Debian's quality is largely due to the <ulink "
"url=\"&url-debian-policy;\">Debian Policy</ulink>, which defines explicit "
"baseline requirements which all Debian packages must fulfill.  Yet there is "
"also a shared history of experience which goes beyond the Debian Policy, an "
"accumulation of years of experience in packaging.  Many very talented people "
"have created great tools, tools which help you, the Debian maintainer, "
"create and maintain excellent packages."
msgstr ""

# type: Content of: <chapter><para>
#: best-pkging-practices.dbk:18
msgid ""
"This chapter provides some best practices for Debian developers.  All "
"recommendations are merely that, and are not requirements or policy.  These "
"are just some subjective hints, advice and pointers collected from Debian "
"developers.  Feel free to pick and choose whatever works best for you."
msgstr ""

# 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>
#: best-pkging-practices.dbk:26
msgid ""
"The following recommendations apply to the <filename>debian/rules</filename> "
"file.  Since <filename>debian/rules</filename> controls the build process "
"and selects the files which go into the package (directly or indirectly), "
"it's usually the file maintainers spend the most time on."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:32
msgid "Helper scripts"
msgstr ""

# 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 "
"<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 "
"to do, why should each maintainer rewrite all this on their own, sometimes "
"with bugs? Also, supposing the menu directory changed, every package would "
"have to be changed."
msgstr ""

# 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 "
"conventions expected by the helper script, the helper takes care of all the "
"details.  Changes in policy can be made in the helper script; then packages "
"just need to be rebuilt with the new version of the helper and no other "
"changes."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:52
msgid ""
"<xref linkend=\"tools\"/> contains a couple of different helpers.  The most "
"common and best (in our opinion) helper system is <systemitem "
"role=\"package\">debhelper</systemitem>.  Previous helper systems, such as "
"<systemitem role=\"package\">debmake</systemitem>, were monolithic: you "
"couldn't pick and choose which part of the helper you found useful, but had "
"to use the helper to do everything.  <systemitem "
"role=\"package\">debhelper</systemitem>, however, is a number of separate "
"little <command>dh_*</command> programs.  For instance, "
"<command>dh_installman</command> installs and compresses man pages, "
"<command>dh_installmenu</command> installs menu files, and so on.  Thus, it "
"offers enough flexibility to be able to use the little helper scripts, where "
"useful, in conjunction with hand-crafted commands in "
"<filename>debian/rules</filename>."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:66
msgid ""
"You can get started with <systemitem role=\"package\">debhelper</systemitem> "
"by reading <citerefentry> <refentrytitle>debhelper</refentrytitle> "
"<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 "
"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>
#: best-pkging-practices.dbk:79
msgid ""
"Some people feel that vanilla <filename>debian/rules</filename> files are "
"better, since you don't have to learn the intricacies of any helper system.  "
"This decision is completely up to you.  Use what works for you.  Many "
"examples of vanilla <filename>debian/rules</filename> files are available at "
"<ulink url=\"&url-rules-files;\"></ulink>."
msgstr ""

# 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>
#: best-pkging-practices.dbk:90
msgid ""
"Big, complex packages may have many bugs that you need to deal with.  If you "
"correct a number of bugs directly in the source, and you're not careful, it "
"can get hard to differentiate the various patches that you applied.  It can "
"get quite messy when you have to update the package to a new upstream "
"version which integrates some of the fixes (but not all).  You can't take "
"the total set of diffs (e.g., from <filename>.diff.gz</filename>) and work "
"out which patch sets to back out as a unit as bugs are fixed upstream."
msgstr ""

# 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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:109
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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:116
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>)."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:124
msgid "Multiple binary packages"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:126
msgid ""
"A single source package will often build several binary packages, either to "
"provide several flavors of the same software (e.g., the <systemitem "
"role=\"package\">vim</systemitem> source package) or to make several small "
"packages instead of a big one (e.g., so the user can install only the subset "
"needed, and thus save some disk space)."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:133
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 "
"the package's temporary trees.  You can do this using "
"<command>install</command> or <command>dh_install</command> from <systemitem "
"role=\"package\">debhelper</systemitem>.  Be sure to check the different "
"permutations of the various packages, ensuring that you have the "
"inter-package dependencies set right in <filename>debian/control</filename>."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:142
msgid ""
"The first case is a bit more difficult since it involves multiple recompiles "
"of the same software but with different configuration options.  The "
"<systemitem role=\"package\">vim</systemitem> source package is an example "
"of how to manage this using an hand-crafted "
"<filename>debian/rules</filename> file."
msgstr ""

# type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:154
msgid "Best practices for <filename>debian/control</filename>"
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:156
msgid ""
"The following practices are relevant to the "
"<filename>debian/control</filename> file.  They supplement the <ulink "
"url=\"&url-debian-policy;ch-binary.html#s-descriptions\">Policy on package "
"descriptions</ulink>."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:162
msgid ""
"The description of the package, as defined by the corresponding field in the "
"<filename>control</filename> file, contains both the package synopsis and "
"the long description for the package.  <xref linkend=\"bpp-desc-basics\"/> "
"describes common guidelines for both parts of the package description.  "
"Following that, <xref linkend=\"bpp-pkg-synopsis\"/> provides guidelines "
"specific to the synopsis, and <xref linkend=\"bpp-pkg-desc\"/> contains "
"guidelines specific to the description."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:171
msgid "General guidelines for package descriptions"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:173
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, "
"development packages are for developers, and can be technical in their "
"language.  More general-purpose applications, such as editors, should be "
"written for a less technical user."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:180
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 "
"non-technical users.  Unless your package really is only for technical "
"users, this is a problem."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:186
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 — "
"GNOME or KDE is fine, since users are probably familiar with these terms, "
"but GTK+ is probably not.  Try not to assume any knowledge at all.  If you "
"must use technical terms, introduce them."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:193
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
msgid ""
"References to the names of any other software packages, protocol names, "
"standards, or specifications should use their canonical forms, if one "
"exists.  For example, use X Window System, X11, or X; not X Windows, "
"X-Windows, or X Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  "
"Use PostScript, not Postscript or postscript."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:205
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
msgid "The package synopsis, or short description"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:213
msgid ""
"The synopsis line (the short description) should be concise.  It must not "
"repeat the package's name (this is policy)."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:217
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)."
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
#, no-wrap
msgid ""
"<replaceable>package-name</replaceable> is a "
"<replaceable>synopsis</replaceable>."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:233
msgid "Alternatively, it might make sense to think of it as"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:236
#, no-wrap
msgid ""
"<replaceable>package-name</replaceable> is "
"<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)"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:242
#, no-wrap
msgid ""
"<replaceable>package-name</replaceable> are "
"<replaceable>synopsis</replaceable>."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:245
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."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:252
msgid "The long description"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:254
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 "
"needed to let the user decide whether to install the package.  Assume that "
"the user has already read the package synopsis."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:260
msgid "The long description should consist of full and complete sentences."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:263
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 "
"accomplish? It is important to describe this in a non-technical way, unless "
"of course the audience for the package is necessarily technical."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:269
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 "
"outstanding features and deficiencies are there compared to other packages "
"(e.g., if you need X, use Y instead)? Is this package related to other "
"packages in some way that is not handled by the package manager (e.g., this "
"is the client for the foo server)?"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:277
msgid ""
"Be careful to avoid spelling and grammar mistakes.  Ensure that you "
"spell-check it.  Both <command>ispell</command> and "
"<command>aspell</command> have special modes for checking "
"<filename>debian/control</filename> files:"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:282
#, no-wrap
msgid "ispell -d american -g debian/control"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:285
#, no-wrap
msgid "aspell -d en -D -c debian/control"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:288
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
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
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
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
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."
msgstr ""

# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:319
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
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>
#: 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."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:362
msgid "Version Control System location"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:364
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"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:370
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
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-*"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:384
msgid ""
"Value of this field should be a string identifying unequivocally the "
"location of the Version Control System repository used to maintain the given "
"package, if available.  <literal>*</literal> identify the Version Control "
"System; currently the following systems are supported by the package "
"tracking system: <literal>arch</literal>, <literal>bzr</literal> (Bazaar), "
"<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>, "
"<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone), "
"<literal>svn</literal> (Subversion).  It is allowed to specify different VCS "
"fields for the same package: they will all be shown in the PTS web "
"interface."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:395
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 "
"from the VCS sources.  Other uses of this information might include "
"automatic building of the latest VCS version of the given package.  To this "
"end the location pointed to by the field should better be version agnostic "
"and point to the main branch (for VCSs supporting such a concept).  Also, "
"the location pointed to should be accessible to the final user; fulfilling "
"this requirement might imply pointing to an anonymous access of the "
"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
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."
msgstr ""

# type: Content of: <chapter><section><section><section><screen>
#: best-pkging-practices.dbk:414
#, no-wrap
msgid ""
"Source: vim\n"
"  Section: editors\n"
"  Priority: optional\n"
"  &lt;snip&gt;\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"
msgstr ""

# type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:428
msgid "Best practices for <filename>debian/changelog</filename>"
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:430
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
msgid "Writing useful changelog entries"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:437
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
msgid ""
"Focus on <emphasis>what</emphasis> was changed — who, how and when are "
"usually less important.  Having said that, remember to politely attribute "
"people who have provided notable help in making the package (e.g., those who "
"have sent in patches)."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:448
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 "
"terse if you have undertaken a major change.  Be especially clear if there "
"are changes that affect the behaviour of the program.  For further "
"explanations, use the <filename>README.Debian</filename> file."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:455
msgid ""
"Use common English so that the majority of readers can comprehend it.  Avoid "
"abbreviations, tech-speak and jargon when explaining changes that close "
"bugs, especially for bugs filed by users that did not strike you as "
"particularly technically savvy.  Be polite, don't swear."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:461
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 "
"and every last one of the changed files, especially if the change was small "
"or repetitive.  You may use wildcards."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:467
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
msgid "Common misconceptions about changelog entries"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:476
msgid ""
"The changelog entries should <emphasis role=\"strong\">not</emphasis> "
"document generic packaging issues (Hey, if you're looking for foo.conf, it's "
"in /etc/blah/.), since administrators and users are supposed to be at least "
"remotely acquainted with how such things are generally arranged on Debian "
"systems.  Do, however, mention if you change the location of a configuration "
"file."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:484
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\"/> ."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:489
msgid ""
"The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
"used for random discussion with bug reporters (I don't see segfaults when "
"starting foo with option bar; send in more info), general statements on "
"life, the universe and everything (sorry this upload took me so long, but I "
"caught the flu), or pleas for help (the bug list on this package is huge, "
"please lend me a hand).  Such things usually won't be noticed by their "
"target audience, but may annoy people who wish to read information about "
"actual changes in the package.  See <xref linkend=\"bug-answering\"/> for "
"more information on how to use the bug tracking system."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:500
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 "
"version tracking now, it is enough to keep the NMUed changelog entries and "
"just mention this fact in your own changelog entry."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:508
msgid "Common errors in changelog entries"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:510
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
#, no-wrap
msgid "* Fixed all outstanding bugs."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:517
msgid "This doesn't tell readers anything too useful, obviously."
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:520
#, no-wrap
msgid "* Applied patch from Jane Random."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:523
msgid "What was the patch about?"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:526
#, no-wrap
msgid "* Late night install target overhaul."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:529
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
#, no-wrap
msgid "* Fix vsync FU w/ ancient CRTs."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:536
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
#, no-wrap
msgid "* This is not a bug, closes: #nnnnnn."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:543
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
#, no-wrap
msgid "* Has been fixed for ages, but I forgot to close; closes: #54321."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:551
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 "
"no need to touch the changelog file, presuming the description of the fix is "
"already in (this applies to the fixes by the upstream authors/maintainers as "
"well, you don't have to track bugs that they fixed ages ago in your "
"changelog)."
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:558
#, no-wrap
msgid "* Closes: #12345, #12346, #15432"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:561
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"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:569
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 "
"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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:578
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:"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:586
#, no-wrap
msgid ""
"cron (3.0pl1-74) unstable; urgency=low\n"
"\n"
"    The checksecurity script is no longer included with the cron package:\n"
"    it now has its own package, checksecurity. If you liked the\n"
"    functionality provided with that script, please install the new\n"
"    package.\n"
"\n"
" -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 "
"-0500"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:596
msgid ""
"The NEWS.Debian file is installed as "
"/usr/share/doc/&lt;package&gt;/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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:602
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!"
msgstr ""

# type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:623
msgid "Best practices for maintainer scripts"
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:625
msgid ""
"Maintainer scripts include the files <filename>debian/postinst</filename>, "
"<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
"<filename>debian/postrm</filename>.  These scripts take care of any package "
"installation or deinstallation setup which isn't handled merely by the "
"creation or removal of files and directories.  The following instructions "
"supplement the <ulink url=\"&url-debian-policy;\">Debian Policy</ulink>."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:633
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
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
msgid ""
"All prompting or interactive configuration should be kept to a minimum.  "
"When it is necessary, you should use the <systemitem "
"role=\"package\">debconf</systemitem> package for the interface.  Remember "
"that prompting in any case can only be in the <literal>configure</literal> "
"stage of the <filename>postinst</filename> script."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:649
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 "
"maintainer script must have a bash shebang line.  POSIX shell or Bash are "
"preferred to Perl, since they enable <systemitem "
"role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:656
msgid ""
"If you change your maintainer scripts, be sure to test package removal, "
"double installation, and purging.  Be sure that a purged package is "
"completely gone, that is, it must remove any files created, directly or "
"indirectly, in any maintainer script."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:662
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
#, no-wrap
msgid "if [ -x /usr/sbin/install-docs ]; then ..."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:667
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
msgid ""
"You can use this function to search <literal>$PATH</literal> 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
msgid ""
"While <command>which</command> is an acceptable alternative, since it is "
"from the required <systemitem role=\"package\">debianutils</systemitem> "
"package, it's not on the root partition.  That is, it's in "
"<filename>/usr/bin</filename> rather than <filename>/bin</filename>, so one "
"can't use it in scripts which are run before the <filename>/usr</filename> "
"partition is mounted.  Most scripts won't have this problem, though."
msgstr ""

# type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:689
msgid ""
"Configuration management with <systemitem "
"role=\"package\">debconf</systemitem>"
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:691
msgid ""
"<systemitem role=\"package\">Debconf</systemitem> is a configuration "
"management system which can be used by all the various packaging scripts "
"(<filename>postinst</filename> mainly) to request feedback from the user "
"concerning how to configure the package.  Direct user interactions must now "
"be avoided in favor of <systemitem role=\"package\">debconf</systemitem> "
"interaction.  This will enable non-interactive installations in the future."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:699
msgid ""
"Debconf is a great tool but it is often poorly used.  Many common mistakes "
"are listed in the <citerefentry> "
"<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum> "
"</citerefentry> man page.  It is something that you must read if you decide "
"to use debconf.  Also, we document some best practices here."
msgstr ""

# type: Content of: <chapter><section><para>
#: best-pkging-practices.dbk:706
msgid ""
"These guidelines include some writing style and typography recommendations, "
"general considerations about debconf usage as well as more specific "
"recommendations for some parts of the distribution (the installation system "
"for instance)."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:712
msgid "Do not abuse debconf"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:714
msgid ""
"Since debconf appeared in Debian, it has been widely abused and several "
"criticisms received by the Debian distribution come from debconf abuse with "
"the need of answering a wide bunch of questions before getting any little "
"thing installed."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:720
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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:726
msgid ""
"Carefully choose the questions priorities in maintainer scripts.  See "
"<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
"<manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most "
"questions should use medium and low priorities."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:734
msgid "General recommendations for authors and translators"
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:736
msgid "Write correct English"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:738
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
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
msgid ""
"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
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 "
"them, try to explain them (use the extended description).  When doing so, "
"try to balance between verbosity and simplicity."
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:758
msgid "Be kind to translators"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:760
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
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)."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:770
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 "
"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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:779
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:784
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><para>
#: best-pkging-practices.dbk:789
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."
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:798
msgid "Unfuzzy complete translations when correcting typos and spelling"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:800
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:806
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
msgid ""
"To <emphasis role=\"strong\">unfuzzy</emphasis> translations, you can "
"proceed the following way:"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:816
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><programlisting>
#: best-pkging-practices.dbk:820
#, no-wrap
msgid ""
"for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null\n"
"--statistics $i; done"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:825
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
msgid ""
"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)"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:839
msgid ""
"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:"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
#: best-pkging-practices.dbk:847
#, 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
msgid ""
"move back to debian/po 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"
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:863
msgid "Do not make assumptions about interfaces"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:865
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:870
msgid ""
"String templates should also avoid mentioning the default values in their "
"description.  First, because this is redundant with the values seen by the "
"users.  Also, because these default values may be different from the "
"maintainer choices (for instance, when the debconf database was preseeded)."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:876
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
msgid "Do not use first person"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:884
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 ...."
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:894
msgid "Be gender neutral"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:896
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
msgid "Templates fields definition"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:906
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
msgid "Type"
msgstr ""

# type: Content of: <chapter><section><section><section><section><title>
#: best-pkging-practices.dbk:913
msgid "string:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:915
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:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:922
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:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:931
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:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:939
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"
msgstr ""

# type: Content of: <chapter><section><section><section><section><title>
#: best-pkging-practices.dbk:946
msgid "multiselect:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:948
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:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:956
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 "
"the user really should see, since debconf will go to great pains to make "
"sure the user sees it; halting the install for them to press a key, and even "
"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:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:967
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:"
msgstr ""

# type: Content of: <chapter><section><section><section><section><para>
#: best-pkging-practices.dbk:974
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
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
msgid "Description: short and extended description"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:989
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
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 "
"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
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 "
"asks for it or even do not show it at all.  Avoid things like What do you "
"want to do?"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1005
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
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 "
"more.  Post to debian-devel.  Ask for help.  Take a writing class! That "
"extended description is important.  If after all that you still can't come "
"up with anything, leave it blank."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1016
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
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 "
"classical dialog interface, people will need to scroll, and lot of people "
"just don't do that."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1027
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
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
msgid "Choices"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1039
msgid ""
"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
msgid "Default"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1048
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
msgid "Templates fields specific style guide"
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:1059
msgid "Type field"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1061
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
msgid "Description field"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1069
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
msgid "String/password templates"
msgstr ""

# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1077
msgid ""
"The short description is a prompt and <emphasis "
"role=\"strong\">not</emphasis> a title.  Avoid question style prompts (IP "
"Address?) in favour of opened prompts (IP address:).  The use of colons is "
"recommended."
msgstr ""

# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1084
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 "
"question again using longer words.  Use complete sentences.  Terse writing "
"style is strongly discouraged."
msgstr ""

# type: Content of: <chapter><section><section><section><section><title>
#: best-pkging-practices.dbk:1094
msgid "Boolean templates"
msgstr ""

# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1098
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)"
msgstr ""

# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1106
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
msgid "Select/Multiselect"
msgstr ""

# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1118
msgid ""
"The short description is a prompt and <emphasis "
"role=\"strong\">not</emphasis> a title.  Do <emphasis "
"role=\"strong\">not</emphasis> use useless Please choose...  constructions.  "
"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
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 "
"than one of the available choices, if the template is a multiselect one "
"(although the interface often makes this clear)."
msgstr ""

# type: Content of: <chapter><section><section><section><section><title>
#: best-pkging-practices.dbk:1136
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*."
msgstr ""

# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1145
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
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."
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:1166
msgid "Choices field"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1168
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
msgid "Default field"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1177
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1182
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1188
msgid "Example, taken from the geneweb package templates:"
msgstr ""

# type: Content of: <chapter><section><section><section><screen>
#: best-pkging-practices.dbk:1191
#, no-wrap
msgid ""
"Template: geneweb/lang\n"
"Type: select\n"
"__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech "
"(cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), "
"Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian "
"(it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian "
"(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"
"# 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:"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1202
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
msgid ""
"The comments are needed as the DefaultChoice 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
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
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1224
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> "
"<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
"</citerefentry>)."
msgstr ""

# type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:1236
msgid "Internationalization"
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:1238
msgid "Handling debconf translations"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1240
msgid ""
"Like porters, translators have a difficult task.  They work on many packages "
"and must collaborate with many different maintainers.  Moreover, most of the "
"time, they are not native English speakers, so you may need to be "
"particularly patient with them."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1246
msgid ""
"The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
"packages configuration easier for maintainers and for users.  Originally, "
"translation of debconf templates was handled with "
"<command>debconf-mergetemplate</command>.  However, that technique is now "
"deprecated; the best way to accomplish <systemitem "
"role=\"package\">debconf</systemitem> internationalization is by using the "
"<systemitem role=\"package\">po-debconf</systemitem> package.  This method "
"is easier both for maintainer and translators; transition scripts are "
"provided."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1256
msgid ""
"Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
"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 "
"<command>debconf-updatepo</command>, the translation is marked as needing "
"attention from the translators.  Then, at build time, the "
"<command>dh_installdebconf</command> program takes care of all the needed "
"magic to add the template along with the up-to-date translations into the "
"binary packages.  Refer to the <citerefentry> "
"<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
"</citerefentry> manual page for details."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:1272
msgid "Internationalized documentation"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1274
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
msgid ""
"If you maintain documentation of any size, its 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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1293
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 "
"file which is included by all the different translations.  This makes it "
"much easier, for instance, to keep URLs up to date across multiple files."
msgstr ""

# type: Content of: <chapter><section><title>
#: best-pkging-practices.dbk:1303
msgid "Common packaging situations"
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:1314
msgid "Packages using <command>autoconf</command>/<command>automake</command>"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1316
msgid ""
"Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
"<filename>config.guess</filename> files up to date is critical for porters, "
"especially on more volatile architectures.  Some very good packaging "
"practices for any package using <command>autoconf</command> and/or "
"<command>automake</command> have been synthesized in &file-bpp-autotools; "
"from the <systemitem role=\"package\">autotools-dev</systemitem> package.  "
"You're strongly encouraged to read this file and to follow the given "
"recommendations."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:1328
msgid "Libraries"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1330
msgid ""
"Libraries are always difficult to package for various reasons.  The policy "
"imposes many constraints to ease their maintenance and to make sure upgrades "
"are as simple as possible when a new upstream version comes out.  Breakage "
"in a library can result in dozens of dependent packages breaking."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1336
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
msgid "Documentation"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1345
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
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
msgid ""
"Policy specifies that documentation should be shipped in HTML format.  We "
"also recommend shipping documentation in PDF and plain text format if "
"convenient and if output of reasonable quality is possible.  However, it is "
"generally not appropriate to ship plain text versions of documentation whose "
"source format is HTML."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1362
msgid ""
"Major shipped manuals should register themselves with <systemitem "
"role=\"package\">doc-base</systemitem> on installation.  See the <systemitem "
"role=\"package\">doc-base</systemitem> package documentation for more "
"information."
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:1370
msgid "Specific types of packages"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1372
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
msgid ""
"Perl related packages have a <ulink url=\"&url-perl-policy;\">Perl "
"policy</ulink>, some examples of packages following that policy are "
"<systemitem role=\"package\">libdbd-pg-perl</systemitem> (binary perl "
"module) or <systemitem role=\"package\">libmldbm-perl</systemitem> (arch "
"independent perl module)."
msgstr ""

# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1387
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
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
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
msgid ""
"Ocaml related packages have their own policy, found in &file-ocaml-policy; "
"from the <systemitem role=\"package\">ocaml</systemitem> package.  A good "
"example is the <systemitem role=\"package\">camlzip</systemitem> source "
"package."
msgstr ""

# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
#: best-pkging-practices.dbk:1416
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
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
msgid "Architecture-independent data"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1454
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, "
"wallpaper patterns, or other graphic files.  If the size of this data is "
"negligible compared to the size of the rest of the package, it's probably "
"best to keep it all in a single package."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1461
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
msgid "Needing a certain locale during build"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1475
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
msgid ""
"If you set <varname>LOCPATH</varname> to the equivalent of "
"<filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the "
"name of the locale you generate, you should get what you want without being "
"root.  Something like this:"
msgstr ""

# type: Content of: <chapter><section><section><screen>
#: best-pkging-practices.dbk:1484
#, no-wrap
msgid ""
"LOCALE_PATH=debian/tmpdir/usr/lib/locale\n"
"LOCALE_NAME=en_IN\n"
"LOCALE_CHARSET=UTF-8\n"
"\n"
"mkdir -p $LOCALE_PATH\n"
"localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET "
"$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
"\n"
"# Using the locale\n"
"LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date"
msgstr ""

# type: Content of: <chapter><section><section><title>
#: best-pkging-practices.dbk:1497
msgid "Make transition packages deborphan compliant"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1499
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 "
"on them.  The default operation is to search only within the libs and "
"oldlibs sections, to hunt down unused libraries.  But when passed the right "
"argument, it tries to catch other useless packages."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1506
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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1512
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: "
"<command>apt-cache search .|grep dummy</command> or <command>apt-cache "
"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"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1522
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
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
msgid ""
"We cannot prevent upstream authors from changing the tarball they distribute "
"without also incrementing the version number, so there can be no guarantee "
"that a pristine tarball is identical to what upstream "
"<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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1540
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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1548
msgid ""
"There is no universally accepted guidelines that upstream authors follow "
"regarding to the directory structure inside their tarball, but "
"<command>dpkg-source</command> is nevertheless able to deal with most "
"upstream tarballs as pristine source.  Its strategy is equivalent to the "
"following:"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:1556
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
#, no-wrap
msgid ""
"zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar "
"xf -"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:1564
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>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.  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
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>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>."
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:1584
msgid "Repackaged upstream source"
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1586
msgid ""
"You <emphasis role=\"strong\">should</emphasis> upload packages with a "
"pristine source tarball if possible, but there are various reasons why it "
"might not be possible.  This is the case if upstream does not distribute the "
"source as gzipped tar at all, or if upstream's tarball contains "
"non-DFSG-free material that you must remove before uploading."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1593
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>&lt;upstream-version&gt;</literal> and "
"<literal>&lt;debian-revision&gt;</literal>."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1602
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 "
"<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"
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:1616
msgid ""
"<emphasis role=\"strong\">must</emphasis> contain detailed information how "
"the repackaged source was obtained, and how this can be reproduced in the "
"<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>."
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
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."
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:1642
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."
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:1651
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 "
"mirror rather than trying to locate a canonical upstream distribution "
"point)."
msgstr ""

# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
#: best-pkging-practices.dbk:1658
msgid ""
"<emphasis role=\"strong\">should</emphasis> use "
"<literal>&lt;packagename&gt;-&lt;upstream-version&gt;.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."
msgstr ""

# type: Content of: <chapter><section><section><section><para>
#: best-pkging-practices.dbk:1671
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."
msgstr ""

# type: Content of: <chapter><section><section><section><title>
#: best-pkging-practices.dbk:1677
msgid "Changing binary files in <literal>diff.gz</literal>"
msgstr ""

# type: Content of: <chapter><section><section><section><para><footnote>
#: best-pkging-practices.dbk:1679
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
msgid "Best practices for debug packages"
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1715
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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1723
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 "
"packages, since this can aid in debugging many programs linked to a "
"library.  In general, debug packages do not need to be added for all "
"programs; doing so would bloat the archive.  But if a maintainer finds that "
"users often need a debugging version of a program, it can be worthwhile to "
"make a debug package for it.  Programs that are core infrastructure, such as "
"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
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 "
"<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
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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1752
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."
msgstr ""

# type: Content of: <chapter><section><section><para>
#: best-pkging-practices.dbk:1759
msgid ""
"Note that the Debian 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
#, no-wrap
msgid "Depends: libfoo-dbg (= ${binary:Version})"
msgstr ""