chiark / gitweb /
Now everything builds. Translators needed!
[developers-reference.git] / po4a / po / best-pkging-practices.pot
1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
4
5 #, fuzzy
6 msgid ""
7 msgstr ""
8 "Project-Id-Version: PACKAGE VERSION\n"
9 "POT-Creation-Date: 2007-07-01 21:01+0000\n"
10 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
11 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
12 "Language-Team: LANGUAGE <LL@li.org>\n"
13 "MIME-Version: 1.0\n"
14 "Content-Type: text/plain; charset=utf-8\n"
15 "Content-Transfer-Encoding: ENCODING"
16
17 # type: Content of: <chapter><title>
18 #: best-pkging-practices.dbk:7
19 msgid "Best Packaging Practices"
20 msgstr ""
21
22 # type: Content of: <chapter><para>
23 #: best-pkging-practices.dbk:9
24 msgid ""
25 "Debian's quality is largely due to the <ulink "
26 "url=\"&url-debian-policy;\">Debian Policy</ulink>, which defines explicit "
27 "baseline requirements which all Debian packages must fulfill.  Yet there is "
28 "also a shared history of experience which goes beyond the Debian Policy, an "
29 "accumulation of years of experience in packaging.  Many very talented people "
30 "have created great tools, tools which help you, the Debian maintainer, "
31 "create and maintain excellent packages."
32 msgstr ""
33
34 # type: Content of: <chapter><para>
35 #: best-pkging-practices.dbk:18
36 msgid ""
37 "This chapter provides some best practices for Debian developers.  All "
38 "recommendations are merely that, and are not requirements or policy.  These "
39 "are just some subjective hints, advice and pointers collected from Debian "
40 "developers.  Feel free to pick and choose whatever works best for you."
41 msgstr ""
42
43 # type: Content of: <chapter><section><title>
44 #: best-pkging-practices.dbk:24
45 msgid "Best practices for <filename>debian/rules</filename>"
46 msgstr ""
47
48 # type: Content of: <chapter><section><para>
49 #: best-pkging-practices.dbk:26
50 msgid ""
51 "The following recommendations apply to the <filename>debian/rules</filename> "
52 "file.  Since <filename>debian/rules</filename> controls the build process "
53 "and selects the files which go into the package (directly or indirectly), "
54 "it's usually the file maintainers spend the most time on."
55 msgstr ""
56
57 # type: Content of: <chapter><section><section><title>
58 #: best-pkging-practices.dbk:32
59 msgid "Helper scripts"
60 msgstr ""
61
62 # type: Content of: <chapter><section><section><para>
63 #: best-pkging-practices.dbk:34
64 msgid ""
65 "The rationale for using helper scripts in <filename>debian/rules</filename> "
66 "is that they let maintainers use and share common logic among many "
67 "packages.  Take for instance the question of installing menu entries: you "
68 "need to put the file into <filename>/usr/lib/menu</filename> (or "
69 "<filename>/usr/lib/menu</filename> for executable binary menufiles, if this "
70 "is needed), and add commands to the maintainer scripts to register and "
71 "unregister the menu entries.  Since this is a very common thing for packages "
72 "to do, why should each maintainer rewrite all this on their own, sometimes "
73 "with bugs? Also, supposing the menu directory changed, every package would "
74 "have to be changed."
75 msgstr ""
76
77 # type: Content of: <chapter><section><section><para>
78 #: best-pkging-practices.dbk:45
79 msgid ""
80 "Helper scripts take care of these issues.  Assuming you comply with the "
81 "conventions expected by the helper script, the helper takes care of all the "
82 "details.  Changes in policy can be made in the helper script; then packages "
83 "just need to be rebuilt with the new version of the helper and no other "
84 "changes."
85 msgstr ""
86
87 # type: Content of: <chapter><section><section><para>
88 #: best-pkging-practices.dbk:52
89 msgid ""
90 "<xref linkend=\"tools\"/> contains a couple of different helpers.  The most "
91 "common and best (in our opinion) helper system is <systemitem "
92 "role=\"package\">debhelper</systemitem>.  Previous helper systems, such as "
93 "<systemitem role=\"package\">debmake</systemitem>, were monolithic: you "
94 "couldn't pick and choose which part of the helper you found useful, but had "
95 "to use the helper to do everything.  <systemitem "
96 "role=\"package\">debhelper</systemitem>, however, is a number of separate "
97 "little <command>dh_*</command> programs.  For instance, "
98 "<command>dh_installman</command> installs and compresses man pages, "
99 "<command>dh_installmenu</command> installs menu files, and so on.  Thus, it "
100 "offers enough flexibility to be able to use the little helper scripts, where "
101 "useful, in conjunction with hand-crafted commands in "
102 "<filename>debian/rules</filename>."
103 msgstr ""
104
105 # type: Content of: <chapter><section><section><para>
106 #: best-pkging-practices.dbk:66
107 msgid ""
108 "You can get started with <systemitem role=\"package\">debhelper</systemitem> "
109 "by reading <citerefentry> <refentrytitle>debhelper</refentrytitle> "
110 "<manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that "
111 "come with the package.  <command>dh_make</command>, from the <systemitem "
112 "role=\"package\">dh-make</systemitem> package (see <xref "
113 "linkend=\"dh-make\"/> ), can be used to convert a vanilla source package to "
114 "a <systemitem role=\"package\">debhelper</systemitem>ized package.  This "
115 "shortcut, though, should not convince you that you do not need to bother "
116 "understanding the individual <command>dh_*</command> helpers.  If you are "
117 "going to use a helper, you do need to take the time to learn to use that "
118 "helper, to learn its expectations and behavior."
119 msgstr ""
120
121 # type: Content of: <chapter><section><section><para>
122 #: best-pkging-practices.dbk:79
123 msgid ""
124 "Some people feel that vanilla <filename>debian/rules</filename> files are "
125 "better, since you don't have to learn the intricacies of any helper system.  "
126 "This decision is completely up to you.  Use what works for you.  Many "
127 "examples of vanilla <filename>debian/rules</filename> files are available at "
128 "<ulink url=\"&url-rules-files;\"></ulink>."
129 msgstr ""
130
131 # type: Content of: <chapter><section><section><title>
132 #: best-pkging-practices.dbk:88
133 msgid "Separating your patches into multiple files"
134 msgstr ""
135
136 # type: Content of: <chapter><section><section><para>
137 #: best-pkging-practices.dbk:90
138 msgid ""
139 "Big, complex packages may have many bugs that you need to deal with.  If you "
140 "correct a number of bugs directly in the source, and you're not careful, it "
141 "can get hard to differentiate the various patches that you applied.  It can "
142 "get quite messy when you have to update the package to a new upstream "
143 "version which integrates some of the fixes (but not all).  You can't take "
144 "the total set of diffs (e.g., from <filename>.diff.gz</filename>) and work "
145 "out which patch sets to back out as a unit as bugs are fixed upstream."
146 msgstr ""
147
148 # type: Content of: <chapter><section><section><para>
149 #: best-pkging-practices.dbk:99
150 msgid ""
151 "Unfortunately, the packaging system as such currently doesn't provide for "
152 "separating the patches into several files.  Nevertheless, there are ways to "
153 "separate patches: the patch files are shipped within the Debian patch file "
154 "(<filename>.diff.gz</filename>), usually within the "
155 "<filename>debian/</filename> directory.  The only difference is that they "
156 "aren't applied immediately by dpkg-source, but by the "
157 "<literal>build</literal> rule of <filename>debian/rules</filename>.  "
158 "Conversely, they are reverted in the <literal>clean</literal> rule."
159 msgstr ""
160
161 # type: Content of: <chapter><section><section><para>
162 #: best-pkging-practices.dbk:109
163 msgid ""
164 "<command>dbs</command> is one of the more popular approaches to this.  It "
165 "does all of the above, and provides a facility for creating new and updating "
166 "old patches.  See the package <systemitem role=\"package\">dbs</systemitem> "
167 "for more information and <systemitem role=\"package\">hello-dbs</systemitem> "
168 "for an example."
169 msgstr ""
170
171 # type: Content of: <chapter><section><section><para>
172 #: best-pkging-practices.dbk:116
173 msgid ""
174 "<command>dpatch</command> also provides these facilities, but it's intended "
175 "to be even easier to use.  See the package <systemitem "
176 "role=\"package\">dpatch</systemitem> for documentation and examples (in "
177 "<filename>/usr/share/doc/dpatch</filename>)."
178 msgstr ""
179
180 # type: Content of: <chapter><section><section><title>
181 #: best-pkging-practices.dbk:124
182 msgid "Multiple binary packages"
183 msgstr ""
184
185 # type: Content of: <chapter><section><section><para>
186 #: best-pkging-practices.dbk:126
187 msgid ""
188 "A single source package will often build several binary packages, either to "
189 "provide several flavors of the same software (e.g., the <systemitem "
190 "role=\"package\">vim</systemitem> source package) or to make several small "
191 "packages instead of a big one (e.g., so the user can install only the subset "
192 "needed, and thus save some disk space)."
193 msgstr ""
194
195 # type: Content of: <chapter><section><section><para>
196 #: best-pkging-practices.dbk:133
197 msgid ""
198 "The second case can be easily managed in <filename>debian/rules</filename>.  "
199 "You just need to move the appropriate files from the build directory into "
200 "the package's temporary trees.  You can do this using "
201 "<command>install</command> or <command>dh_install</command> from <systemitem "
202 "role=\"package\">debhelper</systemitem>.  Be sure to check the different "
203 "permutations of the various packages, ensuring that you have the "
204 "inter-package dependencies set right in <filename>debian/control</filename>."
205 msgstr ""
206
207 # type: Content of: <chapter><section><section><para>
208 #: best-pkging-practices.dbk:142
209 msgid ""
210 "The first case is a bit more difficult since it involves multiple recompiles "
211 "of the same software but with different configuration options.  The "
212 "<systemitem role=\"package\">vim</systemitem> source package is an example "
213 "of how to manage this using an hand-crafted "
214 "<filename>debian/rules</filename> file."
215 msgstr ""
216
217 # type: Content of: <chapter><section><title>
218 #: best-pkging-practices.dbk:154
219 msgid "Best practices for <filename>debian/control</filename>"
220 msgstr ""
221
222 # type: Content of: <chapter><section><para>
223 #: best-pkging-practices.dbk:156
224 msgid ""
225 "The following practices are relevant to the "
226 "<filename>debian/control</filename> file.  They supplement the <ulink "
227 "url=\"&url-debian-policy;ch-binary.html#s-descriptions\">Policy on package "
228 "descriptions</ulink>."
229 msgstr ""
230
231 # type: Content of: <chapter><section><para>
232 #: best-pkging-practices.dbk:162
233 msgid ""
234 "The description of the package, as defined by the corresponding field in the "
235 "<filename>control</filename> file, contains both the package synopsis and "
236 "the long description for the package.  <xref linkend=\"bpp-desc-basics\"/> "
237 "describes common guidelines for both parts of the package description.  "
238 "Following that, <xref linkend=\"bpp-pkg-synopsis\"/> provides guidelines "
239 "specific to the synopsis, and <xref linkend=\"bpp-pkg-desc\"/> contains "
240 "guidelines specific to the description."
241 msgstr ""
242
243 # type: Content of: <chapter><section><section><title>
244 #: best-pkging-practices.dbk:171
245 msgid "General guidelines for package descriptions"
246 msgstr ""
247
248 # type: Content of: <chapter><section><section><para>
249 #: best-pkging-practices.dbk:173
250 msgid ""
251 "The package description should be written for the average likely user, the "
252 "average person who will use and benefit from the package.  For instance, "
253 "development packages are for developers, and can be technical in their "
254 "language.  More general-purpose applications, such as editors, should be "
255 "written for a less technical user."
256 msgstr ""
257
258 # type: Content of: <chapter><section><section><para>
259 #: best-pkging-practices.dbk:180
260 msgid ""
261 "Our review of package descriptions lead us to conclude that most package "
262 "descriptions are technical, that is, are not written to make sense for "
263 "non-technical users.  Unless your package really is only for technical "
264 "users, this is a problem."
265 msgstr ""
266
267 # type: Content of: <chapter><section><section><para>
268 #: best-pkging-practices.dbk:186
269 msgid ""
270 "How do you write for non-technical users? Avoid jargon.  Avoid referring to "
271 "other applications or frameworks that the user might not be familiar with — "
272 "GNOME or KDE is fine, since users are probably familiar with these terms, "
273 "but GTK+ is probably not.  Try not to assume any knowledge at all.  If you "
274 "must use technical terms, introduce them."
275 msgstr ""
276
277 # type: Content of: <chapter><section><section><para>
278 #: best-pkging-practices.dbk:193
279 msgid ""
280 "Be objective.  Package descriptions are not the place for advocating your "
281 "package, no matter how much you love it.  Remember that the reader may not "
282 "care about the same things you care about."
283 msgstr ""
284
285 # type: Content of: <chapter><section><section><para>
286 #: best-pkging-practices.dbk:198
287 msgid ""
288 "References to the names of any other software packages, protocol names, "
289 "standards, or specifications should use their canonical forms, if one "
290 "exists.  For example, use X Window System, X11, or X; not X Windows, "
291 "X-Windows, or X Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  "
292 "Use PostScript, not Postscript or postscript."
293 msgstr ""
294
295 # type: Content of: <chapter><section><section><para>
296 #: best-pkging-practices.dbk:205
297 msgid ""
298 "If you are having problems writing your description, you may wish to send it "
299 "along to &email-debian-l10n-english; and request feedback."
300 msgstr ""
301
302 # type: Content of: <chapter><section><section><title>
303 #: best-pkging-practices.dbk:211
304 msgid "The package synopsis, or short description"
305 msgstr ""
306
307 # type: Content of: <chapter><section><section><para>
308 #: best-pkging-practices.dbk:213
309 msgid ""
310 "The synopsis line (the short description) should be concise.  It must not "
311 "repeat the package's name (this is policy)."
312 msgstr ""
313
314 # type: Content of: <chapter><section><section><para>
315 #: best-pkging-practices.dbk:217
316 msgid ""
317 "It's a good idea to think of the synopsis as an appositive clause, not a "
318 "full sentence.  An appositive clause is defined in WordNet as a grammatical "
319 "relation between a word and a noun phrase that follows, e.g., Rudolph the "
320 "red-nosed reindeer.  The appositive clause here is red-nosed reindeer.  "
321 "Since the synopsis is a clause, rather than a full sentence, we recommend "
322 "that it neither start with a capital nor end with a full stop (period).  It "
323 "should also not begin with an article, either definite (the) or indefinite "
324 "(a or an)."
325 msgstr ""
326
327 # type: Content of: <chapter><section><section><para>
328 #: best-pkging-practices.dbk:226
329 msgid ""
330 "It might help to imagine that the synopsis is combined with the package name "
331 "in the following way:"
332 msgstr ""
333
334 # type: Content of: <chapter><section><section><screen>
335 #: best-pkging-practices.dbk:230
336 #, no-wrap
337 msgid ""
338 "<replaceable>package-name</replaceable> is a "
339 "<replaceable>synopsis</replaceable>."
340 msgstr ""
341
342 # type: Content of: <chapter><section><section><para>
343 #: best-pkging-practices.dbk:233
344 msgid "Alternatively, it might make sense to think of it as"
345 msgstr ""
346
347 # type: Content of: <chapter><section><section><screen>
348 #: best-pkging-practices.dbk:236
349 #, no-wrap
350 msgid ""
351 "<replaceable>package-name</replaceable> is "
352 "<replaceable>synopsis</replaceable>."
353 msgstr ""
354
355 # type: Content of: <chapter><section><section><para>
356 #: best-pkging-practices.dbk:239
357 msgid "or, if the package name itself is a plural (such as developers-tools)"
358 msgstr ""
359
360 # type: Content of: <chapter><section><section><screen>
361 #: best-pkging-practices.dbk:242
362 #, no-wrap
363 msgid ""
364 "<replaceable>package-name</replaceable> are "
365 "<replaceable>synopsis</replaceable>."
366 msgstr ""
367
368 # type: Content of: <chapter><section><section><para>
369 #: best-pkging-practices.dbk:245
370 msgid ""
371 "This way of forming a sentence from the package name and synopsis should be "
372 "considered as a heuristic and not a strict rule.  There are some cases where "
373 "it doesn't make sense to try to form a sentence."
374 msgstr ""
375
376 # type: Content of: <chapter><section><section><title>
377 #: best-pkging-practices.dbk:252
378 msgid "The long description"
379 msgstr ""
380
381 # type: Content of: <chapter><section><section><para>
382 #: best-pkging-practices.dbk:254
383 msgid ""
384 "The long description is the primary information available to the user about "
385 "a package before they install it.  It should provide all the information "
386 "needed to let the user decide whether to install the package.  Assume that "
387 "the user has already read the package synopsis."
388 msgstr ""
389
390 # type: Content of: <chapter><section><section><para>
391 #: best-pkging-practices.dbk:260
392 msgid "The long description should consist of full and complete sentences."
393 msgstr ""
394
395 # type: Content of: <chapter><section><section><para>
396 #: best-pkging-practices.dbk:263
397 msgid ""
398 "The first paragraph of the long description should answer the following "
399 "questions: what does the package do? what task does it help the user "
400 "accomplish? It is important to describe this in a non-technical way, unless "
401 "of course the audience for the package is necessarily technical."
402 msgstr ""
403
404 # type: Content of: <chapter><section><section><para>
405 #: best-pkging-practices.dbk:269
406 msgid ""
407 "The following paragraphs should answer the following questions: Why do I as "
408 "a user need this package? What other features does the package have? What "
409 "outstanding features and deficiencies are there compared to other packages "
410 "(e.g., if you need X, use Y instead)? Is this package related to other "
411 "packages in some way that is not handled by the package manager (e.g., this "
412 "is the client for the foo server)?"
413 msgstr ""
414
415 # type: Content of: <chapter><section><section><para>
416 #: best-pkging-practices.dbk:277
417 msgid ""
418 "Be careful to avoid spelling and grammar mistakes.  Ensure that you "
419 "spell-check it.  Both <command>ispell</command> and "
420 "<command>aspell</command> have special modes for checking "
421 "<filename>debian/control</filename> files:"
422 msgstr ""
423
424 # type: Content of: <chapter><section><section><screen>
425 #: best-pkging-practices.dbk:282
426 #, no-wrap
427 msgid "ispell -d american -g debian/control"
428 msgstr ""
429
430 # type: Content of: <chapter><section><section><screen>
431 #: best-pkging-practices.dbk:285
432 #, no-wrap
433 msgid "aspell -d en -D -c debian/control"
434 msgstr ""
435
436 # type: Content of: <chapter><section><section><para>
437 #: best-pkging-practices.dbk:288
438 msgid ""
439 "Users usually expect these questions to be answered in the package "
440 "description:"
441 msgstr ""
442
443 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
444 #: best-pkging-practices.dbk:293
445 msgid ""
446 "What does the package do? If it is an add-on to another package, then the "
447 "short description of the package we are an add-on to should be put in here."
448 msgstr ""
449
450 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
451 #: best-pkging-practices.dbk:299
452 msgid ""
453 "Why should I want this package? This is related to the above, but not the "
454 "same (this is a mail user agent; this is cool, fast, interfaces with PGP and "
455 "LDAP and IMAP, has features X, Y, and Z)."
456 msgstr ""
457
458 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
459 #: best-pkging-practices.dbk:306
460 msgid ""
461 "If this package should not be installed directly, but is pulled in by "
462 "another package, this should be mentioned."
463 msgstr ""
464
465 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
466 #: best-pkging-practices.dbk:312
467 msgid ""
468 "If the package is experimental, or there are other reasons it should not be "
469 "used, if there are other packages that should be used instead, it should be "
470 "here as well."
471 msgstr ""
472
473 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
474 #: best-pkging-practices.dbk:319
475 msgid ""
476 "How is this package different from the competition? Is it a better "
477 "implementation? more features? different features? Why should I choose this "
478 "package."
479 msgstr ""
480
481 # type: Content of: <chapter><section><section><title>
482 #: best-pkging-practices.dbk:332
483 msgid "Upstream home page"
484 msgstr ""
485
486 # type: Content of: <chapter><section><section><para>
487 #: best-pkging-practices.dbk:334
488 msgid ""
489 "We recommend that you add the URL for the package's home page to the package "
490 "description in <filename>debian/control</filename>.  This information should "
491 "be added at the end of description, using the following format:"
492 msgstr ""
493
494 # type: Content of: <chapter><section><section><screen>
495 #: best-pkging-practices.dbk:339
496 #, no-wrap
497 msgid ""
498 ".\n"
499 "  Homepage: http://some-project.some-place.org/"
500 msgstr ""
501
502 # type: Content of: <chapter><section><section><para>
503 #: best-pkging-practices.dbk:343
504 msgid ""
505 "Note the spaces prepending the line, which serves to break the lines "
506 "correctly.  To see an example of how this displays, see <ulink "
507 "url=\"&url-eg-desc-upstream-info;\"></ulink>."
508 msgstr ""
509
510 # type: Content of: <chapter><section><section><para>
511 #: best-pkging-practices.dbk:348
512 msgid ""
513 "If there is no home page for the software, this should naturally be left "
514 "out."
515 msgstr ""
516
517 # type: Content of: <chapter><section><section><para>
518 #: best-pkging-practices.dbk:351
519 msgid ""
520 "Note that we expect this field will eventually be replaced by a proper "
521 "<filename>debian/control</filename> field understood by "
522 "<command>dpkg</command> and <literal>&packages-host;</literal>.  If you "
523 "don't want to bother migrating the home page from the description to this "
524 "field, you should probably wait until that is available.  Please make sure "
525 "that this line matches the regular expression <literal>/^ Homepage: [^ "
526 "]*$/</literal>, as this allows <filename>&packages-host;</filename> to parse "
527 "it correctly."
528 msgstr ""
529
530 # type: Content of: <chapter><section><section><title>
531 #: best-pkging-practices.dbk:362
532 msgid "Version Control System location"
533 msgstr ""
534
535 # type: Content of: <chapter><section><section><para>
536 #: best-pkging-practices.dbk:364
537 msgid ""
538 "There are additional fields for the location of the Version Control System "
539 "in <filename>debian/control</filename>."
540 msgstr ""
541
542 # type: Content of: <chapter><section><section><section><title>
543 #: best-pkging-practices.dbk:368
544 msgid "XS-Vcs-Browser"
545 msgstr ""
546
547 # type: Content of: <chapter><section><section><section><para>
548 #: best-pkging-practices.dbk:370
549 msgid ""
550 "Value of this field should be a <literal>http://</literal> URL pointing to a "
551 "web-browsable copy of the Version Control System repository used to maintain "
552 "the given package, if available."
553 msgstr ""
554
555 # type: Content of: <chapter><section><section><section><para>
556 #: best-pkging-practices.dbk:375
557 msgid ""
558 "The information is meant to be useful for the final user, willing to browse "
559 "the latest work done on the package (e.g.  when looking for the patch fixing "
560 "a bug tagged as <literal>pending</literal> in the bug tracking system)."
561 msgstr ""
562
563 # type: Content of: <chapter><section><section><section><title>
564 #: best-pkging-practices.dbk:382
565 msgid "XS-Vcs-*"
566 msgstr ""
567
568 # type: Content of: <chapter><section><section><section><para>
569 #: best-pkging-practices.dbk:384
570 msgid ""
571 "Value of this field should be a string identifying unequivocally the "
572 "location of the Version Control System repository used to maintain the given "
573 "package, if available.  <literal>*</literal> identify the Version Control "
574 "System; currently the following systems are supported by the package "
575 "tracking system: <literal>arch</literal>, <literal>bzr</literal> (Bazaar), "
576 "<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>, "
577 "<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone), "
578 "<literal>svn</literal> (Subversion).  It is allowed to specify different VCS "
579 "fields for the same package: they will all be shown in the PTS web "
580 "interface."
581 msgstr ""
582
583 # type: Content of: <chapter><section><section><section><para>
584 #: best-pkging-practices.dbk:395
585 msgid ""
586 "The information is meant to be useful for a user knowledgeable in the given "
587 "Version Control System and willing to build the current version of a package "
588 "from the VCS sources.  Other uses of this information might include "
589 "automatic building of the latest VCS version of the given package.  To this "
590 "end the location pointed to by the field should better be version agnostic "
591 "and point to the main branch (for VCSs supporting such a concept).  Also, "
592 "the location pointed to should be accessible to the final user; fulfilling "
593 "this requirement might imply pointing to an anonymous access of the "
594 "repository instead of pointing to an SSH-accessible version of the same."
595 msgstr ""
596
597 # type: Content of: <chapter><section><section><section><para>
598 #: best-pkging-practices.dbk:406
599 msgid ""
600 "In the following example, an instance of the field for a Subversion "
601 "repository of the <systemitem role=\"package\">vim</systemitem> package is "
602 "shown.  Note how the URL is in the <literal>svn://</literal> scheme (instead "
603 "of <literal>svn+ssh://</literal>) and how it points to the "
604 "<filename>trunk/</filename> branch.  The use of the "
605 "<literal>XS-Vcs-Browser</literal> field described above is also shown."
606 msgstr ""
607
608 # type: Content of: <chapter><section><section><section><screen>
609 #: best-pkging-practices.dbk:414
610 #, no-wrap
611 msgid ""
612 "Source: vim\n"
613 "  Section: editors\n"
614 "  Priority: optional\n"
615 "  &lt;snip&gt;\n"
616 "  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
617 "  XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim"
618 msgstr ""
619
620 # type: Content of: <chapter><section><title>
621 #: best-pkging-practices.dbk:428
622 msgid "Best practices for <filename>debian/changelog</filename>"
623 msgstr ""
624
625 # type: Content of: <chapter><section><para>
626 #: best-pkging-practices.dbk:430
627 msgid ""
628 "The following practices supplement the <ulink "
629 "url=\"&url-debian-policy;ch-docs.html#s-changelogs\">Policy on changelog "
630 "files</ulink>."
631 msgstr ""
632
633 # type: Content of: <chapter><section><section><title>
634 #: best-pkging-practices.dbk:435
635 msgid "Writing useful changelog entries"
636 msgstr ""
637
638 # type: Content of: <chapter><section><section><para>
639 #: best-pkging-practices.dbk:437
640 msgid ""
641 "The changelog entry for a package revision documents changes in that "
642 "revision, and only them.  Concentrate on describing significant and "
643 "user-visible changes that were made since the last version."
644 msgstr ""
645
646 # type: Content of: <chapter><section><section><para>
647 #: best-pkging-practices.dbk:442
648 msgid ""
649 "Focus on <emphasis>what</emphasis> was changed — who, how and when are "
650 "usually less important.  Having said that, remember to politely attribute "
651 "people who have provided notable help in making the package (e.g., those who "
652 "have sent in patches)."
653 msgstr ""
654
655 # type: Content of: <chapter><section><section><para>
656 #: best-pkging-practices.dbk:448
657 msgid ""
658 "There's no need to elaborate the trivial and obvious changes.  You can also "
659 "aggregate several changes in one entry.  On the other hand, don't be overly "
660 "terse if you have undertaken a major change.  Be especially clear if there "
661 "are changes that affect the behaviour of the program.  For further "
662 "explanations, use the <filename>README.Debian</filename> file."
663 msgstr ""
664
665 # type: Content of: <chapter><section><section><para>
666 #: best-pkging-practices.dbk:455
667 msgid ""
668 "Use common English so that the majority of readers can comprehend it.  Avoid "
669 "abbreviations, tech-speak and jargon when explaining changes that close "
670 "bugs, especially for bugs filed by users that did not strike you as "
671 "particularly technically savvy.  Be polite, don't swear."
672 msgstr ""
673
674 # type: Content of: <chapter><section><section><para>
675 #: best-pkging-practices.dbk:461
676 msgid ""
677 "It is sometimes desirable to prefix changelog entries with the names of the "
678 "files that were changed.  However, there's no need to explicitly list each "
679 "and every last one of the changed files, especially if the change was small "
680 "or repetitive.  You may use wildcards."
681 msgstr ""
682
683 # type: Content of: <chapter><section><section><para>
684 #: best-pkging-practices.dbk:467
685 msgid ""
686 "When referring to bugs, don't assume anything.  Say what the problem was, "
687 "how it was fixed, and append the closes: #nnnnn string.  See <xref "
688 "linkend=\"upload-bugfix\"/> for more information."
689 msgstr ""
690
691 # type: Content of: <chapter><section><section><title>
692 #: best-pkging-practices.dbk:474
693 msgid "Common misconceptions about changelog entries"
694 msgstr ""
695
696 # type: Content of: <chapter><section><section><para>
697 #: best-pkging-practices.dbk:476
698 msgid ""
699 "The changelog entries should <emphasis role=\"strong\">not</emphasis> "
700 "document generic packaging issues (Hey, if you're looking for foo.conf, it's "
701 "in /etc/blah/.), since administrators and users are supposed to be at least "
702 "remotely acquainted with how such things are generally arranged on Debian "
703 "systems.  Do, however, mention if you change the location of a configuration "
704 "file."
705 msgstr ""
706
707 # type: Content of: <chapter><section><section><para>
708 #: best-pkging-practices.dbk:484
709 msgid ""
710 "The only bugs closed with a changelog entry should be those that are "
711 "actually fixed in the same package revision.  Closing unrelated bugs in the "
712 "changelog is bad practice.  See <xref linkend=\"upload-bugfix\"/> ."
713 msgstr ""
714
715 # type: Content of: <chapter><section><section><para>
716 #: best-pkging-practices.dbk:489
717 msgid ""
718 "The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
719 "used for random discussion with bug reporters (I don't see segfaults when "
720 "starting foo with option bar; send in more info), general statements on "
721 "life, the universe and everything (sorry this upload took me so long, but I "
722 "caught the flu), or pleas for help (the bug list on this package is huge, "
723 "please lend me a hand).  Such things usually won't be noticed by their "
724 "target audience, but may annoy people who wish to read information about "
725 "actual changes in the package.  See <xref linkend=\"bug-answering\"/> for "
726 "more information on how to use the bug tracking system."
727 msgstr ""
728
729 # type: Content of: <chapter><section><section><para>
730 #: best-pkging-practices.dbk:500
731 msgid ""
732 "It is an old tradition to acknowledge bugs fixed in non-maintainer uploads "
733 "in the first changelog entry of the proper maintainer upload.  As we have "
734 "version tracking now, it is enough to keep the NMUed changelog entries and "
735 "just mention this fact in your own changelog entry."
736 msgstr ""
737
738 # type: Content of: <chapter><section><section><title>
739 #: best-pkging-practices.dbk:508
740 msgid "Common errors in changelog entries"
741 msgstr ""
742
743 # type: Content of: <chapter><section><section><para>
744 #: best-pkging-practices.dbk:510
745 msgid ""
746 "The following examples demonstrate some common errors or examples of bad "
747 "style in changelog entries."
748 msgstr ""
749
750 # type: Content of: <chapter><section><section><screen>
751 #: best-pkging-practices.dbk:514
752 #, no-wrap
753 msgid "* Fixed all outstanding bugs."
754 msgstr ""
755
756 # type: Content of: <chapter><section><section><para>
757 #: best-pkging-practices.dbk:517
758 msgid "This doesn't tell readers anything too useful, obviously."
759 msgstr ""
760
761 # type: Content of: <chapter><section><section><screen>
762 #: best-pkging-practices.dbk:520
763 #, no-wrap
764 msgid "* Applied patch from Jane Random."
765 msgstr ""
766
767 # type: Content of: <chapter><section><section><para>
768 #: best-pkging-practices.dbk:523
769 msgid "What was the patch about?"
770 msgstr ""
771
772 # type: Content of: <chapter><section><section><screen>
773 #: best-pkging-practices.dbk:526
774 #, no-wrap
775 msgid "* Late night install target overhaul."
776 msgstr ""
777
778 # type: Content of: <chapter><section><section><para>
779 #: best-pkging-practices.dbk:529
780 msgid ""
781 "Overhaul which accomplished what? Is the mention of late night supposed to "
782 "remind us that we shouldn't trust that code?"
783 msgstr ""
784
785 # type: Content of: <chapter><section><section><screen>
786 #: best-pkging-practices.dbk:533
787 #, no-wrap
788 msgid "* Fix vsync FU w/ ancient CRTs."
789 msgstr ""
790
791 # type: Content of: <chapter><section><section><para>
792 #: best-pkging-practices.dbk:536
793 msgid ""
794 "Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a "
795 "curse word!) was actually about, or how it was fixed."
796 msgstr ""
797
798 # type: Content of: <chapter><section><section><screen>
799 #: best-pkging-practices.dbk:540
800 #, no-wrap
801 msgid "* This is not a bug, closes: #nnnnnn."
802 msgstr ""
803
804 # type: Content of: <chapter><section><section><para>
805 #: best-pkging-practices.dbk:543
806 msgid ""
807 "First of all, there's absolutely no need to upload the package to convey "
808 "this information; instead, use the bug tracking system.  Secondly, there's "
809 "no explanation as to why the report is not a bug."
810 msgstr ""
811
812 # type: Content of: <chapter><section><section><screen>
813 #: best-pkging-practices.dbk:548
814 #, no-wrap
815 msgid "* Has been fixed for ages, but I forgot to close; closes: #54321."
816 msgstr ""
817
818 # type: Content of: <chapter><section><section><para>
819 #: best-pkging-practices.dbk:551
820 msgid ""
821 "If for some reason you didn't mention the bug number in a previous changelog "
822 "entry, there's no problem, just close the bug normally in the BTS.  There's "
823 "no need to touch the changelog file, presuming the description of the fix is "
824 "already in (this applies to the fixes by the upstream authors/maintainers as "
825 "well, you don't have to track bugs that they fixed ages ago in your "
826 "changelog)."
827 msgstr ""
828
829 # type: Content of: <chapter><section><section><screen>
830 #: best-pkging-practices.dbk:558
831 #, no-wrap
832 msgid "* Closes: #12345, #12346, #15432"
833 msgstr ""
834
835 # type: Content of: <chapter><section><section><para>
836 #: best-pkging-practices.dbk:561
837 msgid ""
838 "Where's the description? If you can't think of a descriptive message, start "
839 "by inserting the title of each different bug."
840 msgstr ""
841
842 # type: Content of: <chapter><section><section><title>
843 #: best-pkging-practices.dbk:567
844 msgid "Supplementing changelogs with NEWS.Debian files"
845 msgstr ""
846
847 # type: Content of: <chapter><section><section><para>
848 #: best-pkging-practices.dbk:569
849 msgid ""
850 "Important news about changes in a package can also be put in NEWS.Debian "
851 "files.  The news will be displayed by tools like apt-listchanges, before all "
852 "the rest of the changelogs.  This is the preferred means to let the user "
853 "know about significant changes in a package.  It is better than using "
854 "debconf notes since it is less annoying and the user can go back and refer "
855 "to the NEWS.Debian file after the install.  And it's better than listing "
856 "major changes in README.Debian, since the user can easily miss such notes."
857 msgstr ""
858
859 # type: Content of: <chapter><section><section><para>
860 #: best-pkging-practices.dbk:578
861 msgid ""
862 "The file format is the same as a debian changelog file, but leave off the "
863 "asterisks and describe each news item with a full paragraph when necessary "
864 "rather than the more concise summaries that would go in a changelog.  It's a "
865 "good idea to run your file through dpkg-parsechangelog to check its "
866 "formatting as it will not be automatically checked during build as the "
867 "changelog is.  Here is an example of a real NEWS.Debian file:"
868 msgstr ""
869
870 # type: Content of: <chapter><section><section><screen>
871 #: best-pkging-practices.dbk:586
872 #, no-wrap
873 msgid ""
874 "cron (3.0pl1-74) unstable; urgency=low\n"
875 "\n"
876 "    The checksecurity script is no longer included with the cron package:\n"
877 "    it now has its own package, checksecurity. If you liked the\n"
878 "    functionality provided with that script, please install the new\n"
879 "    package.\n"
880 "\n"
881 " -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 "
882 "-0500"
883 msgstr ""
884
885 # type: Content of: <chapter><section><section><para>
886 #: best-pkging-practices.dbk:596
887 msgid ""
888 "The NEWS.Debian file is installed as "
889 "/usr/share/doc/&lt;package&gt;/NEWS.Debian.gz.  It is compressed, and always "
890 "has that name even in Debian native packages.  If you use debhelper, "
891 "dh_installchangelogs will install debian/NEWS files for you."
892 msgstr ""
893
894 # type: Content of: <chapter><section><section><para>
895 #: best-pkging-practices.dbk:602
896 msgid ""
897 "Unlike changelog files, you need not update NEWS.Debian files with every "
898 "release.  Only update them if you have something particularly newsworthy "
899 "that user should know about.  If you have no news at all, there's no need to "
900 "ship a NEWS.Debian file in your package.  No news is good news!"
901 msgstr ""
902
903 # type: Content of: <chapter><section><title>
904 #: best-pkging-practices.dbk:623
905 msgid "Best practices for maintainer scripts"
906 msgstr ""
907
908 # type: Content of: <chapter><section><para>
909 #: best-pkging-practices.dbk:625
910 msgid ""
911 "Maintainer scripts include the files <filename>debian/postinst</filename>, "
912 "<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
913 "<filename>debian/postrm</filename>.  These scripts take care of any package "
914 "installation or deinstallation setup which isn't handled merely by the "
915 "creation or removal of files and directories.  The following instructions "
916 "supplement the <ulink url=\"&url-debian-policy;\">Debian Policy</ulink>."
917 msgstr ""
918
919 # type: Content of: <chapter><section><para>
920 #: best-pkging-practices.dbk:633
921 msgid ""
922 "Maintainer scripts must be idempotent.  That means that you need to make "
923 "sure nothing bad will happen if the script is called twice where it would "
924 "usually be called once."
925 msgstr ""
926
927 # type: Content of: <chapter><section><para>
928 #: best-pkging-practices.dbk:638
929 msgid ""
930 "Standard input and output may be redirected (e.g.  into pipes) for logging "
931 "purposes, so don't rely on them being a tty."
932 msgstr ""
933
934 # type: Content of: <chapter><section><para>
935 #: best-pkging-practices.dbk:642
936 msgid ""
937 "All prompting or interactive configuration should be kept to a minimum.  "
938 "When it is necessary, you should use the <systemitem "
939 "role=\"package\">debconf</systemitem> package for the interface.  Remember "
940 "that prompting in any case can only be in the <literal>configure</literal> "
941 "stage of the <filename>postinst</filename> script."
942 msgstr ""
943
944 # type: Content of: <chapter><section><para>
945 #: best-pkging-practices.dbk:649
946 msgid ""
947 "Keep the maintainer scripts as simple as possible.  We suggest you use pure "
948 "POSIX shell scripts.  Remember, if you do need any bash features, the "
949 "maintainer script must have a bash shebang line.  POSIX shell or Bash are "
950 "preferred to Perl, since they enable <systemitem "
951 "role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
952 msgstr ""
953
954 # type: Content of: <chapter><section><para>
955 #: best-pkging-practices.dbk:656
956 msgid ""
957 "If you change your maintainer scripts, be sure to test package removal, "
958 "double installation, and purging.  Be sure that a purged package is "
959 "completely gone, that is, it must remove any files created, directly or "
960 "indirectly, in any maintainer script."
961 msgstr ""
962
963 # type: Content of: <chapter><section><para>
964 #: best-pkging-practices.dbk:662
965 msgid ""
966 "If you need to check for the existence of a command, you should use "
967 "something like"
968 msgstr ""
969
970 # type: Content of: <chapter><section><programlisting>
971 #: best-pkging-practices.dbk:665
972 #, no-wrap
973 msgid "if [ -x /usr/sbin/install-docs ]; then ..."
974 msgstr ""
975
976 # type: Content of: <chapter><section><para>
977 #: best-pkging-practices.dbk:667
978 msgid ""
979 "If you don't wish to hard-code the path of a command in your maintainer "
980 "script, the following POSIX-compliant shell function may help:"
981 msgstr ""
982
983 # type: Content of: <chapter><section><para>
984 #: best-pkging-practices.dbk:672
985 msgid ""
986 "You can use this function to search <literal>$PATH</literal> for a command "
987 "name, passed as an argument.  It returns true (zero) if the command was "
988 "found, and false if not.  This is really the most portable way, since "
989 "<literal>command -v</literal>, <command>type</command>, and "
990 "<command>which</command> are not POSIX."
991 msgstr ""
992
993 # type: Content of: <chapter><section><para>
994 #: best-pkging-practices.dbk:679
995 msgid ""
996 "While <command>which</command> is an acceptable alternative, since it is "
997 "from the required <systemitem role=\"package\">debianutils</systemitem> "
998 "package, it's not on the root partition.  That is, it's in "
999 "<filename>/usr/bin</filename> rather than <filename>/bin</filename>, so one "
1000 "can't use it in scripts which are run before the <filename>/usr</filename> "
1001 "partition is mounted.  Most scripts won't have this problem, though."
1002 msgstr ""
1003
1004 # type: Content of: <chapter><section><title>
1005 #: best-pkging-practices.dbk:689
1006 msgid ""
1007 "Configuration management with <systemitem "
1008 "role=\"package\">debconf</systemitem>"
1009 msgstr ""
1010
1011 # type: Content of: <chapter><section><para>
1012 #: best-pkging-practices.dbk:691
1013 msgid ""
1014 "<systemitem role=\"package\">Debconf</systemitem> is a configuration "
1015 "management system which can be used by all the various packaging scripts "
1016 "(<filename>postinst</filename> mainly) to request feedback from the user "
1017 "concerning how to configure the package.  Direct user interactions must now "
1018 "be avoided in favor of <systemitem role=\"package\">debconf</systemitem> "
1019 "interaction.  This will enable non-interactive installations in the future."
1020 msgstr ""
1021
1022 # type: Content of: <chapter><section><para>
1023 #: best-pkging-practices.dbk:699
1024 msgid ""
1025 "Debconf is a great tool but it is often poorly used.  Many common mistakes "
1026 "are listed in the <citerefentry> "
1027 "<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum> "
1028 "</citerefentry> man page.  It is something that you must read if you decide "
1029 "to use debconf.  Also, we document some best practices here."
1030 msgstr ""
1031
1032 # type: Content of: <chapter><section><para>
1033 #: best-pkging-practices.dbk:706
1034 msgid ""
1035 "These guidelines include some writing style and typography recommendations, "
1036 "general considerations about debconf usage as well as more specific "
1037 "recommendations for some parts of the distribution (the installation system "
1038 "for instance)."
1039 msgstr ""
1040
1041 # type: Content of: <chapter><section><section><title>
1042 #: best-pkging-practices.dbk:712
1043 msgid "Do not abuse debconf"
1044 msgstr ""
1045
1046 # type: Content of: <chapter><section><section><para>
1047 #: best-pkging-practices.dbk:714
1048 msgid ""
1049 "Since debconf appeared in Debian, it has been widely abused and several "
1050 "criticisms received by the Debian distribution come from debconf abuse with "
1051 "the need of answering a wide bunch of questions before getting any little "
1052 "thing installed."
1053 msgstr ""
1054
1055 # type: Content of: <chapter><section><section><para>
1056 #: best-pkging-practices.dbk:720
1057 msgid ""
1058 "Keep usage notes to what they belong: the NEWS.Debian, or README.Debian "
1059 "file.  Only use notes for important notes which may directly affect the "
1060 "package usability.  Remember that notes will always block the install until "
1061 "confirmed or bother the user by email."
1062 msgstr ""
1063
1064 # type: Content of: <chapter><section><section><para>
1065 #: best-pkging-practices.dbk:726
1066 msgid ""
1067 "Carefully choose the questions priorities in maintainer scripts.  See "
1068 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1069 "<manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most "
1070 "questions should use medium and low priorities."
1071 msgstr ""
1072
1073 # type: Content of: <chapter><section><section><title>
1074 #: best-pkging-practices.dbk:734
1075 msgid "General recommendations for authors and translators"
1076 msgstr ""
1077
1078 # type: Content of: <chapter><section><section><section><title>
1079 #: best-pkging-practices.dbk:736
1080 msgid "Write correct English"
1081 msgstr ""
1082
1083 # type: Content of: <chapter><section><section><section><para>
1084 #: best-pkging-practices.dbk:738
1085 msgid ""
1086 "Most Debian package maintainers are not native English speakers.  So, "
1087 "writing properly phrased templates may not be easy for them."
1088 msgstr ""
1089
1090 # type: Content of: <chapter><section><section><section><para>
1091 #: best-pkging-practices.dbk:742
1092 msgid ""
1093 "Please use (and abuse) &email-debian-l10n-english; mailing list.  Have your "
1094 "templates proofread."
1095 msgstr ""
1096
1097 # type: Content of: <chapter><section><section><section><para>
1098 #: best-pkging-practices.dbk:746
1099 msgid ""
1100 "Badly written templates give a poor image of your package, of your work...or "
1101 "even of Debian itself."
1102 msgstr ""
1103
1104 # type: Content of: <chapter><section><section><section><para>
1105 #: best-pkging-practices.dbk:750
1106 msgid ""
1107 "Avoid technical jargon as much as possible.  If some terms sound common to "
1108 "you, they may be impossible to understand for others.  If you cannot avoid "
1109 "them, try to explain them (use the extended description).  When doing so, "
1110 "try to balance between verbosity and simplicity."
1111 msgstr ""
1112
1113 # type: Content of: <chapter><section><section><section><title>
1114 #: best-pkging-practices.dbk:758
1115 msgid "Be kind to translators"
1116 msgstr ""
1117
1118 # type: Content of: <chapter><section><section><section><para>
1119 #: best-pkging-practices.dbk:760
1120 msgid ""
1121 "Debconf templates may be translated.  Debconf, along with its sister package "
1122 "<command>po-debconf</command> offers a simple framework for getting "
1123 "templates translated by translation teams or even individuals."
1124 msgstr ""
1125
1126 # type: Content of: <chapter><section><section><section><para>
1127 #: best-pkging-practices.dbk:765
1128 msgid ""
1129 "Please use gettext-based templates.  Install <systemitem "
1130 "role=\"package\">po-debconf</systemitem> on your development system and read "
1131 "its documentation (man po-debconf is a good start)."
1132 msgstr ""
1133
1134 # type: Content of: <chapter><section><section><section><para>
1135 #: best-pkging-practices.dbk:770
1136 msgid ""
1137 "Avoid changing templates too often.  Changing templates text induces more "
1138 "work to translators which will get their translation fuzzied.  If you plan "
1139 "changes to your original templates, please contact translators.  Most active "
1140 "translators are very responsive and getting their work included along with "
1141 "your modified templates will save you additional uploads.  If you use "
1142 "gettext-based templates, the translator's name and e-mail addresses are "
1143 "mentioned in the po files headers."
1144 msgstr ""
1145
1146 # type: Content of: <chapter><section><section><section><para>
1147 #: best-pkging-practices.dbk:779
1148 msgid ""
1149 "The use of the <command>podebconf-report-po</command> from the po-debconf "
1150 "package is highly recommended to warn translators which have incomplete "
1151 "translations and request them for updates."
1152 msgstr ""
1153
1154 # type: Content of: <chapter><section><section><section><para>
1155 #: best-pkging-practices.dbk:784
1156 msgid ""
1157 "If in doubt, you may also contact the translation team for a given language "
1158 "(debian-l10n-xxxxx@&lists-host;), or the &email-debian-i18n; mailing list."
1159 msgstr ""
1160
1161 # type: Content of: <chapter><section><section><section><para>
1162 #: best-pkging-practices.dbk:789
1163 msgid ""
1164 "Calls for translations posted to &email-debian-i18n; with the "
1165 "<filename>debian/po/templates.pot</filename> file attached or referenced in "
1166 "a URL are encouraged.  Be sure to mentions in these calls for new "
1167 "translations which languages you have existing translations for, in order to "
1168 "avoid duplicate work."
1169 msgstr ""
1170
1171 # type: Content of: <chapter><section><section><section><title>
1172 #: best-pkging-practices.dbk:798
1173 msgid "Unfuzzy complete translations when correcting typos and spelling"
1174 msgstr ""
1175
1176 # type: Content of: <chapter><section><section><section><para>
1177 #: best-pkging-practices.dbk:800
1178 msgid ""
1179 "When the text of a debconf template is corrected and you are <emphasis "
1180 "role=\"strong\">sure</emphasis> that the change does <emphasis "
1181 "role=\"strong\">not</emphasis> affect translations, please be kind to "
1182 "translators and unfuzzy their translations."
1183 msgstr ""
1184
1185 # type: Content of: <chapter><section><section><section><para>
1186 #: best-pkging-practices.dbk:806
1187 msgid ""
1188 "If you don't do so, the whole template will not be translated as long as a "
1189 "translator will send you an update."
1190 msgstr ""
1191
1192 # type: Content of: <chapter><section><section><section><para>
1193 #: best-pkging-practices.dbk:810
1194 msgid ""
1195 "To <emphasis role=\"strong\">unfuzzy</emphasis> translations, you can "
1196 "proceed the following way:"
1197 msgstr ""
1198
1199 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1200 #: best-pkging-practices.dbk:816
1201 msgid ""
1202 "Put all incomplete PO files out of the way.  You can check the completeness "
1203 "by using (needs the <systemitem role=\"package\">gettext</systemitem> "
1204 "package installed):"
1205 msgstr ""
1206
1207 # type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1208 #: best-pkging-practices.dbk:820
1209 #, no-wrap
1210 msgid ""
1211 "for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null\n"
1212 "--statistics $i; done"
1213 msgstr ""
1214
1215 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1216 #: best-pkging-practices.dbk:825
1217 msgid ""
1218 "move all files which report either fuzzy strings to a temporary place.  "
1219 "Files which report no fuzzy strings (only translated and untranslated) will "
1220 "be kept in place."
1221 msgstr ""
1222
1223 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1224 #: best-pkging-practices.dbk:832
1225 msgid ""
1226 "now <emphasis role=\"strong\">and now only</emphasis>, modify the template "
1227 "for the typos and check again that translation are not impacted (typos, "
1228 "spelling errors, sometimes typographical corrections are usually OK)"
1229 msgstr ""
1230
1231 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1232 #: best-pkging-practices.dbk:839
1233 msgid ""
1234 "run <command>debconf-updatepo</command>.  This will fuzzy all strings you "
1235 "modified in translations.  You can see this by running the above again"
1236 msgstr ""
1237
1238 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1239 #: best-pkging-practices.dbk:845
1240 msgid "use the following command:"
1241 msgstr ""
1242
1243 # type: Content of: <chapter><section><section><section><orderedlist><listitem><programlisting>
1244 #: best-pkging-practices.dbk:847
1245 #, no-wrap
1246 msgid "for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done"
1247 msgstr ""
1248
1249 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1250 #: best-pkging-practices.dbk:851
1251 msgid ""
1252 "move back to debian/po the files which showed fuzzy strings in the first "
1253 "step"
1254 msgstr ""
1255
1256 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
1257 #: best-pkging-practices.dbk:856
1258 msgid "run <command>debconf-updatepo</command> again"
1259 msgstr ""
1260
1261 # type: Content of: <chapter><section><section><section><title>
1262 #: best-pkging-practices.dbk:863
1263 msgid "Do not make assumptions about interfaces"
1264 msgstr ""
1265
1266 # type: Content of: <chapter><section><section><section><para>
1267 #: best-pkging-practices.dbk:865
1268 msgid ""
1269 "Templates text should not make reference to widgets belonging to some "
1270 "debconf interfaces.  Sentences like If you answer Yes...  have no meaning "
1271 "for users of graphical interfaces which use checkboxes for boolean "
1272 "questions."
1273 msgstr ""
1274
1275 # type: Content of: <chapter><section><section><section><para>
1276 #: best-pkging-practices.dbk:870
1277 msgid ""
1278 "String templates should also avoid mentioning the default values in their "
1279 "description.  First, because this is redundant with the values seen by the "
1280 "users.  Also, because these default values may be different from the "
1281 "maintainer choices (for instance, when the debconf database was preseeded)."
1282 msgstr ""
1283
1284 # type: Content of: <chapter><section><section><section><para>
1285 #: best-pkging-practices.dbk:876
1286 msgid ""
1287 "More generally speaking, try to avoid referring to user actions.  Just give "
1288 "facts."
1289 msgstr ""
1290
1291 # type: Content of: <chapter><section><section><section><title>
1292 #: best-pkging-practices.dbk:882
1293 msgid "Do not use first person"
1294 msgstr ""
1295
1296 # type: Content of: <chapter><section><section><section><para>
1297 #: best-pkging-practices.dbk:884
1298 msgid ""
1299 "You should avoid the use of first person (I will do this...  or We "
1300 "recommend...).  The computer is not a person and the Debconf templates do "
1301 "not speak for the Debian developers.  You should use neutral construction.  "
1302 "Those of you who already wrote scientific publications, just write your "
1303 "templates like you would write a scientific paper.  However, try using "
1304 "action voice if still possible, like Enable this if ...  instead of This can "
1305 "be enabled if ...."
1306 msgstr ""
1307
1308 # type: Content of: <chapter><section><section><section><title>
1309 #: best-pkging-practices.dbk:894
1310 msgid "Be gender neutral"
1311 msgstr ""
1312
1313 # type: Content of: <chapter><section><section><section><para>
1314 #: best-pkging-practices.dbk:896
1315 msgid ""
1316 "The world is made of men and women.  Please use gender-neutral constructions "
1317 "in your writing."
1318 msgstr ""
1319
1320 # type: Content of: <chapter><section><section><title>
1321 #: best-pkging-practices.dbk:904
1322 msgid "Templates fields definition"
1323 msgstr ""
1324
1325 # type: Content of: <chapter><section><section><para>
1326 #: best-pkging-practices.dbk:906
1327 msgid ""
1328 "This part gives some information which is mostly taken from the "
1329 "<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
1330 "<manvolnum>7</manvolnum> </citerefentry> manual page."
1331 msgstr ""
1332
1333 # type: Content of: <chapter><section><section><section><title>
1334 #: best-pkging-practices.dbk:911
1335 msgid "Type"
1336 msgstr ""
1337
1338 # type: Content of: <chapter><section><section><section><section><title>
1339 #: best-pkging-practices.dbk:913
1340 msgid "string:"
1341 msgstr ""
1342
1343 # type: Content of: <chapter><section><section><section><section><para>
1344 #: best-pkging-practices.dbk:915
1345 msgid "Results in a free-form input field that the user can type any string into."
1346 msgstr ""
1347
1348 # type: Content of: <chapter><section><section><section><section><title>
1349 #: best-pkging-practices.dbk:920
1350 msgid "password:"
1351 msgstr ""
1352
1353 # type: Content of: <chapter><section><section><section><section><para>
1354 #: best-pkging-practices.dbk:922
1355 msgid ""
1356 "Prompts the user for a password.  Use this with caution; be aware that the "
1357 "password the user enters will be written to debconf's database.  You should "
1358 "probably clean that value out of the database as soon as is possible."
1359 msgstr ""
1360
1361 # type: Content of: <chapter><section><section><section><section><title>
1362 #: best-pkging-practices.dbk:929
1363 msgid "boolean:"
1364 msgstr ""
1365
1366 # type: Content of: <chapter><section><section><section><section><para>
1367 #: best-pkging-practices.dbk:931
1368 msgid ""
1369 "A true/false choice.  Remember: true/false, <emphasis role=\"strong\">not "
1370 "yes/no</emphasis>..."
1371 msgstr ""
1372
1373 # type: Content of: <chapter><section><section><section><section><title>
1374 #: best-pkging-practices.dbk:937
1375 msgid "select:"
1376 msgstr ""
1377
1378 # type: Content of: <chapter><section><section><section><section><para>
1379 #: best-pkging-practices.dbk:939
1380 msgid ""
1381 "A choice between one of a number of values.  The choices must be specified "
1382 "in a field named 'Choices'.  Separate the possible values with commas and "
1383 "spaces, like this: Choices: yes, no, maybe"
1384 msgstr ""
1385
1386 # type: Content of: <chapter><section><section><section><section><title>
1387 #: best-pkging-practices.dbk:946
1388 msgid "multiselect:"
1389 msgstr ""
1390
1391 # type: Content of: <chapter><section><section><section><section><para>
1392 #: best-pkging-practices.dbk:948
1393 msgid ""
1394 "Like the select data type, except the user can choose any number of items "
1395 "from the choices list (or chose none of them)."
1396 msgstr ""
1397
1398 # type: Content of: <chapter><section><section><section><section><title>
1399 #: best-pkging-practices.dbk:954
1400 msgid "note:"
1401 msgstr ""
1402
1403 # type: Content of: <chapter><section><section><section><section><para>
1404 #: best-pkging-practices.dbk:956
1405 msgid ""
1406 "Rather than being a question per se, this datatype indicates a note that can "
1407 "be displayed to the user.  It should be used only for important notes that "
1408 "the user really should see, since debconf will go to great pains to make "
1409 "sure the user sees it; halting the install for them to press a key, and even "
1410 "mailing the note to them in some cases."
1411 msgstr ""
1412
1413 # type: Content of: <chapter><section><section><section><section><title>
1414 #: best-pkging-practices.dbk:965
1415 msgid "text:"
1416 msgstr ""
1417
1418 # type: Content of: <chapter><section><section><section><section><para>
1419 #: best-pkging-practices.dbk:967
1420 msgid "This type is now considered obsolete: don't use it."
1421 msgstr ""
1422
1423 # type: Content of: <chapter><section><section><section><section><title>
1424 #: best-pkging-practices.dbk:972
1425 msgid "error:"
1426 msgstr ""
1427
1428 # type: Content of: <chapter><section><section><section><section><para>
1429 #: best-pkging-practices.dbk:974
1430 msgid ""
1431 "This type is designed to handle error messages.  It is mostly similar to the "
1432 "note type.  Frontends may present it differently (for instance, the dialog "
1433 "frontend of cdebconf draws a red screen instead of the usual blue one)."
1434 msgstr ""
1435
1436 # type: Content of: <chapter><section><section><section><section><para>
1437 #: best-pkging-practices.dbk:979
1438 msgid ""
1439 "It is recommended to use this type for any message that needs user attention "
1440 "for a correction of any kind."
1441 msgstr ""
1442
1443 # type: Content of: <chapter><section><section><section><title>
1444 #: best-pkging-practices.dbk:987
1445 msgid "Description: short and extended description"
1446 msgstr ""
1447
1448 # type: Content of: <chapter><section><section><section><para>
1449 #: best-pkging-practices.dbk:989
1450 msgid ""
1451 "Template descriptions have two parts: short and extended.  The short "
1452 "description is in the Description: line of the template."
1453 msgstr ""
1454
1455 # type: Content of: <chapter><section><section><section><para>
1456 #: best-pkging-practices.dbk:993
1457 msgid ""
1458 "The short description should be kept short (50 characters or so) so that it "
1459 "may be accomodated by most debconf interfaces.  Keeping it short also helps "
1460 "translators, as usually translations tend to end up being longer than the "
1461 "original."
1462 msgstr ""
1463
1464 # type: Content of: <chapter><section><section><section><para>
1465 #: best-pkging-practices.dbk:999
1466 msgid ""
1467 "The short description should be able to stand on its own.  Some interfaces "
1468 "do not show the long description by default, or only if the user explicitely "
1469 "asks for it or even do not show it at all.  Avoid things like What do you "
1470 "want to do?"
1471 msgstr ""
1472
1473 # type: Content of: <chapter><section><section><section><para>
1474 #: best-pkging-practices.dbk:1005
1475 msgid ""
1476 "The short description does not necessarily have to be a full sentence.  This "
1477 "is part of the keep it short and efficient recommendation."
1478 msgstr ""
1479
1480 # type: Content of: <chapter><section><section><section><para>
1481 #: best-pkging-practices.dbk:1009
1482 msgid ""
1483 "The extended description should not repeat the short description word for "
1484 "word.  If you can't think up a long description, then first, think some "
1485 "more.  Post to debian-devel.  Ask for help.  Take a writing class! That "
1486 "extended description is important.  If after all that you still can't come "
1487 "up with anything, leave it blank."
1488 msgstr ""
1489
1490 # type: Content of: <chapter><section><section><section><para>
1491 #: best-pkging-practices.dbk:1016
1492 msgid ""
1493 "The extended description should use complete sentences.  Paragraphs should "
1494 "be kept short for improved readability.  Do not mix two ideas in the same "
1495 "paragraph but rather use another paragraph."
1496 msgstr ""
1497
1498 # type: Content of: <chapter><section><section><section><para>
1499 #: best-pkging-practices.dbk:1021
1500 msgid ""
1501 "Don't be too verbose.  User tend to ignore too long screens.  20 lines are "
1502 "by experience a border you shouldn't cross, because that means that in the "
1503 "classical dialog interface, people will need to scroll, and lot of people "
1504 "just don't do that."
1505 msgstr ""
1506
1507 # type: Content of: <chapter><section><section><section><para>
1508 #: best-pkging-practices.dbk:1027
1509 msgid ""
1510 "The extended description should <emphasis role=\"strong\">never</emphasis> "
1511 "include a question."
1512 msgstr ""
1513
1514 # type: Content of: <chapter><section><section><section><para>
1515 #: best-pkging-practices.dbk:1031
1516 msgid ""
1517 "For specific rules depending on templates type (string, boolean, etc.), "
1518 "please read below."
1519 msgstr ""
1520
1521 # type: Content of: <chapter><section><section><section><title>
1522 #: best-pkging-practices.dbk:1037
1523 msgid "Choices"
1524 msgstr ""
1525
1526 # type: Content of: <chapter><section><section><section><para>
1527 #: best-pkging-practices.dbk:1039
1528 msgid ""
1529 "This field should be used for Select and Multiselect types.  It contains the "
1530 "possible choices which will be presented to users.  These choices should be "
1531 "separated by commas."
1532 msgstr ""
1533
1534 # type: Content of: <chapter><section><section><section><title>
1535 #: best-pkging-practices.dbk:1046
1536 msgid "Default"
1537 msgstr ""
1538
1539 # type: Content of: <chapter><section><section><section><para>
1540 #: best-pkging-practices.dbk:1048
1541 msgid ""
1542 "This field is optional.  It contains the default answer for string, select "
1543 "and multiselect templates.  For multiselect templates, it may contain a "
1544 "comma-separated list of choices."
1545 msgstr ""
1546
1547 # type: Content of: <chapter><section><section><title>
1548 #: best-pkging-practices.dbk:1057
1549 msgid "Templates fields specific style guide"
1550 msgstr ""
1551
1552 # type: Content of: <chapter><section><section><section><title>
1553 #: best-pkging-practices.dbk:1059
1554 msgid "Type field"
1555 msgstr ""
1556
1557 # type: Content of: <chapter><section><section><section><para>
1558 #: best-pkging-practices.dbk:1061
1559 msgid ""
1560 "No specific indication except: use the appropriate type by referring to the "
1561 "previous section."
1562 msgstr ""
1563
1564 # type: Content of: <chapter><section><section><section><title>
1565 #: best-pkging-practices.dbk:1067
1566 msgid "Description field"
1567 msgstr ""
1568
1569 # type: Content of: <chapter><section><section><section><para>
1570 #: best-pkging-practices.dbk:1069
1571 msgid ""
1572 "Below are specific instructions for properly writing the Description (short "
1573 "and extended) depending on the template type."
1574 msgstr ""
1575
1576 # type: Content of: <chapter><section><section><section><section><title>
1577 #: best-pkging-practices.dbk:1073
1578 msgid "String/password templates"
1579 msgstr ""
1580
1581 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1582 #: best-pkging-practices.dbk:1077
1583 msgid ""
1584 "The short description is a prompt and <emphasis "
1585 "role=\"strong\">not</emphasis> a title.  Avoid question style prompts (IP "
1586 "Address?) in favour of opened prompts (IP address:).  The use of colons is "
1587 "recommended."
1588 msgstr ""
1589
1590 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1591 #: best-pkging-practices.dbk:1084
1592 msgid ""
1593 "The extended description is a complement to the short description.  In the "
1594 "extended part, explain what is being asked, rather than ask the same "
1595 "question again using longer words.  Use complete sentences.  Terse writing "
1596 "style is strongly discouraged."
1597 msgstr ""
1598
1599 # type: Content of: <chapter><section><section><section><section><title>
1600 #: best-pkging-practices.dbk:1094
1601 msgid "Boolean templates"
1602 msgstr ""
1603
1604 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1605 #: best-pkging-practices.dbk:1098
1606 msgid ""
1607 "The short description should be phrased in the form of a question which "
1608 "should be kept short and should generally end with a question mark.  Terse "
1609 "writing style is permitted and even encouraged if the question is rather "
1610 "long (remember that translations are often longer than original versions)"
1611 msgstr ""
1612
1613 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1614 #: best-pkging-practices.dbk:1106
1615 msgid ""
1616 "Again, please avoid referring to specific interface widgets.  A common "
1617 "mistake for such templates is if you answer Yes-type constructions."
1618 msgstr ""
1619
1620 # type: Content of: <chapter><section><section><section><section><title>
1621 #: best-pkging-practices.dbk:1114
1622 msgid "Select/Multiselect"
1623 msgstr ""
1624
1625 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1626 #: best-pkging-practices.dbk:1118
1627 msgid ""
1628 "The short description is a prompt and <emphasis "
1629 "role=\"strong\">not</emphasis> a title.  Do <emphasis "
1630 "role=\"strong\">not</emphasis> use useless Please choose...  constructions.  "
1631 "Users are clever enough to figure out they have to choose something...:)"
1632 msgstr ""
1633
1634 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1635 #: best-pkging-practices.dbk:1126
1636 msgid ""
1637 "The extended description will complete the short description.  It may refer "
1638 "to the available choices.  It may also mention that the user may choose more "
1639 "than one of the available choices, if the template is a multiselect one "
1640 "(although the interface often makes this clear)."
1641 msgstr ""
1642
1643 # type: Content of: <chapter><section><section><section><section><title>
1644 #: best-pkging-practices.dbk:1136
1645 msgid "Notes"
1646 msgstr ""
1647
1648 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1649 #: best-pkging-practices.dbk:1140
1650 msgid "The short description should be considered to be a *title*."
1651 msgstr ""
1652
1653 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1654 #: best-pkging-practices.dbk:1145
1655 msgid ""
1656 "The extended description is what will be displayed as a more detailed "
1657 "explanation of the note.  Phrases, no terse writing style."
1658 msgstr ""
1659
1660 # type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
1661 #: best-pkging-practices.dbk:1151
1662 msgid ""
1663 "<emphasis role=\"strong\">Do not abuse debconf.</emphasis> Notes are the "
1664 "most common way to abuse debconf.  As written in debconf-devel manual page: "
1665 "it's best to use them only for warning about very serious problems.  The "
1666 "NEWS.Debian or README.Debian files are the appropriate location for a lot of "
1667 "notes.  If, by reading this, you consider converting your Note type "
1668 "templates to entries in NEWS/Debian or README.Debian, plus consider keeping "
1669 "existing translations for the future."
1670 msgstr ""
1671
1672 # type: Content of: <chapter><section><section><section><title>
1673 #: best-pkging-practices.dbk:1166
1674 msgid "Choices field"
1675 msgstr ""
1676
1677 # type: Content of: <chapter><section><section><section><para>
1678 #: best-pkging-practices.dbk:1168
1679 msgid ""
1680 "If the Choices are likely to change often, please consider using the "
1681 "__Choices trick.  This will split each individual choice into a single "
1682 "string, which will considerably help translators for doing their work."
1683 msgstr ""
1684
1685 # type: Content of: <chapter><section><section><section><title>
1686 #: best-pkging-practices.dbk:1175 best-pkging-practices.dbk:1213
1687 msgid "Default field"
1688 msgstr ""
1689
1690 # type: Content of: <chapter><section><section><section><para>
1691 #: best-pkging-practices.dbk:1177
1692 msgid ""
1693 "If the default value, for a select template, is likely to vary depending on "
1694 "the user language (for instance, if the choice is a language choice), please "
1695 "use the _DefaultChoice trick."
1696 msgstr ""
1697
1698 # type: Content of: <chapter><section><section><section><para>
1699 #: best-pkging-practices.dbk:1182
1700 msgid ""
1701 "This special field allow translators to put the most appropriate choice "
1702 "according to their own language.  It will become the default choice when "
1703 "their language is used while your own mentioned Default Choice will be used "
1704 "chan using English."
1705 msgstr ""
1706
1707 # type: Content of: <chapter><section><section><section><para>
1708 #: best-pkging-practices.dbk:1188
1709 msgid "Example, taken from the geneweb package templates:"
1710 msgstr ""
1711
1712 # type: Content of: <chapter><section><section><section><screen>
1713 #: best-pkging-practices.dbk:1191
1714 #, no-wrap
1715 msgid ""
1716 "Template: geneweb/lang\n"
1717 "Type: select\n"
1718 "__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech "
1719 "(cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), "
1720 "Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian "
1721 "(it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian "
1722 "(ro), Russian (ru), Spanish (es), Swedish (sv)\n"
1723 "# This is the default choice. Translators may put their own language here\n"
1724 "# instead of the default.\n"
1725 "# WARNING : you MUST use the ENGLISH FORM of your language\n"
1726 "# For instance, the french translator will need to put French (fr) here.\n"
1727 "_DefaultChoice: English (en)[ translators, please see comment in PO files]\n"
1728 "_Description: Geneweb default language:"
1729 msgstr ""
1730
1731 # type: Content of: <chapter><section><section><section><para>
1732 #: best-pkging-practices.dbk:1202
1733 msgid ""
1734 "Note the use of brackets which allow internal comments in debconf fields.  "
1735 "Also note the use of comments which will show up in files the translators "
1736 "will work with."
1737 msgstr ""
1738
1739 # type: Content of: <chapter><section><section><section><para>
1740 #: best-pkging-practices.dbk:1207
1741 msgid ""
1742 "The comments are needed as the DefaultChoice trick is a bit confusing: the "
1743 "translators may put their own choice"
1744 msgstr ""
1745
1746 # type: Content of: <chapter><section><section><section><para>
1747 #: best-pkging-practices.dbk:1215
1748 msgid ""
1749 "Do NOT use empty default field.  If you don't want to use default values, do "
1750 "not use Default at all."
1751 msgstr ""
1752
1753 # type: Content of: <chapter><section><section><section><para>
1754 #: best-pkging-practices.dbk:1219
1755 msgid ""
1756 "If you use po-debconf (and you <emphasis role=\"strong\">should</emphasis>, "
1757 "see 2.2), consider making this field translatable, if you think it may be "
1758 "translated."
1759 msgstr ""
1760
1761 # type: Content of: <chapter><section><section><section><para>
1762 #: best-pkging-practices.dbk:1224
1763 msgid ""
1764 "If the default value may vary depending on language/country (for instance "
1765 "the default value for a language choice), consider using the special "
1766 "_DefaultChoice type documented in <citerefentry> "
1767 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1768 "</citerefentry>)."
1769 msgstr ""
1770
1771 # type: Content of: <chapter><section><title>
1772 #: best-pkging-practices.dbk:1236
1773 msgid "Internationalization"
1774 msgstr ""
1775
1776 # type: Content of: <chapter><section><section><title>
1777 #: best-pkging-practices.dbk:1238
1778 msgid "Handling debconf translations"
1779 msgstr ""
1780
1781 # type: Content of: <chapter><section><section><para>
1782 #: best-pkging-practices.dbk:1240
1783 msgid ""
1784 "Like porters, translators have a difficult task.  They work on many packages "
1785 "and must collaborate with many different maintainers.  Moreover, most of the "
1786 "time, they are not native English speakers, so you may need to be "
1787 "particularly patient with them."
1788 msgstr ""
1789
1790 # type: Content of: <chapter><section><section><para>
1791 #: best-pkging-practices.dbk:1246
1792 msgid ""
1793 "The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
1794 "packages configuration easier for maintainers and for users.  Originally, "
1795 "translation of debconf templates was handled with "
1796 "<command>debconf-mergetemplate</command>.  However, that technique is now "
1797 "deprecated; the best way to accomplish <systemitem "
1798 "role=\"package\">debconf</systemitem> internationalization is by using the "
1799 "<systemitem role=\"package\">po-debconf</systemitem> package.  This method "
1800 "is easier both for maintainer and translators; transition scripts are "
1801 "provided."
1802 msgstr ""
1803
1804 # type: Content of: <chapter><section><section><para>
1805 #: best-pkging-practices.dbk:1256
1806 msgid ""
1807 "Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
1808 "is stored in <filename>po</filename> files (drawing from "
1809 "<command>gettext</command> translation techniques).  Special template files "
1810 "contain the original messages and mark which fields are translatable.  When "
1811 "you change the value of a translatable field, by calling "
1812 "<command>debconf-updatepo</command>, the translation is marked as needing "
1813 "attention from the translators.  Then, at build time, the "
1814 "<command>dh_installdebconf</command> program takes care of all the needed "
1815 "magic to add the template along with the up-to-date translations into the "
1816 "binary packages.  Refer to the <citerefentry> "
1817 "<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
1818 "</citerefentry> manual page for details."
1819 msgstr ""
1820
1821 # type: Content of: <chapter><section><section><title>
1822 #: best-pkging-practices.dbk:1272
1823 msgid "Internationalized documentation"
1824 msgstr ""
1825
1826 # type: Content of: <chapter><section><section><para>
1827 #: best-pkging-practices.dbk:1274
1828 msgid ""
1829 "Internationalizing documentation is crucial for users, but a lot of labor.  "
1830 "There's no way to eliminate all that work, but you can make things easier "
1831 "for translators."
1832 msgstr ""
1833
1834 # type: Content of: <chapter><section><section><para>
1835 #: best-pkging-practices.dbk:1279
1836 msgid ""
1837 "If you maintain documentation of any size, its easier for translators if "
1838 "they have access to a source control system.  That lets translators see the "
1839 "differences between two versions of the documentation, so, for instance, "
1840 "they can see what needs to be retranslated.  It is recommended that the "
1841 "translated documentation maintain a note about what source control revision "
1842 "the translation is based on.  An interesting system is provided by <ulink "
1843 "url=\"&url-i18n-doc-check;\">doc-check</ulink> in the <systemitem "
1844 "role=\"package\">boot-floppies</systemitem> package, which shows an overview "
1845 "of the translation status for any given language, using structured comments "
1846 "for the current revision of the file to be translated and, for a translated "
1847 "file, the revision of the original file the translation is based on.  You "
1848 "might wish to adapt and provide that in your CVS area."
1849 msgstr ""
1850
1851 # type: Content of: <chapter><section><section><para>
1852 #: best-pkging-practices.dbk:1293
1853 msgid ""
1854 "If you maintain XML or SGML documentation, we suggest that you isolate any "
1855 "language-independent information and define those as entities in a separate "
1856 "file which is included by all the different translations.  This makes it "
1857 "much easier, for instance, to keep URLs up to date across multiple files."
1858 msgstr ""
1859
1860 # type: Content of: <chapter><section><title>
1861 #: best-pkging-practices.dbk:1303
1862 msgid "Common packaging situations"
1863 msgstr ""
1864
1865 # type: Content of: <chapter><section><section><title>
1866 #: best-pkging-practices.dbk:1314
1867 msgid "Packages using <command>autoconf</command>/<command>automake</command>"
1868 msgstr ""
1869
1870 # type: Content of: <chapter><section><section><para>
1871 #: best-pkging-practices.dbk:1316
1872 msgid ""
1873 "Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
1874 "<filename>config.guess</filename> files up to date is critical for porters, "
1875 "especially on more volatile architectures.  Some very good packaging "
1876 "practices for any package using <command>autoconf</command> and/or "
1877 "<command>automake</command> have been synthesized in &file-bpp-autotools; "
1878 "from the <systemitem role=\"package\">autotools-dev</systemitem> package.  "
1879 "You're strongly encouraged to read this file and to follow the given "
1880 "recommendations."
1881 msgstr ""
1882
1883 # type: Content of: <chapter><section><section><title>
1884 #: best-pkging-practices.dbk:1328
1885 msgid "Libraries"
1886 msgstr ""
1887
1888 # type: Content of: <chapter><section><section><para>
1889 #: best-pkging-practices.dbk:1330
1890 msgid ""
1891 "Libraries are always difficult to package for various reasons.  The policy "
1892 "imposes many constraints to ease their maintenance and to make sure upgrades "
1893 "are as simple as possible when a new upstream version comes out.  Breakage "
1894 "in a library can result in dozens of dependent packages breaking."
1895 msgstr ""
1896
1897 # type: Content of: <chapter><section><section><para>
1898 #: best-pkging-practices.dbk:1336
1899 msgid ""
1900 "Good practices for library packaging have been grouped in <ulink "
1901 "url=\"&url-libpkg-guide;\">the library packaging guide</ulink>."
1902 msgstr ""
1903
1904 # type: Content of: <chapter><section><section><title>
1905 #: best-pkging-practices.dbk:1343
1906 msgid "Documentation"
1907 msgstr ""
1908
1909 # type: Content of: <chapter><section><section><para>
1910 #: best-pkging-practices.dbk:1345
1911 msgid ""
1912 "Be sure to follow the <ulink url=\"&url-debian-policy;ch-docs.html\">Policy "
1913 "on documentation</ulink>."
1914 msgstr ""
1915
1916 # type: Content of: <chapter><section><section><para>
1917 #: best-pkging-practices.dbk:1350
1918 msgid ""
1919 "If your package contains documentation built from XML or SGML, we recommend "
1920 "you not ship the XML or SGML source in the binary package(s).  If users want "
1921 "the source of the documentation, they should retrieve the source package."
1922 msgstr ""
1923
1924 # type: Content of: <chapter><section><section><para>
1925 #: best-pkging-practices.dbk:1355
1926 msgid ""
1927 "Policy specifies that documentation should be shipped in HTML format.  We "
1928 "also recommend shipping documentation in PDF and plain text format if "
1929 "convenient and if output of reasonable quality is possible.  However, it is "
1930 "generally not appropriate to ship plain text versions of documentation whose "
1931 "source format is HTML."
1932 msgstr ""
1933
1934 # type: Content of: <chapter><section><section><para>
1935 #: best-pkging-practices.dbk:1362
1936 msgid ""
1937 "Major shipped manuals should register themselves with <systemitem "
1938 "role=\"package\">doc-base</systemitem> on installation.  See the <systemitem "
1939 "role=\"package\">doc-base</systemitem> package documentation for more "
1940 "information."
1941 msgstr ""
1942
1943 # type: Content of: <chapter><section><section><title>
1944 #: best-pkging-practices.dbk:1370
1945 msgid "Specific types of packages"
1946 msgstr ""
1947
1948 # type: Content of: <chapter><section><section><para>
1949 #: best-pkging-practices.dbk:1372
1950 msgid ""
1951 "Several specific types of packages have special sub-policies and "
1952 "corresponding packaging rules and practices:"
1953 msgstr ""
1954
1955 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1956 #: best-pkging-practices.dbk:1378
1957 msgid ""
1958 "Perl related packages have a <ulink url=\"&url-perl-policy;\">Perl "
1959 "policy</ulink>, some examples of packages following that policy are "
1960 "<systemitem role=\"package\">libdbd-pg-perl</systemitem> (binary perl "
1961 "module) or <systemitem role=\"package\">libmldbm-perl</systemitem> (arch "
1962 "independent perl module)."
1963 msgstr ""
1964
1965 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1966 #: best-pkging-practices.dbk:1387
1967 msgid ""
1968 "Python related packages have their python policy; see &file-python-policy; "
1969 "in the <systemitem role=\"package\">python</systemitem> package."
1970 msgstr ""
1971
1972 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1973 #: best-pkging-practices.dbk:1394
1974 msgid ""
1975 "Emacs related packages have the <ulink url=\"&url-emacs-policy;\">emacs "
1976 "policy</ulink>."
1977 msgstr ""
1978
1979 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1980 #: best-pkging-practices.dbk:1401
1981 msgid ""
1982 "Java related packages have their <ulink url=\"&url-java-policy;\">java "
1983 "policy</ulink>."
1984 msgstr ""
1985
1986 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1987 #: best-pkging-practices.dbk:1408
1988 msgid ""
1989 "Ocaml related packages have their own policy, found in &file-ocaml-policy; "
1990 "from the <systemitem role=\"package\">ocaml</systemitem> package.  A good "
1991 "example is the <systemitem role=\"package\">camlzip</systemitem> source "
1992 "package."
1993 msgstr ""
1994
1995 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
1996 #: best-pkging-practices.dbk:1416
1997 msgid ""
1998 "Packages providing XML or SGML DTDs should conform to the recommendations "
1999 "found in the <systemitem role=\"package\">sgml-base-doc</systemitem> "
2000 "package."
2001 msgstr ""
2002
2003 # type: Content of: <chapter><section><section><itemizedlist><listitem><para>
2004 #: best-pkging-practices.dbk:1422
2005 msgid ""
2006 "Lisp packages should register themselves with <systemitem "
2007 "role=\"package\">common-lisp-controller</systemitem>, about which see "
2008 "&file-lisp-controller;."
2009 msgstr ""
2010
2011 # type: Content of: <chapter><section><section><title>
2012 #: best-pkging-practices.dbk:1452
2013 msgid "Architecture-independent data"
2014 msgstr ""
2015
2016 # type: Content of: <chapter><section><section><para>
2017 #: best-pkging-practices.dbk:1454
2018 msgid ""
2019 "It is not uncommon to have a large amount of architecture-independent data "
2020 "packaged with a program.  For example, audio files, a collection of icons, "
2021 "wallpaper patterns, or other graphic files.  If the size of this data is "
2022 "negligible compared to the size of the rest of the package, it's probably "
2023 "best to keep it all in a single package."
2024 msgstr ""
2025
2026 # type: Content of: <chapter><section><section><para>
2027 #: best-pkging-practices.dbk:1461
2028 msgid ""
2029 "However, if the size of the data is considerable, consider splitting it out "
2030 "into a separate, architecture-independent package (_all.deb).  By doing "
2031 "this, you avoid needless duplication of the same data into eleven or more "
2032 ".debs, one per each architecture.  While this adds some extra overhead into "
2033 "the <filename>Packages</filename> files, it saves a lot of disk space on "
2034 "Debian mirrors.  Separating out architecture-independent data also reduces "
2035 "processing time of <command>lintian</command> or <command>linda</command> "
2036 "(see <xref linkend=\"tools-lint\"/> ) when run over the entire Debian "
2037 "archive."
2038 msgstr ""
2039
2040 # type: Content of: <chapter><section><section><title>
2041 #: best-pkging-practices.dbk:1473
2042 msgid "Needing a certain locale during build"
2043 msgstr ""
2044
2045 # type: Content of: <chapter><section><section><para>
2046 #: best-pkging-practices.dbk:1475
2047 msgid ""
2048 "If you need a certain locale during build, you can create a temporary file "
2049 "via this trick:"
2050 msgstr ""
2051
2052 # type: Content of: <chapter><section><section><para>
2053 #: best-pkging-practices.dbk:1479
2054 msgid ""
2055 "If you set <varname>LOCPATH</varname> to the equivalent of "
2056 "<filename>/usr/lib/locale</filename>, and <varname>LC_ALL</varname> to the "
2057 "name of the locale you generate, you should get what you want without being "
2058 "root.  Something like this:"
2059 msgstr ""
2060
2061 # type: Content of: <chapter><section><section><screen>
2062 #: best-pkging-practices.dbk:1484
2063 #, no-wrap
2064 msgid ""
2065 "LOCALE_PATH=debian/tmpdir/usr/lib/locale\n"
2066 "LOCALE_NAME=en_IN\n"
2067 "LOCALE_CHARSET=UTF-8\n"
2068 "\n"
2069 "mkdir -p $LOCALE_PATH\n"
2070 "localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET "
2071 "$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
2072 "\n"
2073 "# Using the locale\n"
2074 "LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date"
2075 msgstr ""
2076
2077 # type: Content of: <chapter><section><section><title>
2078 #: best-pkging-practices.dbk:1497
2079 msgid "Make transition packages deborphan compliant"
2080 msgstr ""
2081
2082 # type: Content of: <chapter><section><section><para>
2083 #: best-pkging-practices.dbk:1499
2084 msgid ""
2085 "Deborphan is a program for helping users to detect which packages can safely "
2086 "be removed from the system, i.e.  the ones that have no packages depending "
2087 "on them.  The default operation is to search only within the libs and "
2088 "oldlibs sections, to hunt down unused libraries.  But when passed the right "
2089 "argument, it tries to catch other useless packages."
2090 msgstr ""
2091
2092 # type: Content of: <chapter><section><section><para>
2093 #: best-pkging-practices.dbk:1506
2094 msgid ""
2095 "For example, with --guess-dummy, deborphan tries to search all transitional "
2096 "packages which were needed for upgrade but which can now safely be removed.  "
2097 "For that, it looks for the string dummy or transitional in their short "
2098 "description."
2099 msgstr ""
2100
2101 # type: Content of: <chapter><section><section><para>
2102 #: best-pkging-practices.dbk:1512
2103 msgid ""
2104 "So, when you are creating such a package, please make sure to add this text "
2105 "to your short description.  If you are looking for examples, just run: "
2106 "<command>apt-cache search .|grep dummy</command> or <command>apt-cache "
2107 "search .|grep transitional</command>."
2108 msgstr ""
2109
2110 # type: Content of: <chapter><section><section><title>
2111 #: best-pkging-practices.dbk:1520
2112 msgid "Best practices for <filename>orig.tar.gz</filename> files"
2113 msgstr ""
2114
2115 # type: Content of: <chapter><section><section><para>
2116 #: best-pkging-practices.dbk:1522
2117 msgid ""
2118 "There are two kinds of original source tarballs: Pristine source and "
2119 "repackaged upstream source."
2120 msgstr ""
2121
2122 # type: Content of: <chapter><section><section><section><title>
2123 #: best-pkging-practices.dbk:1526
2124 msgid "Pristine source"
2125 msgstr ""
2126
2127 # type: Content of: <chapter><section><section><section><para><footnote>
2128 #: best-pkging-practices.dbk:1528
2129 msgid ""
2130 "The defining characteristic of a pristine source tarball is that the "
2131 ".orig.tar.gz file is byte-for-byte identical to a tarball officially "
2132 "distributed by the upstream author.  <footnote>"
2133 msgstr ""
2134
2135 # type: Content of: <chapter><section><section><section><para><footnote><para>
2136 #: best-pkging-practices.dbk:1530
2137 msgid ""
2138 "We cannot prevent upstream authors from changing the tarball they distribute "
2139 "without also incrementing the version number, so there can be no guarantee "
2140 "that a pristine tarball is identical to what upstream "
2141 "<emphasis>currently</emphasis> distributing at any point in time.  All that "
2142 "can be expected is that it is identical to something that upstream once "
2143 "<emphasis>did</emphasis> distribute.  If a difference arises later (say, if "
2144 "upstream notices that he wasn't using maximal comression in his original "
2145 "distribution and then re-<literal>gzip</literal>s it), that's just too bad.  "
2146 "Since there is no good way to upload a new .orig.tar.gz for the same "
2147 "version, there is not even any point in treating this situation as a bug."
2148 msgstr ""
2149
2150 # type: Content of: <chapter><section><section><section><para>
2151 #: best-pkging-practices.dbk:1540
2152 msgid ""
2153 "</footnote> This makes it possible to use checksums to easily verify that "
2154 "all changes between Debian's version and upstream's are contained in the "
2155 "Debian diff.  Also, if the original source is huge, upstream authors and "
2156 "others who already have the upstream tarball can save download time if they "
2157 "want to inspect your packaging in detail."
2158 msgstr ""
2159
2160 # type: Content of: <chapter><section><section><section><para>
2161 #: best-pkging-practices.dbk:1548
2162 msgid ""
2163 "There is no universally accepted guidelines that upstream authors follow "
2164 "regarding to the directory structure inside their tarball, but "
2165 "<command>dpkg-source</command> is nevertheless able to deal with most "
2166 "upstream tarballs as pristine source.  Its strategy is equivalent to the "
2167 "following:"
2168 msgstr ""
2169
2170 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2171 #: best-pkging-practices.dbk:1556
2172 msgid "It unpacks the tarball in an empty temporary directory by doing"
2173 msgstr ""
2174
2175 # type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
2176 #: best-pkging-practices.dbk:1559
2177 #, no-wrap
2178 msgid ""
2179 "zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar "
2180 "xf -"
2181 msgstr ""
2182
2183 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2184 #: best-pkging-practices.dbk:1564
2185 msgid ""
2186 "If, after this, the temporary directory contains nothing but one directory "
2187 "and no other files, <command>dpkg-source</command> renames that directory to "
2188 "<literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.  The "
2189 "name of the top-level directory in the tarball does not matter, and is "
2190 "forgotten."
2191 msgstr ""
2192
2193 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2194 #: best-pkging-practices.dbk:1573
2195 msgid ""
2196 "Otherwise, the upstream tarball must have been packaged without a common "
2197 "top-level directory (shame on the upstream author!).  In this case, "
2198 "<command>dpkg-source</command> renames the temporary directory "
2199 "<emphasis>itself</emphasis> to "
2200 "<literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>."
2201 msgstr ""
2202
2203 # type: Content of: <chapter><section><section><section><title>
2204 #: best-pkging-practices.dbk:1584
2205 msgid "Repackaged upstream source"
2206 msgstr ""
2207
2208 # type: Content of: <chapter><section><section><section><para>
2209 #: best-pkging-practices.dbk:1586
2210 msgid ""
2211 "You <emphasis role=\"strong\">should</emphasis> upload packages with a "
2212 "pristine source tarball if possible, but there are various reasons why it "
2213 "might not be possible.  This is the case if upstream does not distribute the "
2214 "source as gzipped tar at all, or if upstream's tarball contains "
2215 "non-DFSG-free material that you must remove before uploading."
2216 msgstr ""
2217
2218 # type: Content of: <chapter><section><section><section><para>
2219 #: best-pkging-practices.dbk:1593
2220 msgid ""
2221 "In these cases the developer must construct a suitable .orig.tar.gz file "
2222 "himself.  We refer to such a tarball as a repackaged upstream source.  Note "
2223 "that a repackaged upstream source is different from a Debian-native "
2224 "package.  A repackaged source still comes with Debian-specific changes in a "
2225 "separate <literal>.diff.gz</literal> and still has a version number composed "
2226 "of <literal>&lt;upstream-version&gt;</literal> and "
2227 "<literal>&lt;debian-revision&gt;</literal>."
2228 msgstr ""
2229
2230 # type: Content of: <chapter><section><section><section><para>
2231 #: best-pkging-practices.dbk:1602
2232 msgid ""
2233 "There may be cases where it is desirable to repackage the source even though "
2234 "upstream distributes a <literal>.tar.gz</literal> that could in principle be "
2235 "used in its pristine form.  The most obvious is if "
2236 "<emphasis>significant</emphasis> space savings can be achieved by "
2237 "recompressing the tar archive or by removing genuinely useless cruft from "
2238 "the upstream archive.  Use your own discretion here, but be prepared to "
2239 "defend your decision if you repackage source that could have been pristine."
2240 msgstr ""
2241
2242 # type: Content of: <chapter><section><section><section><para>
2243 #: best-pkging-practices.dbk:1611
2244 msgid "A repackaged .orig.tar.gz"
2245 msgstr ""
2246
2247 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2248 #: best-pkging-practices.dbk:1616
2249 msgid ""
2250 "<emphasis role=\"strong\">must</emphasis> contain detailed information how "
2251 "the repackaged source was obtained, and how this can be reproduced in the "
2252 "<filename>debian/copyright</filename>.  It is also a good idea to provide a "
2253 "<literal>get-orig-source</literal> target in your "
2254 "<filename>debian/rules</filename> file that repeats the process, as "
2255 "described in the Policy Manual, <ulink "
2256 "url=\"&url-debian-policy;ch-source.html#s-debianrules\">Main building "
2257 "script: debian/rules</ulink>."
2258 msgstr ""
2259
2260 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote>
2261 #: best-pkging-practices.dbk:1628
2262 msgid ""
2263 "<emphasis role=\"strong\">should not</emphasis> contain any file that does "
2264 "not come from the upstream author(s), or whose contents has been changed by "
2265 "you.  <footnote>"
2266 msgstr ""
2267
2268 #.  or similarly named 
2269 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para><footnote><para>
2270 #: best-pkging-practices.dbk:1630
2271 msgid ""
2272 "As a special exception, if the omission of non-free files would lead to the "
2273 "source failing to build without assistance from the Debian diff, it might be "
2274 "appropriate to instead edit the files, omitting only the non-free parts of "
2275 "them, and/or explain the situation in a README.Debian-source file in the "
2276 "root of the source tree.  But in that case please also urge the upstream "
2277 "author to make the non-free components easier seperable from the rest of the "
2278 "source."
2279 msgstr ""
2280
2281 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2282 #: best-pkging-practices.dbk:1642
2283 msgid ""
2284 "<emphasis role=\"strong\">should</emphasis>, except where impossible for "
2285 "legal reasons, preserve the entire building and portablility infrastructure "
2286 "provided by the upstream author.  For example, it is not a sufficient reason "
2287 "for omitting a file that it is used only when building on MS-DOS.  "
2288 "Similarly, a Makefile provided by upstream should not be omitted even if the "
2289 "first thing your <filename>debian/rules</filename> does is to overwrite it "
2290 "by running a configure script."
2291 msgstr ""
2292
2293 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2294 #: best-pkging-practices.dbk:1651
2295 msgid ""
2296 "(<emphasis>Rationale:</emphasis> It is common for Debian users who need to "
2297 "build software for non-Debian platforms to fetch the source from a Debian "
2298 "mirror rather than trying to locate a canonical upstream distribution "
2299 "point)."
2300 msgstr ""
2301
2302 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2303 #: best-pkging-practices.dbk:1658
2304 msgid ""
2305 "<emphasis role=\"strong\">should</emphasis> use "
2306 "<literal>&lt;packagename&gt;-&lt;upstream-version&gt;.orig</literal> as the "
2307 "name of the top-level directory in its tarball.  This makes it possible to "
2308 "distinguish pristine tarballs from repackaged ones."
2309 msgstr ""
2310
2311 # type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
2312 #: best-pkging-practices.dbk:1666
2313 msgid ""
2314 "<emphasis role=\"strong\">should</emphasis> be gzipped with maximal "
2315 "compression."
2316 msgstr ""
2317
2318 # type: Content of: <chapter><section><section><section><para>
2319 #: best-pkging-practices.dbk:1671
2320 msgid ""
2321 "The canonical way to meet the latter two points is to let "
2322 "<literal>dpkg-source -b</literal> construct the repackaged tarball from an "
2323 "unpacked directory."
2324 msgstr ""
2325
2326 # type: Content of: <chapter><section><section><section><title>
2327 #: best-pkging-practices.dbk:1677
2328 msgid "Changing binary files in <literal>diff.gz</literal>"
2329 msgstr ""
2330
2331 # type: Content of: <chapter><section><section><section><para><footnote>
2332 #: best-pkging-practices.dbk:1679
2333 msgid ""
2334 "Sometimes it is necessary to change binary files contained in the original "
2335 "tarball, or to add binary files that are not in it.  If this is done by "
2336 "simply copying the files into the debianized source tree, "
2337 "<command>dpkg-source</command> will not be able to handle this.  On the "
2338 "other hand, according to the guidelines given above, you cannot include such "
2339 "a changed binary file in a repackaged <filename>orig.tar.gz</filename>.  "
2340 "Instead, include the file in the <filename>debian</filename> directory in "
2341 "<command>uuencode</command>d (or similar) form <footnote>"
2342 msgstr ""
2343
2344 # type: Content of: <chapter><section><section><section><para><footnote><para>
2345 #: best-pkging-practices.dbk:1686
2346 msgid ""
2347 "The file should have a name that makes it clear which binary file it "
2348 "encodes.  Usually, some postfix indicating the encoding should be appended "
2349 "to the original filename.  Note that you don't need to depend on <systemitem "
2350 "role=\"package\">sharutils</systemitem> to get the "
2351 "<command>uudecode</command> program if you use <command>perl</command>'s "
2352 "<literal>pack</literal> function.  The code could look like"
2353 msgstr ""
2354
2355 # type: Content of: <chapter><section><section><section><para>
2356 #: best-pkging-practices.dbk:1694
2357 msgid ""
2358 "&example-uu; </footnote>.  The file would then be decoded and copied to its "
2359 "place during the build process.  Thus the change will be visible quite easy."
2360 msgstr ""
2361
2362 # type: Content of: <chapter><section><section><section><para>
2363 #: best-pkging-practices.dbk:1700
2364 msgid ""
2365 "Some packages use <command>dbs</command> to manage patches to their upstream "
2366 "source, and always create a new <literal>orig.tar.gz</literal> file that "
2367 "contains the real <literal>orig.tar.gz</literal> in its toplevel directory.  "
2368 "This is questionable with respect to the preference for pristine source.  On "
2369 "the other hand, it is easy to modify or add binary files in this case: Just "
2370 "put them into the newly created <literal>orig.tar.gz</literal> file, besides "
2371 "the real one, and copy them to the right place during the build process."
2372 msgstr ""
2373
2374 # type: Content of: <chapter><section><section><title>
2375 #: best-pkging-practices.dbk:1713
2376 msgid "Best practices for debug packages"
2377 msgstr ""
2378
2379 # type: Content of: <chapter><section><section><para>
2380 #: best-pkging-practices.dbk:1715
2381 msgid ""
2382 "A debug package is a package with a name ending in -dbg, that contains "
2383 "additional information that gdb can use.  Since Debian binaries are stripped "
2384 "by default, debugging information, including function names and line "
2385 "numbers, is otherwise not available when running gdb on Debian binaries.  "
2386 "Debug packages allow users who need this additional debugging information to "
2387 "install it, without bloating a regular system with the information."
2388 msgstr ""
2389
2390 # type: Content of: <chapter><section><section><para>
2391 #: best-pkging-practices.dbk:1723
2392 msgid ""
2393 "It is up to a package's maintainer whether to create a debug package or "
2394 "not.  Maintainers are encouraged to create debug packages for library "
2395 "packages, since this can aid in debugging many programs linked to a "
2396 "library.  In general, debug packages do not need to be added for all "
2397 "programs; doing so would bloat the archive.  But if a maintainer finds that "
2398 "users often need a debugging version of a program, it can be worthwhile to "
2399 "make a debug package for it.  Programs that are core infrastructure, such as "
2400 "apache and the X server are also good candidates for debug packages."
2401 msgstr ""
2402
2403 # type: Content of: <chapter><section><section><para>
2404 #: best-pkging-practices.dbk:1733
2405 msgid ""
2406 "Some debug packages may contain an entire special debugging build of a "
2407 "library or other binary, but most of them can save space and build time by "
2408 "instead containing separated debugging symbols that gdb can find and load on "
2409 "the fly when debugging a program or library.  The convention in Debian is to "
2410 "keep these symbols in <filename>/usr/lib/debug/path</filename>, where "
2411 "<emphasis>path</emphasis> is the path to the executable or library.  For "
2412 "example, debugging symbols for <filename>/usr/bin/foo</filename> go in "
2413 "<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for "
2414 "<filename>/usr/lib/libfoo.so.1</filename> go in "
2415 "<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>."
2416 msgstr ""
2417
2418 # type: Content of: <chapter><section><section><para>
2419 #: best-pkging-practices.dbk:1745
2420 msgid ""
2421 "The debugging symbols can be extracted from an object file using objcopy "
2422 "--only-keep-debug.  Then the object file can be stripped, and objcopy "
2423 "--add-gnu-debuglink used to specify the path to the debugging symbol file.  "
2424 "<citerefentry> <refentrytitle>objcopy</refentrytitle> "
2425 "<manvolnum>1</manvolnum> </citerefentry> explains in detail how this works."
2426 msgstr ""
2427
2428 # type: Content of: <chapter><section><section><para>
2429 #: best-pkging-practices.dbk:1752
2430 msgid ""
2431 "The dh_strip command in debhelper supports creating debug packages, and can "
2432 "take care of using objcopy to separate out the debugging symbols for you.  "
2433 "If your package uses debhelper, all you need to do is call dh_strip "
2434 "--dbg-package=libfoo-dbg, and add an entry to debian/control for the debug "
2435 "package."
2436 msgstr ""
2437
2438 # type: Content of: <chapter><section><section><para>
2439 #: best-pkging-practices.dbk:1759
2440 msgid ""
2441 "Note that the Debian package should depend on the package that it provides "
2442 "debugging symbols for, and this dependency should be versioned.  For "
2443 "example:"
2444 msgstr ""
2445
2446 # type: Content of: <chapter><section><section><screen>
2447 #: best-pkging-practices.dbk:1763
2448 #, no-wrap
2449 msgid "Depends: libfoo-dbg (= ${binary:Version})"
2450 msgstr ""