X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=best-pkging-practices.dbk;h=575a80fc3f9e7d66a799e7d210a53de0b6985671;hp=ca9f149c9d8eed0733df213bd95913e1788a184c;hb=d291c3aa43e7eca1303204812fe5323b6af9040d;hpb=fc34d7250f853440f2e1a9e89c5fd34419ee0f40 diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk index ca9f149..575a80f 100644 --- a/best-pkging-practices.dbk +++ b/best-pkging-practices.dbk @@ -567,9 +567,9 @@ inserting the title of each different bug. Important news about changes in a package can also be put in NEWS.Debian files. -The news will be displayed by tools like apt-listchanges, before all the rest +The news will be displayed by tools like apt-listchanges, before all the rest of the changelogs. This is the preferred means to let the user know about -significant changes in a package. It is better than using debconf notes since +significant changes in a package. It is better than using debconf notes since it is less annoying and the user can go back and refer to the NEWS.Debian file after the install. And it's better than listing major changes in README.Debian, since the user can easily @@ -830,128 +830,62 @@ If you don't do so, the whole template will not be translated as long as a translator will send you an update. -To unfuzzy translations, you can use two methods. The first -method does preventive search and replace actions in the -PO files. The latter uses gettext utilities to unfuzzy -strings. - - -Preventive unfuzzy method: +To unfuzzy translations, you can use +msguntypot (part of the po4a package). -Try finding a complete translation file before -the change: - -for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics $i; done - -The file only showing translated items will be used -as the reference file. If there is none (which should not happen if you take -care to properly interact with translators), you should use the file -with the most translated strings. - - - - -Identify the needed change. In this example, let's assume the change is about -fixing a typo in the word typo which was inadvertently -written as tpyo. Therefore, the change is -s/tpyo/typo. - - - - -Check that this change is only applied to the place where you really intend -to make it and not in any other place -where the original string is appropriate. This specifically applies to -change in punctuation, for instance. - - - - -Modify all PO files by using sed. The use of that command -is recommended over any text editor to guarantee that the files encoding will -not be broken by the edit action: - - -cd debian/po -for i in *.po; do sed -i 's/tpyo/typo/g' $i; done - - - - -Change the debconf template file to fix the typo. - - - - -Run debconf-updatepo. +Regenerate the POT and PO files. +debconf-updatepo -Check the foo.po reference file. Its statistics should -not be changed: +Make a copy of the POT file. - -msgfmt -o /dev/null --statistics debian/po/foo.po - +cp templates.pot templates.pot.orig -If the file's statistics changed, you did something wrong. Try again -or ask for help on the &email-debian-i18n; mailing list. +Make a copy of all the PO files. +mkdir po_fridge; cp *.po po_fridge - - -Gettext utilities method: - - -Put all incomplete PO files out of the way. You can check the completeness by -using (needs the gettext package -installed): +Change the debconf template files to fix the typos. -for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null --statistics $i; done -Move all files which report either fuzzy strings to a temporary place. Files -which report no fuzzy strings (only translated and untranslated) will be kept -in place. +Regenerate the POT and PO files (again). - - +debconf-updatepo -Now and now only, modify the template for -the typos and check again that translation are not impacted (typos, spelling -errors, sometimes typographical corrections are usually OK). +At this point, the typo fix fuzzied all the translations, and this +unfortunate change is the only one between the PO files of your main +directory and the one from the fridge. Here is how to solve this. -Run debconf-updatepo. This will fuzzy all strings you -modified in translations. You can see this by running the above again. +Discard fuzzy translation, restore the ones from the fridge. +cp po_fridge/*.po . -Use the following command: +Manually merge the PO files with the new POT file, but taking the useless fuzzy into account. -for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done +msguntypot -o templates.pot.orig -n templates.pot *.po -Move back to debian/po the files which showed fuzzy strings in the first step. - - - - -Run debconf-updatepo again. +Clean up. +rm -rf templates.pot.orig po_fridge @@ -1117,7 +1051,7 @@ description is in the Description: line of the template. The short description should be kept short (50 characters or so) so that it may -be accomodated by most debconf interfaces. Keeping it short also helps +be accommodated by most debconf interfaces. Keeping it short also helps translators, as usually translations tend to end up being longer than the original. @@ -1224,7 +1158,7 @@ strongly discouraged. The short description should be phrased in the form of a question which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember -that translations are often longer than original versions) +that translations are often longer than original versions). @@ -1350,7 +1284,7 @@ translated. If the default value may vary depending on language/country (for instance the default value for a language choice), consider using the special _Default type documented in po-debconf -7 ). +7 . @@ -1360,6 +1294,13 @@ type documented in po-debconf
Internationalization + +This section contains global information for developers to make translators' +life easier. More information for translators and developers interested +in internationalization are available in the Internationalisation and localisation in Debian +documentation. +
Handling debconf translations @@ -1421,6 +1362,14 @@ language-independent information and define those as entities in a separate file which is included by all the different translations. This makes it much easier, for instance, to keep URLs up to date across multiple files. + +Some tools (e.g. po4a, poxml, or the translate-toolkit) are specialized in extracting +the translatable material from different formats. They produce PO files, a +format quite common to translators, which permits to see what needs to be +retranslated when the translated document is updated. +
@@ -1655,10 +1604,17 @@ your short description. If you are looking for examples, just run: apt-cache search .|grep dummy or apt-cache search .|grep transitional. + +Also, it is recommended to adjust its section to +oldlibs +and its priority to +extra +in order to ease deborphan's job. +
-Best practices for <filename>.orig.tar.{gz,bz2,lzma}</filename> files +Best practices for <filename>.orig.tar.{gz,bz2,xz}</filename> files There are two kinds of original source tarballs: Pristine source and repackaged upstream source. @@ -1667,7 +1623,7 @@ upstream source. Pristine source The defining characteristic of a pristine source tarball is that the -.orig.tar.{gz,bz2,lzma} file is byte-for-byte identical to a tarball officially +.orig.tar.{gz,bz2,xz} file is byte-for-byte identical to a tarball officially distributed by the upstream author. We cannot prevent upstream authors from changing the tarball they distribute without also incrementing the version number, so there can be no guarantee that a pristine @@ -1677,7 +1633,7 @@ identical to something that upstream once did distribute. If a difference arises later (say, if upstream notices that he wasn't using maximal compression in his original distribution and then re-gzips it), that's just too bad. Since there is no good -way to upload a new .orig.tar.{gz,bz2,lzma} for the same version, there is not even any +way to upload a new .orig.tar.{gz,bz2,xz} for the same version, there is not even any point in treating this situation as a bug. This makes it possible to use checksums to easily verify that all changes between Debian's version and upstream's are contained in the Debian diff. Also, if the original @@ -1731,17 +1687,17 @@ gzipped tar at all, or if upstream's tarball contains non-DFSG-free material that you must remove before uploading. -In these cases the developer must construct a suitable .orig.tar.{gz,bz2,lzma} +In these cases the developer must construct a suitable .orig.tar.{gz,bz2,xz} file himself. We refer to such a tarball as a repackaged upstream source. Note that a repackaged upstream source is different from a Debian-native package. A repackaged source still comes with Debian-specific -changes in a separate .diff.gz or .debian.tar.{gz,bz2,lzma} +changes in a separate .diff.gz or .debian.tar.{gz,bz2,xz} and still has a version number composed of upstream-version and debian-version. There may be cases where it is desirable to repackage the source even though -upstream distributes a .tar.{gz,bz2,lzma} that could in principle be +upstream distributes a .tar.{gz,bz2,xz} that could in principle be used in its pristine form. The most obvious is if significant space savings can be achieved by recompressing the tar archive or by removing genuinely useless cruft from the upstream @@ -1749,7 +1705,7 @@ archive. Use your own discretion here, but be prepared to defend your decision if you repackage source that could have been pristine. -A repackaged .orig.tar.{gz,bz2,lzma} +A repackaged .orig.tar.{gz,bz2,xz} @@ -1882,6 +1838,33 @@ debugging symbols for, and this dependency should be versioned. For example: Depends: libfoo (= ${binary:Version})
+
+Best practices for meta-packages + +A meta-package is a mostly empty package that makes it easy to install a +coherent set of packages that can evolve over time. It achieves this by +depending on all the packages of the set. Thanks to the power of APT, the +meta-package maintainer can adjust the dependencies and the user's system +will automatically get the supplementary packages. The dropped packages +that were automatically installed will be also be marked as removal +candidates (and are even automatically removed by aptitude). +gnome and +linux-image-amd64 are two examples +of meta-packages (built by the source packages +meta-gnome2 and +linux-latest). + + +The long description of the meta-package must clearly document its purpose +so that the user knows what he will lose if he removes the package. Being +explicit about the consequences is recommended. This is particularly +important for meta-packages which are installed during initial +installation and that have not been explicitly installed by the user. +Those tend to be important to ensure smooth system upgrades and +the user should be discouraged from uninstalling them to avoid +potential breakages. + +