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