#: best-pkging-practices.dbk:5 msgid "Best Packaging Practices" msgstr "" # type: Content of: <chapter><para> #: best-pkging-practices.dbk:7 msgid "" "Debian's quality is largely due to the <ulink " "url=\"http://www.debian.org/doc/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:16 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:22 msgid "Best practices for <filename>debian/rules</filename>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:24 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:30 msgid "Helper scripts" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:32 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:43 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:50 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:64 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:77 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=\"http://arch.debian.org/arch/private/srivasta/\"></ulink>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:86 msgid "Separating your patches into multiple files" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:88 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:97 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:107 msgid "" "<command>dbs</command> is one of the more popular approaches to this. It " "does all of the above, and provides a facility for creating new and updating " "old patches. See the package <systemitem role=\"package\">dbs</systemitem> " "for more information and <systemitem role=\"package\">hello-dbs</systemitem> " "for an example." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:114 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:122 msgid "Multiple binary packages" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:124 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:131 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:140 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:150 msgid "Best practices for <filename>debian/control</filename>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:152 msgid "" "The following practices are relevant to the " "<filename>debian/control</filename> file. They supplement the <ulink " "url=\"http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions\">Policy " "on package descriptions</ulink>." msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:158 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:167 msgid "General guidelines for package descriptions" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:169 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:176 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:182 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:189 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:194 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:201 msgid "" "If you are having problems writing your description, you may wish to send it " "along to <email>debian-l10n-english@lists.debian.org</email> and request " "feedback." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:208 msgid "The package synopsis, or short description" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:210 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:214 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:223 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:227 #, no-wrap msgid "" "<replaceable>package-name</replaceable> is a " "<replaceable>synopsis</replaceable>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:230 msgid "Alternatively, it might make sense to think of it as" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:233 #, no-wrap msgid "" "<replaceable>package-name</replaceable> is " "<replaceable>synopsis</replaceable>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:236 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:239 #, no-wrap msgid "" "<replaceable>package-name</replaceable> are " "<replaceable>synopsis</replaceable>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:242 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:249 msgid "The long description" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:251 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:257 msgid "The long description should consist of full and complete sentences." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:260 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:266 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:274 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:279 #, no-wrap msgid "-d american -g debian/control" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:282 #, no-wrap msgid "-d en -D -c debian/control" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:285 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:290 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:296 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:303 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:309 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:316 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:325 msgid "Upstream home page" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:327 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:332 #, no-wrap msgid "" ".\n" " Homepage: http://some-project.some-place.org/" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:336 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=\"http://packages.debian.org/unstable/web/wml\"></ulink>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:341 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:344 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.debian.org</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.debian.org</filename> to " "parse it correctly." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:355 msgid "Version Control System location" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:357 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:361 msgid "XS-Vcs-Browser" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:363 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:368 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:375 msgid "XS-Vcs-*" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:377 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:388 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:399 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:407 #, no-wrap msgid "" "Source: vim\n" " Section: editors\n" " Priority: optional\n" " <snip>\n" " XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n" " XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim" msgstr "" # type: Content of: <chapter><section><title> #: best-pkging-practices.dbk:421 msgid "Best practices for <filename>debian/changelog</filename>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:423 msgid "" "The following practices supplement the <ulink " "url=\"http://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs\">Policy " "on changelog files</ulink>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:428 msgid "Writing useful changelog entries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:430 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:435 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:441 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:448 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:454 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:460 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:467 msgid "Common misconceptions about changelog entries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:469 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:477 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:482 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:493 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:501 msgid "Common errors in changelog entries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:503 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:507 #, no-wrap msgid "* Fixed all outstanding bugs." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:510 msgid "This doesn't tell readers anything too useful, obviously." msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:513 #, no-wrap msgid "* Applied patch from Jane Random." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:516 msgid "What was the patch about?" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:519 #, no-wrap msgid "* Late night install target overhaul." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:522 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:526 #, no-wrap msgid "* Fix vsync FU w/ ancient CRTs." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:529 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:533 #, no-wrap msgid "* This is not a bug, closes: #nnnnnn." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:536 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:541 #, 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:544 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:551 #, no-wrap msgid "* Closes: #12345, #12346, #15432" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:554 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:560 msgid "Supplementing changelogs with NEWS.Debian files" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:562 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:571 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:579 #, no-wrap msgid "" "(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 <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 " "-0500" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:589 msgid "" "The NEWS.Debian file is installed as " "/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and always " "has that name even in Debian native packages. If you use debhelper, " "dh_installchangelogs will install debian/NEWS files for you." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:595 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:605 msgid "Best practices for maintainer scripts" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:607 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=\"http://www.debian.org/doc/debian-policy/\">Debian Policy</ulink>." msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:615 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:620 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:624 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:631 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:638 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:644 msgid "" "If you need to check for the existence of a command, you should use " "something like" msgstr "" # type: Content of: <chapter><section><screen> #: best-pkging-practices.dbk:648 #, no-wrap msgid "[ -x /usr/sbin/install-docs ]; then ..." msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:651 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><screen> #: best-pkging-practices.dbk:655 #, no-wrap msgid "" "() {\n" " OLDIFS=$IFS\n" " IFS=:\n" " for p in $PATH; do\n" " if [ -x $p/$* ]; then\n" " IFS=$OLDIFS\n" " return 0\n" " fi\n" " done\n" " IFS=$OLDIFS\n" " return 1\n" "}" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:669 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:676 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:686 msgid "" "Configuration management with <systemitem " "role=\"package\">debconf</systemitem>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:688 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:696 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:703 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:709 msgid "Do not abuse debconf" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:711 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:717 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:723 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:731 msgid "General recommendations for authors and translators" msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:733 msgid "Write correct English" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:735 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:739 msgid "" "Please use (and abuse) <email>debian-l10n-english@lists.debian.org</email> " "mailing list. Have your templates proofread." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:743 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:747 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:755 msgid "Be kind to translators" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:757 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:762 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:767 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:776 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:781 msgid "" "If in doubt, you may also contact the translation team for a given language " "(debian-l10n-xxxxx@lists.debian.org), or the " "<email>debian-i18n@lists.debian.org</email> mailing list." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:786 msgid "" "Calls for translations posted to <email>debian-i18n@lists.debian.org</email> " "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:795 msgid "Unfuzzy complete translations when correcting typos and spelling" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:797 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:803 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:807 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:813 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><screen> #: best-pkging-practices.dbk:818 #, no-wrap msgid "" "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:824 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:831 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:838 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:844 msgid "use the following command:" msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><screen> #: best-pkging-practices.dbk:847 #, no-wrap msgid "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:852 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:857 msgid "run <command>debconf-updatepo</command> again" msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:864 msgid "Do not make assumptions about interfaces" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:866 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:871 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:877 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:883 msgid "Do not use first person" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:885 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:895 msgid "Be gender neutral" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:897 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:905 msgid "Templates fields definition" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:907 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:912 msgid "Type" msgstr "" # type: Content of: <chapter><section><section><section><section><title> #: best-pkging-practices.dbk:914 msgid "string:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:916 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:921 msgid "password:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:923 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:930 msgid "boolean:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:932 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:938 msgid "select:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:940 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:947 msgid "multiselect:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:949 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:955 msgid "note:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:957 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:966 msgid "text:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:968 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:973 msgid "error:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:975 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:980 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:988 msgid "Description: short and extended description" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:990 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:994 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:1000 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:1006 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:1010 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:1017 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:1022 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:1028 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:1032 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:1038 msgid "Choices" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1040 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:1047 msgid "Default" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1049 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:1058 msgid "Templates fields specific style guide" msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:1060 msgid "Type field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1062 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:1068 msgid "Description field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1070 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:1074 msgid "String/password templates" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1078 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:1085 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:1095 msgid "Boolean templates" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1099 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:1107 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:1115 msgid "Select/Multiselect" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1119 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:1127 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:1137 msgid "Notes" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1141 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:1146 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:1152 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:1167 msgid "Choices field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1169 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:1176 best-pkging-practices.dbk:1214 msgid "Default field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1178 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:1183 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:1189 msgid "Example, taken from the geneweb package templates:" msgstr "" # type: Content of: <chapter><section><section><section><screen> #: best-pkging-practices.dbk:1192 #, no-wrap msgid "" ": 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:1203 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:1208 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:1216 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:1220 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:1225 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:1237 msgid "Internationalization" msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1239 msgid "Handling debconf translations" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1241 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:1247 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:1257 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:1273 msgid "Internationalized documentation" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1275 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:1280 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=\"http://cvs.debian.org/boot-floppies/documentation/doc-check?rev=HEAD\\|[amp " "]\\|content-type=text/vnd.viewcvs-markup\">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:1295 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:1305 msgid "Common packaging situations" msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1307 msgid "Packages using <command>autoconf</command>/<command>automake</command>" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1309 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 " "<filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename> 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:1321 msgid "Libraries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1323 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:1329 msgid "" "Good practices for library packaging have been grouped in <ulink " "url=\"http://www.netfort.gr.jp/~dancer/column/libpkg-guide/\">the library " "packaging guide</ulink>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1336 msgid "Documentation" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1338 msgid "" "Be sure to follow the <ulink " "url=\"http://www.debian.org/doc/debian-policy/ch-docs.html\">Policy on " "documentation</ulink>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1343 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:1348 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:1355 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:1363 msgid "Specific types of packages" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1365 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:1371 msgid "" "Perl related packages have a <ulink " "url=\"http://www.debian.org/doc/packaging-manuals/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:1380 msgid "" "Python related packages have their python policy; see " "<filename>/usr/share/doc/python/python-policy.txt.gz</filename> in the " "<systemitem role=\"package\">python</systemitem> package." msgstr "" # type: Content of: <chapter><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1387 msgid "" "Emacs related packages have the <ulink " "url=\"http://www.debian.org/doc/packaging-manuals/debian-emacs-policy\">emacs " "policy</ulink>." msgstr "" # type: Content of: <chapter><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1394 msgid "" "Java related packages have their <ulink " "url=\"http://www.debian.org/doc/packaging-manuals/java-policy/\">java " "policy</ulink>." msgstr "" # type: Content of: <chapter><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1401 msgid "" "Ocaml related packages have their own policy, found in " "<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename> 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:1409 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:1415 msgid "" "Lisp packages should register themselves with <systemitem " "role=\"package\">common-lisp-controller</systemitem>, about which see " "<filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1424 msgid "Architecture-independent data" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1426 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:1433 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:1445 msgid "Needing a certain locale during build" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1447 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:1451 msgid "" "If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL 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:1456 #, no-wrap msgid "" "=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:1469 msgid "Make transition packages deborphan compliant" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1471 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:1478 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:1484 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:" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:1488 #, no-wrap msgid "-cache search .|grep dummy" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1491 msgid "or" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:1494 #, no-wrap msgid "-cache search .|grep transitional" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1497 msgid "." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1502 msgid "Best practices for <filename>orig.tar.gz</filename> files" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1504 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:1508 msgid "Pristine source" msgstr "" # type: Content of: <chapter><section><section><section><para><footnote> #: best-pkging-practices.dbk:1510 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:1512 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:1522 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:1530 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:1538 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:1541 #, no-wrap msgid "path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf -" msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1546 msgid "" "If, after this, the temporary directory contains nothing but one directory " "and no other files, <command>dpkg-source</command> renames that directory to " "<literal><packagename>-<upstream-version>(.orig)</literal>. The " "name of the top-level directory in the tarball does not matter, and is " "forgotten." msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1555 msgid "" "Otherwise, the upstream tarball must have been packaged without a common " "top-level directory (shame on the upstream author!). In this case, " "<command>dpkg-source</command> renames the temporary directory " "<emphasis>itself</emphasis> to " "<literal><packagename>-<upstream-version>(.orig)</literal>." msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:1566 msgid "Repackaged upstream source" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1568 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:1575 msgid "" "In these cases the developer must construct a suitable .orig.tar.gz file " "himself. We refer to such a tarball as a repackaged upstream source. Note " "that a repackaged upstream source is different from a Debian-native " "package. A repackaged source still comes with Debian-specific changes in a " "separate <literal>.diff.gz</literal> and still has a version number composed " "of <literal><upstream-version></literal> and " "<literal><debian-revision></literal>." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1584 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:1593 msgid "A repackaged .orig.tar.gz" msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1598 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=\"http://www.debian.org/doc/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:1610 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 "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para> #: best-pkging-practices.dbk:1612 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:1623 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:1632 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:1639 msgid "" "<emphasis role=\"strong\">should</emphasis> use " "<literal><packagename>-<upstream-version>.orig</literal> as the " "name of the top-level directory in its tarball. This makes it possible to " "distinguish pristine tarballs from repackaged ones." msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1647 msgid "" "<emphasis role=\"strong\">should</emphasis> be gzipped with maximal " "compression." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1652 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:1658 msgid "Changing binary files in <literal>diff.gz</literal>" msgstr "" # type: Content of: <chapter><section><section><section><para><footnote> #: best-pkging-practices.dbk:1660 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:1667 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><footnote><screen> #: best-pkging-practices.dbk:1673 #, no-wrap msgid "" "-file: perl -ne 'print(pack u, $$_);'\n" "$(file) > $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, " "$$_);'\n" "$(file).uuencoded > $(file)" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1675 msgid "" "</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:1680 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:1693 msgid "Best practices for debug packages" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1695 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:1703 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:1713 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:1725 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:1732 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:1739 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:1743 #, no-wrap msgid ": libfoo-dbg (= ${binary:Version})" msgstr ""

# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR Free Software Foundation, Inc. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "POT-Creation-Date: 2007-06-26 16:13+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: ENCODING" # type: Content of: #: best-pkging-practices.dbk:5 msgid "Best Packaging Practices" msgstr "" # type: Content of: <chapter><para> #: best-pkging-practices.dbk:7 msgid "" "Debian's quality is largely due to the <ulink " "url=\"http://www.debian.org/doc/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:16 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:22 msgid "Best practices for <filename>debian/rules</filename>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:24 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:30 msgid "Helper scripts" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:32 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:43 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:50 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:64 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:77 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=\"http://arch.debian.org/arch/private/srivasta/\"></ulink>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:86 msgid "Separating your patches into multiple files" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:88 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:97 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:107 msgid "" "<command>dbs</command> is one of the more popular approaches to this. It " "does all of the above, and provides a facility for creating new and updating " "old patches. See the package <systemitem role=\"package\">dbs</systemitem> " "for more information and <systemitem role=\"package\">hello-dbs</systemitem> " "for an example." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:114 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:122 msgid "Multiple binary packages" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:124 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:131 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:140 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:150 msgid "Best practices for <filename>debian/control</filename>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:152 msgid "" "The following practices are relevant to the " "<filename>debian/control</filename> file. They supplement the <ulink " "url=\"http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions\">Policy " "on package descriptions</ulink>." msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:158 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:167 msgid "General guidelines for package descriptions" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:169 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:176 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:182 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:189 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:194 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:201 msgid "" "If you are having problems writing your description, you may wish to send it " "along to <email>debian-l10n-english@lists.debian.org</email> and request " "feedback." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:208 msgid "The package synopsis, or short description" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:210 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:214 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:223 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:227 #, no-wrap msgid "" "<replaceable>package-name</replaceable> is a " "<replaceable>synopsis</replaceable>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:230 msgid "Alternatively, it might make sense to think of it as" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:233 #, no-wrap msgid "" "<replaceable>package-name</replaceable> is " "<replaceable>synopsis</replaceable>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:236 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:239 #, no-wrap msgid "" "<replaceable>package-name</replaceable> are " "<replaceable>synopsis</replaceable>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:242 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:249 msgid "The long description" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:251 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:257 msgid "The long description should consist of full and complete sentences." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:260 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:266 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:274 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:279 #, no-wrap msgid "-d american -g debian/control" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:282 #, no-wrap msgid "-d en -D -c debian/control" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:285 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:290 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:296 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:303 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:309 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:316 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:325 msgid "Upstream home page" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:327 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:332 #, no-wrap msgid "" ".\n" " Homepage: http://some-project.some-place.org/" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:336 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=\"http://packages.debian.org/unstable/web/wml\"></ulink>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:341 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:344 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.debian.org</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.debian.org</filename> to " "parse it correctly." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:355 msgid "Version Control System location" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:357 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:361 msgid "XS-Vcs-Browser" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:363 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:368 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:375 msgid "XS-Vcs-*" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:377 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:388 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:399 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:407 #, no-wrap msgid "" "Source: vim\n" " Section: editors\n" " Priority: optional\n" " <snip>\n" " XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n" " XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim" msgstr "" # type: Content of: <chapter><section><title> #: best-pkging-practices.dbk:421 msgid "Best practices for <filename>debian/changelog</filename>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:423 msgid "" "The following practices supplement the <ulink " "url=\"http://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs\">Policy " "on changelog files</ulink>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:428 msgid "Writing useful changelog entries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:430 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:435 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:441 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:448 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:454 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:460 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:467 msgid "Common misconceptions about changelog entries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:469 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:477 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:482 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:493 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:501 msgid "Common errors in changelog entries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:503 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:507 #, no-wrap msgid "* Fixed all outstanding bugs." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:510 msgid "This doesn't tell readers anything too useful, obviously." msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:513 #, no-wrap msgid "* Applied patch from Jane Random." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:516 msgid "What was the patch about?" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:519 #, no-wrap msgid "* Late night install target overhaul." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:522 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:526 #, no-wrap msgid "* Fix vsync FU w/ ancient CRTs." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:529 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:533 #, no-wrap msgid "* This is not a bug, closes: #nnnnnn." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:536 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:541 #, 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:544 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:551 #, no-wrap msgid "* Closes: #12345, #12346, #15432" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:554 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:560 msgid "Supplementing changelogs with NEWS.Debian files" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:562 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:571 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:579 #, no-wrap msgid "" "(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 <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 " "-0500" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:589 msgid "" "The NEWS.Debian file is installed as " "/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and always " "has that name even in Debian native packages. If you use debhelper, " "dh_installchangelogs will install debian/NEWS files for you." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:595 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:605 msgid "Best practices for maintainer scripts" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:607 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=\"http://www.debian.org/doc/debian-policy/\">Debian Policy</ulink>." msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:615 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:620 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:624 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:631 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:638 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:644 msgid "" "If you need to check for the existence of a command, you should use " "something like" msgstr "" # type: Content of: <chapter><section><screen> #: best-pkging-practices.dbk:648 #, no-wrap msgid "[ -x /usr/sbin/install-docs ]; then ..." msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:651 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><screen> #: best-pkging-practices.dbk:655 #, no-wrap msgid "" "() {\n" " OLDIFS=$IFS\n" " IFS=:\n" " for p in $PATH; do\n" " if [ -x $p/$* ]; then\n" " IFS=$OLDIFS\n" " return 0\n" " fi\n" " done\n" " IFS=$OLDIFS\n" " return 1\n" "}" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:669 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:676 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:686 msgid "" "Configuration management with <systemitem " "role=\"package\">debconf</systemitem>" msgstr "" # type: Content of: <chapter><section><para> #: best-pkging-practices.dbk:688 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:696 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:703 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:709 msgid "Do not abuse debconf" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:711 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:717 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:723 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:731 msgid "General recommendations for authors and translators" msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:733 msgid "Write correct English" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:735 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:739 msgid "" "Please use (and abuse) <email>debian-l10n-english@lists.debian.org</email> " "mailing list. Have your templates proofread." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:743 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:747 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:755 msgid "Be kind to translators" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:757 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:762 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:767 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:776 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:781 msgid "" "If in doubt, you may also contact the translation team for a given language " "(debian-l10n-xxxxx@lists.debian.org), or the " "<email>debian-i18n@lists.debian.org</email> mailing list." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:786 msgid "" "Calls for translations posted to <email>debian-i18n@lists.debian.org</email> " "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:795 msgid "Unfuzzy complete translations when correcting typos and spelling" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:797 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:803 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:807 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:813 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><screen> #: best-pkging-practices.dbk:818 #, no-wrap msgid "" "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:824 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:831 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:838 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:844 msgid "use the following command:" msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><screen> #: best-pkging-practices.dbk:847 #, no-wrap msgid "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:852 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:857 msgid "run <command>debconf-updatepo</command> again" msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:864 msgid "Do not make assumptions about interfaces" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:866 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:871 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:877 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:883 msgid "Do not use first person" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:885 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:895 msgid "Be gender neutral" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:897 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:905 msgid "Templates fields definition" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:907 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:912 msgid "Type" msgstr "" # type: Content of: <chapter><section><section><section><section><title> #: best-pkging-practices.dbk:914 msgid "string:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:916 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:921 msgid "password:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:923 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:930 msgid "boolean:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:932 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:938 msgid "select:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:940 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:947 msgid "multiselect:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:949 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:955 msgid "note:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:957 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:966 msgid "text:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:968 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:973 msgid "error:" msgstr "" # type: Content of: <chapter><section><section><section><section><para> #: best-pkging-practices.dbk:975 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:980 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:988 msgid "Description: short and extended description" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:990 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:994 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:1000 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:1006 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:1010 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:1017 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:1022 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:1028 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:1032 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:1038 msgid "Choices" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1040 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:1047 msgid "Default" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1049 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:1058 msgid "Templates fields specific style guide" msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:1060 msgid "Type field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1062 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:1068 msgid "Description field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1070 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:1074 msgid "String/password templates" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1078 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:1085 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:1095 msgid "Boolean templates" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1099 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:1107 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:1115 msgid "Select/Multiselect" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1119 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:1127 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:1137 msgid "Notes" msgstr "" # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1141 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:1146 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:1152 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:1167 msgid "Choices field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1169 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:1176 best-pkging-practices.dbk:1214 msgid "Default field" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1178 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:1183 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:1189 msgid "Example, taken from the geneweb package templates:" msgstr "" # type: Content of: <chapter><section><section><section><screen> #: best-pkging-practices.dbk:1192 #, no-wrap msgid "" ": 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:1203 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:1208 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:1216 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:1220 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:1225 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:1237 msgid "Internationalization" msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1239 msgid "Handling debconf translations" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1241 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:1247 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:1257 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:1273 msgid "Internationalized documentation" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1275 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:1280 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=\"http://cvs.debian.org/boot-floppies/documentation/doc-check?rev=HEAD\\|[amp " "]\\|content-type=text/vnd.viewcvs-markup\">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:1295 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:1305 msgid "Common packaging situations" msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1307 msgid "Packages using <command>autoconf</command>/<command>automake</command>" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1309 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 " "<filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename> 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:1321 msgid "Libraries" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1323 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:1329 msgid "" "Good practices for library packaging have been grouped in <ulink " "url=\"http://www.netfort.gr.jp/~dancer/column/libpkg-guide/\">the library " "packaging guide</ulink>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1336 msgid "Documentation" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1338 msgid "" "Be sure to follow the <ulink " "url=\"http://www.debian.org/doc/debian-policy/ch-docs.html\">Policy on " "documentation</ulink>." msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1343 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:1348 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:1355 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:1363 msgid "Specific types of packages" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1365 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:1371 msgid "" "Perl related packages have a <ulink " "url=\"http://www.debian.org/doc/packaging-manuals/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:1380 msgid "" "Python related packages have their python policy; see " "<filename>/usr/share/doc/python/python-policy.txt.gz</filename> in the " "<systemitem role=\"package\">python</systemitem> package." msgstr "" # type: Content of: <chapter><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1387 msgid "" "Emacs related packages have the <ulink " "url=\"http://www.debian.org/doc/packaging-manuals/debian-emacs-policy\">emacs " "policy</ulink>." msgstr "" # type: Content of: <chapter><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1394 msgid "" "Java related packages have their <ulink " "url=\"http://www.debian.org/doc/packaging-manuals/java-policy/\">java " "policy</ulink>." msgstr "" # type: Content of: <chapter><section><section><itemizedlist><listitem><para> #: best-pkging-practices.dbk:1401 msgid "" "Ocaml related packages have their own policy, found in " "<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename> 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:1409 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:1415 msgid "" "Lisp packages should register themselves with <systemitem " "role=\"package\">common-lisp-controller</systemitem>, about which see " "<filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1424 msgid "Architecture-independent data" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1426 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:1433 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:1445 msgid "Needing a certain locale during build" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1447 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:1451 msgid "" "If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL 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:1456 #, no-wrap msgid "" "=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:1469 msgid "Make transition packages deborphan compliant" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1471 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:1478 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:1484 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:" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:1488 #, no-wrap msgid "-cache search .|grep dummy" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1491 msgid "or" msgstr "" # type: Content of: <chapter><section><section><screen> #: best-pkging-practices.dbk:1494 #, no-wrap msgid "-cache search .|grep transitional" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1497 msgid "." msgstr "" # type: Content of: <chapter><section><section><title> #: best-pkging-practices.dbk:1502 msgid "Best practices for <filename>orig.tar.gz</filename> files" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1504 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:1508 msgid "Pristine source" msgstr "" # type: Content of: <chapter><section><section><section><para><footnote> #: best-pkging-practices.dbk:1510 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:1512 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:1522 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:1530 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:1538 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:1541 #, no-wrap msgid "path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf -" msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1546 msgid "" "If, after this, the temporary directory contains nothing but one directory " "and no other files, <command>dpkg-source</command> renames that directory to " "<literal><packagename>-<upstream-version>(.orig)</literal>. The " "name of the top-level directory in the tarball does not matter, and is " "forgotten." msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1555 msgid "" "Otherwise, the upstream tarball must have been packaged without a common " "top-level directory (shame on the upstream author!). In this case, " "<command>dpkg-source</command> renames the temporary directory " "<emphasis>itself</emphasis> to " "<literal><packagename>-<upstream-version>(.orig)</literal>." msgstr "" # type: Content of: <chapter><section><section><section><title> #: best-pkging-practices.dbk:1566 msgid "Repackaged upstream source" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1568 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:1575 msgid "" "In these cases the developer must construct a suitable .orig.tar.gz file " "himself. We refer to such a tarball as a repackaged upstream source. Note " "that a repackaged upstream source is different from a Debian-native " "package. A repackaged source still comes with Debian-specific changes in a " "separate <literal>.diff.gz</literal> and still has a version number composed " "of <literal><upstream-version></literal> and " "<literal><debian-revision></literal>." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1584 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:1593 msgid "A repackaged .orig.tar.gz" msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1598 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=\"http://www.debian.org/doc/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:1610 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 "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para> #: best-pkging-practices.dbk:1612 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:1623 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:1632 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:1639 msgid "" "<emphasis role=\"strong\">should</emphasis> use " "<literal><packagename>-<upstream-version>.orig</literal> as the " "name of the top-level directory in its tarball. This makes it possible to " "distinguish pristine tarballs from repackaged ones." msgstr "" # type: Content of: <chapter><section><section><section><orderedlist><listitem><para> #: best-pkging-practices.dbk:1647 msgid "" "<emphasis role=\"strong\">should</emphasis> be gzipped with maximal " "compression." msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1652 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:1658 msgid "Changing binary files in <literal>diff.gz</literal>" msgstr "" # type: Content of: <chapter><section><section><section><para><footnote> #: best-pkging-practices.dbk:1660 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:1667 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><footnote><screen> #: best-pkging-practices.dbk:1673 #, no-wrap msgid "" "-file: perl -ne 'print(pack u, $$_);'\n" "$(file) > $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, " "$$_);'\n" "$(file).uuencoded > $(file)" msgstr "" # type: Content of: <chapter><section><section><section><para> #: best-pkging-practices.dbk:1675 msgid "" "</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:1680 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:1693 msgid "Best practices for debug packages" msgstr "" # type: Content of: <chapter><section><section><para> #: best-pkging-practices.dbk:1695 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:1703 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:1713 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:1725 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:1732 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:1739 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:1743 #, no-wrap msgid ": libfoo-dbg (= ${binary:Version})" msgstr ""