DPKG-GENTDEB(1) 					User Contributed Perl Documentation					   DPKG-GENTDEB(1)

NAME

       dpkg-gentdeb - generate Debian TDeb translation packages from source.

SYNOPSIS

       dpkg-gentdeb

Copyright and Licence
	Copyright (C) 2007, 2011  Neil Williams <codehelp@debian.org>

	This package is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 3 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program.  If not, see <http://www.gnu.org/licenses/>.

DESCRIPTION

       dpkg-gentdeb is a dpkg-dev add-on created by Emdebian to create translation packages (tdebs). dpkg-gentdeb is intended to separate out the
       individual translation files from the current Debian packages into packages without any translation files and a single TDeb package, one
       per source package.

       If a second tdeb is supported by one source package, the $srcpackage-tdeb package must contain any debconf templates used by any of the
       binary packages. The second tdeb is then used for translations of optional content.

       This script is intended to provide a TDeb during the normal package build, as well as supporting later calls by translation teams to update
       the TDeb, using a debian/$package.tdeb file.

       Files to be included in a TDeb MUST be available to dpkg-gentdeb WITHOUT building the package - during a TDeb update the package can not
       rely on ANY of the package build-dependencies being installed, except possibly for the clean target.

Requirements of a TDeb
       o   TDeb packages must be Architecture: all or the upload will be rejected automatically by ftp-master. It is not possible to override this
	   restriction.

       o   Files included in TDeb packages must not require any package build-dependencies to update and package. If the TDeb contains other
	   Arch:all files like images or meta data files, those files must not require the use of make or other build instructions to create,
	   update, install or package.

	   "dpkg-gentdeb" will update supported translation mechanisms but the diff between the version of the package in the archive and the
	   changes for the TDeb update must only relate to the update of the translation itself.

	   The build-dependencies for the clean target might exist but this is not guaranteed.

       Once a package uses dpkg-gentdeb, translation files should be removed from all packages in the normal build. This includes all translated
       manpages and other translated content. Original, untranslated, content should remain.

       dpkg-gentdeb runs as a part of the normal package build - simply add the call to the binary-indep target of debian/rules then describe the
       files to be included into the TDeb in the debian/$package.tdeb file.

       The tdeb diff is created by translators when updating the tdeb package. Tdeb packages should depend on the source:Version of the declared
       package unless the TDeb replaces an existing -data or -common package in which case the existing dependency can be retained as long as it
       is at least source:Version or better.

       The name of the TDeb package can be specified using the -p option.

TDeb uploaders
       Initially, the current mechanism of filing bugs and closing bugs with a new upload will be used for TDeb updates as well. In order for
       these uploads to be accepted, packages using TDebs need to define Translation-Maintainers: in debian/control (usually the debian-i18n
       mailing list) and Localisation Assistants (uploaders nominated by Debian who coordinate translation updates so that any one package gets a
       single TDeb containing multiple updated translations).

Creating a TDeb
       If your package already puts translations into a -data or -common package and this package contains no other files which would be
       disallowed in a TDeb (i.e. files which require the package build process to create, update, install or package), then this package can be
       used as a TDeb.

       If you need to add a new package to your source for the TDeb, create that package in debian/control as normal.

       Now create a .tdeb file for that package in debian/ - e.g. if the source package is foo and the TDeb will be foo-locale, create the file
       debian/foo-locale.tdeb

       TDeb listing in the control file
		   Package: $fullname
		   Architecture: all
		   Priority: extra
		   Section: localization
		   Depends: $mainpackage (>= ${source:Version})
		   XC-Package-Type: tdeb
		   Description: Translations for $mainpackage (tdeb)
		   $mainpackage_short_description
		   .
		   This package contains the translation files.

	   TDebs are only allowed to Depend: on the main package built from the same source package and must use a versioned dependency of equal
	   to or greater than the source:Version. This allows TDebs to remain installed whilst new translations are being prepared, if the source
	   package has changed the strings for translation.

Listing files for a TDeb
       The .tdeb file needs to allow "dpkg-gentdeb" to locate the translation files and identify the upstream name used by the package
       translations.  e.g. If the package uses gettext, this will be the name of the .mo files installed in /usr/share/locale/$lang/LC_MESSAGES/.
       Note that this must be the name used by upstream and may have no direct relation to any of the Debian packages built from this source. This
       name will also be used to identify and update the POT file. If the package uses multiple PO directories, list each name separately.

       Translated manpages, where used, must be included in the TDeb - retaining the English manpages in the current package. List these files in
       the .tdeb file.

       Untranslated content which complies with the requirements of a TDeb can also be listed in the .tdeb file.

Experimental QtLinguist support
       Whilst it is possible to use TDebs with Qt translations, this is not currently being tested and is hindered by the translation tools being
       packaged in the libqt4-dev package which could be an unwelcome dependency for dpkg-gentdeb in most cases. It is possible that
       "dpkg-gentdeb" may support an option to enable Qt support where necessary.

       The .tdeb file must then list the name of the translations files used by upstream where the normal path would be
       /usr/share/$NAME/translations.

	[linguistproject] project.pro

OPTIONS

       The default action is to process all available po files and all identifiable translated content.

Use in Debian
       XC-Package-Type: tdeb needs support in Debian. Notably, many of the scripts in the devscripts package fail to identify the TDeb in the
       .changes file and certain debhelper scripts fail to handle the TDeb package-type.

       reprepro needs a patch to accept .tdeb and allow .tdeb in the repository files:
	$ reprepro --ignore=extension -b /path/ includedeb 
	unstable ../qof-locale-sv_0.7.5-1em1_arm.tdeb
	$ ls /opt/reprepro/locale/pool/main/q/qof/
	qof-locale-sv_0.7.5-1em1_arm.deb

	Filename: pool/main/q/qof/qof-locale-sv_0.7.5-1em1_arm.deb
	Description: sv translation for qof (tdeb)

       reprepro also needs a way to handle a .tdeb in a .changes file.
	reprepro -b /opt/reprepro/locale/ include unstable ../qof_0.7.5-1em1_arm.changes
	'qof-locale-id_0.7.5-1em1_arm.tdeb' is not .deb or .udeb!
	There have been errors!

Other translations
       Packages may also contain translated manpages and translations for debconf templates. These translations are not yet packaged or processed
       by dpkg-gentdeb. For Tdebs to be supported in Debian, these issues will need to be resolved such that Emdebian can continue to only package
       the gettext program translations, omitting translated manpages and leaving debconf translation support to existing tools or implement
       sufficient changes in cdebconf.

Debconf Templates
       Packages may need to rename the templates file for the template file and change the reference in debian/po/POTFILES.in to the new file.
       This results in a lintian warning:

	Now running lintian...
	W: dpkg-cross: no-debconf-templates
	Finished running lintian.

       The package probably now needs to Pre-Depend on the TDeb.  Alternatively either dpkg or debconf should automatically install a TDeb prior
       to trying to configure the main package.

       Templates files are the most common reason for l10n rebuilds of packages prior to a release.

perl v5.12.3							    2011-06-18							   DPKG-GENTDEB(1)