X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=fa740a9b02db1712179c5254be230940c5e16b04;hp=3f4c37085197672bdb67b320225adf8fc10db36c;hb=c622506e664571f7e04563fcb53aea660ba4af1d;hpb=9b64d5c215f07f2a68476e4a6f91eb0a204e3ec2 diff --git a/developers-reference.sgml b/developers-reference.sgml index 3f4c370..fa740a9 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + + + - Package with multiple patches -

-Big packages tend to have many upstream bugs that you want to fix within -the Debian package. If you just correct the bug in the source, all the -fixes are directly integrated in the .diff.gz file and you -can't easily differentiate the various patches that you applied. It gets -very messy when you have to update the package to a new upstream version -which integrates some of the fixes (but not all). + + Configuration management with debconf +

-The good solution is to keep separate patches within the -debian/patches directory and to apply them on the fly at -build time. The package dbs provides an -implementation of such a system, you just have to build-depend on dbs to -be able to use its functionalities. The package -hello-dbs is a simple example that demonstrates how to -use dbs. +Debconf is a configuration management system which +can be used by all the various packaging scripts +(postinst mainly) to request feedback from the user +concerning how to configure the package. Direct user interactions must +now be avoided in favor of debconf +interaction. This will enable non-interactive installations in the +future.

-Additionally, dbs provides facilities to create the patches and to keep -track of what they are for. +Debconf is a great tool but it is often poorly used. Many common mistakes +are listed in the man page. +It is something that you must read if you decide to use debconf. + - Multiple binary packages -

-A single source package will often build several binary packages, either -to provide several flavors of the same software (examples are the -vim-* packages) or to make several small packages instead of a big one -(it's interesting if the user doesn't need all the packages and can thus -save some disk space). -

-The second case can be easily managed by dh_install (from -debhelper) to move files from the build directory to -the package's temporary trees. -

-The first case is a bit more difficult since it involves multiple recompiles -of the same software but with different configure options. The -vim is an example of how to manage this with an -hand crafted rules file. - - Handling debconf translations -

+ + Internationalization + + + Handling debconf translations +

Like porters, translators have a difficult task. They work on many packages and must collaborate with many different maintainers. Moreover, most of the time, they are not native English -speaker, so you may need to be particularly patient with them. +speakers, so you may need to be particularly patient with them.

The goal of debconf was to make packages configuration easier for maintainers and for users. Originally, translation of debconf templates was handled with -debconf-mergetemplate from the -debconf-utils package. Since -debconf version 1.2.9, -debconf-mergetemplate has been deprecated and a new -system called po-debconf is strongly -encouraged. This new method is much easier both for the maintainer and -the translators, and you should upgrade your packages to use it. -Transition scripts are provided. +debconf-mergetemplate. However, that technique is now +deprecated; the best way to accomplish debconf +internationalization is by using the po-debconf +package. This method is easier both for maintainer and translators; +transition scripts are provided.

Using po-debconf, the translation is stored in po files (drawing from gettext translation techniques). Special template files contain the original messages and -mark which fields should be translated. When you change the original, -calling the debconf-updatepo script with no argument is -enough to mark the translation as needing attention from the -translators. Then, at build time, use the -dh_installdebconf program take care of all the needed -magic to add the template along with the up-to-date translations into -the binary packages. Refer to the manual page for details. - - - Specific packaging practices +mark which fields are translatable. When you change the value of a +translatable field, by calling debconf-updatepo, the +translation is marked as needing attention from the translators. Then, +at build time, the dh_installdebconf program takes care +of all the needed magic to add the template along with the up-to-date +translations into the binary packages. Refer to the manual page for details. + + + + Internationalized Documentation +

+Internationalizing documentation is crucial for users, but a lot of +labor. There's no way to eliminate all that work, but you can make things +easier for translators. +

+If you maintain documentation of any size, its easier for translators +if they have access to a source control system. That lets translators +see the differences between two versions of the documentation, so, for +instance, they can see what needs to be retranslated. It is +recommended that the translated documentation maintain a note about +what source control revision the translation is based on. An +interesting system is provided by in the boot-floppies package, +which shows an overview of the translation status for any given +language, using structured comments for the current revision of the +file to be translated and, for a translated file, the revision of the +original file the translation is based on. You might wish to adapt +and provide that in your CVS area. +

+If you maintain XML or SGML documentation, we suggest that you isolate +any language-independant 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. + + + + + Common Situations