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=7253cad50195d12456fb528aed8fed9749836fc0;hb=c622506e664571f7e04563fcb53aea660ba4af1d;hpb=4fcd750fdae9da7cb3f2da77536c10d8491672dd diff --git a/developers-reference.sgml b/developers-reference.sgml index 7253cad..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 -

-Like porters, translators have a difficult task. Since they work on many -packages, they cannot keep track of every change in packages in order to -be informed when a translated string is outdated. Fortunately -debconf can automatically report outdated translations, -if package maintainers follow some basic guidelines described below. -

-Translators can use debconf-getlang (package -debconf-utils) to write a templates.xx -file containing both English and localized fields (where xx is -the language code, may be followed by a country code). This file can be -put into the debian subdirectory without any change. -

-When building a binary package, debian/templates.xx files are -merged along with debian/templates to generate the -templates file contained in the binary package. This is -automatically done by dh_installdebconf (package -debhelper). If you do not use debhelper, you can -do the same with debconf-mergetemplate -(package debconf-utils). -

-When the package maintainer needs to update the templates file, they only -change debian/templates. When English strings in this file -and in debian/templates.xx differ, translators do know that -their translation is outdated. -

-Please see the page about - -at the Debian web site, it contains more detailed instructions, including a -full example. + + 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 +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. 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 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. + + - - Specific packaging practices + + Common Situations