<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
	<articleinfo>
		<title>YADA - Yet Another Debianisation Aid</title>
		<date>20 December 2009</date>
		<copyright><year>1999</year><holder>Charles Briscoe-Smith</holder></copyright>
		<copyright><year>1999-2009</year><holder>Piotr Roszatycki</holder></copyright>
	</articleinfo>
	<abstract>
		<para>YADA is a Debian packaging helper. It parses a special file, <filename>debian/packages</filename>, in a source package, and generates an appropriate <filename>debian/rules</filename>to control building of the package.</para>
	</abstract>
	<sect1>
		<title>How YADA works</title>
		<para>The basic idea is very simple: everything that used to be scattered amongst many little files in your <filename>debian/</filename> directory is now concentrated into a single file, <filename>debian/packages</filename>. There are only a couple of exceptions: <filename>debian/changelog</filename>is unchanged, and <filename>debian/yada</filename>is the YADA script, which you must copy into <filename>/usr/bin</filename> or into your <filename>debian/</filename> directory. You can do this with the command <command>yada</command> <option>yada</option>. <filename>debian/rules</filename>, <filename>debian/control</filename>and optional <filename>debian/templates</filename> are now generated from <filename>debian/packages</filename>by YADA. Most of the other files there will then likely be redundant. </para>
		<para>So the only thing you now need to know to switch to YADA is how to write <filename>debian/packages</filename>! Read on. </para>
		<para>When you've written <filename>debian/packages</filename>, you'll need to run <command>yada</command> <option>generate</option> in order to generate your new <filename>debian/control</filename>and <filename>debian/rules</filename>. After that, your rules file should automatically regenerate both itself and <filename>debian/control</filename>as necessary. </para>
	</sect1>
	<sect1>
		<title>yada command</title>
		<para>YADA is a just perl script so it can be installed globally in the system in <filename>/usr/bin</filename> directory or can be placed in local <filename>debian/</filename> directory. It is also possible to use newer yada script in <filename>debian/</filename> directory than installed in <filename>/usr/bin</filename> directory. </para>
		<para>Commands available: </para>
		<itemizedlist>
			<listitem>
				<para><command>yada</command> <option>yada</option> </para>
				<para>This command creates an skeleton <filename>debian/packages</filename>file for you to fill in, if you don't already have one and creates <filename>debian/changelog</filename>for initial release. </para>
			</listitem>
			<listitem>
				<para><command>yada</command> <option>rebuild rules</option> </para>
				<para>YADA reads <filename>debian/packages</filename>and generates a new rules file, <filename>debian/rules</filename>. Note that any existing rules file will be overwritten, and no backup will be kept. </para>
			</listitem>
			<listitem>
				<para><command>yada</command> <option>rebuild control</option> </para>
				<para>YADA reads <filename>debian/packages</filename>and generates a new control file, <filename>debian/control</filename>. Note that any existing control file will be overwritten, and no backup will be kept. </para>
			</listitem>
			<listitem>
				<para><command>yada</command> <option>rebuild templates</option> </para>
				<para>YADA reads <filename>debian/packages</filename>and generates a new optional templates file, <filename>debian/templates</filename>. Note that any existing templates file will be overwritten, and no backup will be kept. This file is created only if <filename>debian/packages</filename>contains any Templates: field. The file might be used with <citerefentry><refentrytitle>debconf-updatepo</refentrytitle><manvolnum>1</manvolnum></citerefentry> command of <citerefentry><refentrytitle>po-debconf</refentrytitle><manvolnum>7</manvolnum></citerefentry> system to regenerate DebConf translations located in <filename>debian/po/</filename> directory. </para>
			</listitem>
			<listitem>
				<para><command>yada</command> <option>rebuild</option> </para>
				<para>Regenerates all above required files if they don't exists already. </para>
			</listitem>
		</itemizedlist>
	</sect1>
	<sect1>
		<title>The format of <filename>debian/packages</filename></title>
		<para><filename>debian/packages</filename>is based on the format of <filename>debian/control</filename>, but with several differences. I'll explain the format from scratch. </para>
		<para><filename>debian/packages</filename>is formed from a series of paragraphs, separated by blank lines. Empty paragraphs are ignored, so you can add extra blank lines before and after paragraphs without problems. ALL lines are stripped of trailing whitespace, in order to ensure that what you see is what YADA sees. (I'm paranoid about trailing whitespace.) </para>
		<para>Lines beginning with a hash mark ("#") at the left margin are ignored completely. If the hash mark has white space in front of it, the line is treated as part of an extended field if appropriate; if not, it is ignored. </para>
		<para>Lines beginning with a percent mark ("%") at the left margin means macro commands similar to macros used by C preprocessor. The defined macro variables can be further used in common paragraphs or as parameters for other macro commands. </para>
		<para>Each paragraph is made up of fields, each of which associates a keyword with a textual value. A field's value can be single-line or multi-line. The first (or only) line of a field starts at the left margin with a case-insensitive keyword containing alphanumerics and hyphens, followed by a colon, followed by the first (or only) line of the field's value. Subsequent lines of the field start with a space character at the left margin, and are followed by one line of the field's value. </para>
		<para>Here are a couple of example paragraphs in this format: </para>
		<programlisting>

	Word: gnu
	Part-Of-Speech: noun
	# Note to myself: must fix this pronunciation
	Pronunciation: guh-NOO
	Definition: a large animal in the
	 antelope family, which has a hairy
	 coat.
	
	Word: gnat
	Part-of-speech: noun
	Definition: a small insect which bites
	 anything that moves.
</programlisting>
		<para>The observant will have noticed that this leaves no way to include a blank line in a field's value; since trailing whitespace is stripped, a line containing only a space would be treated as the end of the paragraph. There is an escape sequence for this: a line containing a single dot (a.k.a. full stop or period) after the initial space will be treated as blank. </para>
		<para>In fact, any line containing only dots after that initial space will have one of them stripped off before being processed. Lines starting with a space and a dot, but which contain a character other than a dot anywhere in the line are left unmolested. </para>
		<para>So, we can include blank lines like this: </para>
		<programlisting>

	Dish:           Boiled lobster
	Ingredients:
	 1 lobster
	 1 anvil
	 1 saucepan
	Method:
	 First, catch your lobster.
	 .
	 When you have it cornered, stun it
	 by hitting it over the head with the
	 anvil, then quickly put it into the
	 saucepan and boil it.
	 .
	 You should take great care not to let
	 the lobster take posession of the
	 anvil; a lobster with an anvil can
	 make your life hell.
</programlisting>

		<para>That example also demonstrates another minor feature: blank space is stripped from the beginning of the first line of a multi-line value. If that first line is entirely white space, the whole line is ignored, and the value starts on the line AFTER the line containing the keyword. </para>
	</sect1>
	<sect1>
		<title>How to write <filename>debian/packages</filename></title>
		<para>There are two kinds of paragraph in <filename>debian/packages</filename>. The first paragraph in the file describes the source package, describing how to build it, how to clean it, what it's called, where it came from, who maintains it, etc. The following paragraphs each describe a binary package which can be built from the source package. </para>
		<sect2>
			<title>Merged fields</title>
			<para>YADA merges several fields with the same keyword into one field. So, if we have several "Postinst: ..." sections, they will be concatenate (or a error will be generated if different shells are requested). There are also added two general keyword: "After-" and "Before-" that can be prepend to the classical keywords. With this, these section are concatenate after or before the regular section. </para>
			<para>In example, the section: </para>
			<programlisting>

	Build: sh
	 echo test build
	After-Build: sh
	 echo test after-build
	Before-Build: sh
	 echo test before-build
 </programlisting>
			<para>will be concatenated into one field: </para>
			<programlisting>

	Build: sh
	 echo test before-build
	 echo test build
	 echo test after-build
 </programlisting>
		</sect2>
		<sect2>
			<title>Executable fields</title>
			<para>Several fields contain commands to be executed at appropriate points during the processing of the package. The first line of one of these executable fields specifies which command processor is to be used to execute the field; subsequent lines are the commands to be executed. </para>
			<para>At present, the only command processor recognised by YADA is <command>sh</command> and <command>bash</command>, the bourne shell. The rest of the field is interpreted as a shell script fragment. The fragment will be executed with the shell's <option>-e</option> option set, so that if any command fails, the whole script will fail. </para>
			<programlisting>

	Source: libxyz
	 [...]
	Build: bash
	 ./configure --prefix=/usr
	 CC=${CC:-gcc}
	 CFLAGS=${CFLAGS:--Wall -g}
	 if [ "${DEB_BUILD_OPTIONS#*noopt}" != "$DEB_BUILD_OPTIONS" ]; then
	     CFLAGS="$CFLAGS -O0"
	 else
	     CFLAGS="$CFLAGS -O2"
	 fi
	 make CFLAGS="$CFLAGS" LDFLAGS="$LDFLAGS" CC="$CC"
	Clean: sh
	 make distclean || true
 </programlisting>
			<para>In some cases, extra variables or commands may be available for use by an executable field. These are described below. </para>
		</sect2>
		<sect2>
			<title>Environment variables</title>
			<para>Several extra environment variables are available to use with Build, Install, Finalize, Preinst, Postinst, Prerm, Postrm, Config and Init fields. </para>
			<variablelist>
				<varlistentry>
					<term><varname>ROOT</varname></term>
					<listitem>
						<para>The root of the temporary filesystem image to install into. You won't need to use this in most cases. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><varname>TMPROOT</varname></term>
					<listitem>
						<para>The temporary directory shared with all binary packages. It can be used for <command>make</command> <option>install DESTDIR=$TMPROOT</option>. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><varname>CONTROL</varname></term>
					<listitem>
						<para>The directory into which control files are to be installed. You probably won't need to use this unless you install control files that yada doesn't already know about. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><varname>PACKAGE</varname></term>
					<listitem>
						<para>The name of the binary package being built. This variable is set only for binary packages. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><varname>SOURCE</varname></term>
					<listitem>
						<para>The name of the source package being built. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><varname>VERSION</varname></term>
					<listitem>
						<para>The version of the Debian source package. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term><varname>DEB_*</varname></term>
					<listitem>
						<para>The variables will be set by <citerefentry><refentrytitle>dpkg-architecture</refentrytitle><manvolnum>1</manvolnum></citerefentry> command. You will need these variables if you use different settings for various architectures (i.e. special optimalization for i386 or alpha). </para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect2>
		<sect2>
			<title>Fields in the source paragraph</title>
			<para>The following fields have the same meaning as they do in <filename>debian/control</filename>, and should all be present in <filename>debian/packages</filename>: </para>
			<variablelist>
				<varlistentry>
					<term>Source</term>
					<listitem>
						<para>The name of the source package. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Section</term>
					<listitem>
						<para>The section (main, contrib, non-free or non-us) and subsection (admin, devel, games, x11, etc.) of the source package in the archive, separated by a forward slash. If the section is main, give only the subsection. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Priority</term>
					<listitem>
						<para>How necessary the programs or data contained in source package are to the running of the system (required, important, standard, optional or extra). </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Maintainer</term>
					<listitem>
						<para>The full name and email address of the person currently responsible for this source package. The email address should be separated from the name by a single space, and surrounded by angle-brackets. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Standards-version</term>
					<listitem>
						<para>Which version of Debian policy the maintainer believes this package conforms to. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Format</term>
					<listitem>
						<para>The version number of debian/control format. It can be safely missed. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Origin</term>
					<listitem>
						<para>This field changes origin of the package. The default value is "debian" which means the information about origin is in the file <filename>/etc/dpkg/origins/debian</filename>. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Bugs</term>
					<listitem>
						<para>The URL for Bugs Tracking System, i.e. "debbugs://bugs.debian.org" for packages from Debian distribution. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Homepage</term>
					<listitem>
						<para>The URL of the World-Wide Web home page of the upstream package. You should include this if possible. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Build-Depends</term>
					<listitem>
						<para/>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Build-Depends-Indep</term>
					<listitem>
						<para>These fields specify relationships between this package and other packages at build time. They each comprise a comma-separated list of dependencies, which are treated as set out in the Debian packaging manual. A dependency is either a single package, a list of alternative packages separated by vertical bars. The YADA automatically adds build depends on "file, patch, perl" if called <filename>debian/yada</filename> or "yada" if called <filename>/usr/bin/yada</filename>. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Vcs-Browser</term>
					<listitem>
						<para>The URL of web page which provides HTML interface for Version Control System of this source package. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Vcs-Arch, Vcs-Bzr, Vcs-Cvs, Vcs-Darcs, Vcs-Git, Vcs-Hg, Vcs-Mtn, Vcs-Svn</term>
					<listitem>
						<para>The URL of Version Control System of this source package. </para>
					</listitem>
				</varlistentry>
			</variablelist>
			<para>The following fields are defined by YADA, and you should use them in <filename>debian/packages</filename>. YADA uses the first four of these to construct the <filename>/usr/share/doc/<replaceable>package</replaceable>/copyright</filename> file, so it is important they are correct. </para>
			<variablelist>
				<varlistentry>
					<term>Upstream-Source</term>
					<listitem>
						<para>The URL of the upstream source code. If this field is not present, YADA will assume that the package is a Debian-native package. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Copyright</term>
					<listitem>
						<para>The first line of this field gives the names of the standard copyright licence which applies to this package, if any. The following lines should contain a copy of the source package's copyright notice and copyright licence. If any of the standard licences are mentioned, you need not write where their full text can be found on a Debian system; yada will add that information for you. The standard licence names defined at present are "GPL", "LGPL", "GFDL", "Apache", "Artistic" and "BSD". The license name can contain its version number after hyphen mark (i.e. "GPL-3"). If none apply, place a single dot on the first line, and include the complete copyright and licence notice. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Major-Changes</term>
					<listitem>
						<para>If any major changes have been made to the upstream source, list them here. This fulfils the Debian policy requirement that changes be listed, and fulfils the legal requirements of several common copyright licences. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Packaged-For</term>
					<listitem>
						<para>The name of the project or organisation for which you produced the package. For packages produced by registered Debian developers, this field should read "Debian". For others, it might read, for example, "GNU", or "Hungry Programmers", or "Corel Corp.". If you didn't create the package as part of your work for anyone other than yourself, then don't include a "Origin" field. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Description</term>
					<listitem>
						<para>The first line of this field gives the human-readable name of the package. For example, if the Source field reads "libc6", the first line of the Description field might read "The GNU C library, version 2". The rest of the field should contain any descriptive text which pertains to ALL the binary packages this source package produces. It will be prepended to the Description field of each binary package, followed by a blank line. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Build</term>
					<listitem>
						<para>An executable field describing how to build the software contained in the package. One extra command is available in this field: </para>
						<itemizedlist>
							<listitem>
								<para>yada fixup libtool [&lt;pathname&gt;] </para>
								<para>Performs the fixups described in Lintian's "libtool-workarounds.txt" to prevent libtool hardcoding shared library directories into binaries. This should be called AFTER the configure script has generated libtool, but before libtool gets used. If the libtool script is not named "libtool" in the current directory, specify its &lt;pathname&gt;. </para>
							</listitem>
						</itemizedlist>
						<para>This field is called with "build" target. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Build-Arch</term>
					<listitem>
						<para>An executable field describing how to build architecture depended code in the package. This field is called with "build-arch" and "build" targets. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Build-Indep</term>
					<listitem>
						<para>An executable field describing how to build architecture independed code in the package. This field is called with "build-indep" and "build" targets. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Clean</term>
					<listitem>
						<para>An executable field describing how to reverse the effects of the Build field. There are no extra commands or variables available. This field is called with "clean" target. </para>
					</listitem>
				</varlistentry>
			</variablelist>
			<para>These fields are also defined by YADA, but you may not need to use them: </para>
			<variablelist>
				<varlistentry>
					<term>Upstream-Authors</term>
					<listitem>
						<para>The names and email addressed of upstream authors. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Packager</term>
					<listitem>
						<para>The name and email address of the person who originally created Debianised this package, if not the current maintainer. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Other-Maintainers</term>
					<listitem>
						<para>The names and email addresses of any previous maintainers of this package, excluding the original packager and the current maintainer. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Patches</term>
					<listitem>
						<para>A wildcard matching those files in the debian/ directory which should be treated as patches, and automatically patched into the source. It means that "yada patch ..." command is called before Build script and "yada unpatch" command is called after Clean script. Automatic patching is not activated unless you specify this field. This feature was inspired by the "*.dpatch" system in the egcs packages. </para>
						<para>Most often, this field would be used like this: </para>
						<programlisting>

	Patches: *.diff
</programlisting>

						<para>The matchings can be separated with whitespace: </para>
						<programlisting>
	
	Patches: patches/*-all.diff patches/*-i386.diff
</programlisting>
						<para>The second example is equivalent of: </para>
						<programlisting>

	Build: sh
	 yada patch "debian/patches/*-all.diff"
	 yada patch "debian/patches/*-i386.diff"
</programlisting>
						<para>Basically, it works as follows. Instead of applying patches to the source tree directly, and letting dpkg-source handle them, you place the patches in files in your <filename>debian/</filename> directory. The names of these files should be matched by the contents of the "Patches:" field; this is how yada recognises patch files. So, for example, if you are sent an optimiser patch for your compiler, you can simply copy the email to <filename>debian/optimiser.diff</filename>. </para>
						<para>When your source package is built, each patch is applied to the source tree. When your package is cleaned, the patches are unapplied. Yada takes some care to keep track of the status (applied or not) of every patch using files named like <filename>debian/patch-*-applied</filename>, and it applies and unapplies the patches as necessary. (For safety's sake, you should make sure your pattern cannot match files of the form <filename>patch-*-applied</filename>.) </para>
						<para>Often, patches are intended to patch files in subdirectories. This means that <command>patch</command> needs to be given the <option>-p&lt;n&gt;</option> option to tell it how many pathname components to strip from filenames. You can give options to <command>patch</command> by putting a <option>PATCHOPTIONS</option> line in the patch file. The line must contain the text <option>#PATCHOPTIONS:</option> at the start of a line. The rest of the line gives options which will be passed to <command>patch</command> when applying or unapplying that patch file. </para>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect2>
		<sect2>
			<title>Fields in binary paragraphs</title>
			<para>The following fields can be used in the paragraphs describing binary packages. First, the fields which have the same meaning as in <filename>debian/control</filename>: </para>
			<variablelist>
				<varlistentry>
					<term>Package</term>
					<listitem>
						<para>The name of the binary package. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Version</term>
					<listitem>
						<para>If this field in binary package's paragraph exists, the package can contain different version number than source package version. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Architecture</term>
					<listitem>
						<para>The architecture(s) for which this binary package may be built. "all" means that it is architecture-independent; "any" means that it is not architecture-independent, but may be built for any architecture. "none" is a YADA extension and means that this binary package will never be built (useful for "commenting out" binary packages). Macros "linux", "hurd", "darwin", "freebsd", "netbsd", "openbsd", "kfreebsd", "knetbsd" and "solaris" are expanded to native dpkg's architecture names. </para>
						<programlisting>

	Package: package-linuxonly
	Architecture: linux
	
	Package: package-doc
	Architecture: all
	
	Package: package-intelonly
	Architecture: i386
</programlisting>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Section</term>
					<listitem>
						<para/>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Priority</term>
					<listitem>
						<para>Analogous to the Section and Priority fields in the source paragraph, these classify the binary package. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Essential</term>
					<listitem>
						<para>If "yes", <command>dpkg</command> will prevent the end-user from removing the binary package from the system unless <option>--force-remove-essential</option> is specified. Do not use this unless you have discussed it on debian-devel and the concensus opinion is that you may. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Pre-Depends, Depends, Recommends, Suggests, Enhances</term>
					<listitem>
						<para>These fields specify relationships between this package as other packages which may be installed on the target system. They each comprise a comma-separated list of dependencies, which are treated as set out in the Debian packaging manual. A dependency is either a single package, a list of alternative packages separated by vertical bars, or (a YADA extension) one or more filenames or file-globs in square brackets. Filenames in square brackets should be absolute filenames on the installed system, and are fed to <command>dpkg-shlibdeps</command> to be analysed for shared library dependencies. The output of <command>dpkg-shlibdeps</command> is substituted for the square brackets and the file-globs before the field is placed into the binary package. </para>
						<para>For example, most packages containing ELF binaries will use the line: </para>
						<programlisting>

	Package: mypackage
	Depends: [/usr/bin/*]
</programlisting>
						<para>In this case, yada will generate <varname>${shlibs:mypackage:Depends}</varname> variable. All <varname>${*:mypackage:Depends}</varname> variables will be joined to one <varname>${mypackage:Depends}</varname> variable. </para>
						<para>If the "Depends" field is ommited, and the package have ELF binaries, this field will be generated automatically. </para>
						<para>The substvars variables will be generated automatically for some of the special fields, i.e. <varname>${doc-base:$PACKAGE:Suggests}</varname> for "Doc-Base" field or <varname>${menu:$PACKAGE:Suggests}</varname> for "Menu" field. </para>
						<para>The square brackets without filenames will be replaced by <varname>${$PACKAGE:Field}</varname>. </para>
						<para>If package name contains dot (.) or colon (:), you have to replace it with hyphen (-) in shlibs variables. </para>
						<para>More advanced example: </para>
						<programlisting>

	Package: mypackage
	Depends: ${shlibs:mypackage:Depends}, perl5 | perl
	Suggests: ${mypackage:Suggests}, www-browser
	Recommends: mypackage-plugins, []
	
	Package: mypackage-bin
	Install: sh
	 yada shlibdeps
	
	Package: mypackage-libc++
	Depends: ${shlibs:mypackage-libc--:Depends}, [/usr/lib/mypackage/*]
</programlisting>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Provides, Conflicts, Replaces, Breaks</term>
					<listitem>
						<para>These fields affect the interaction between packages installed on the same system. They are fully documented in the Debian packaging manual. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Description</term>
					<listitem>
						<para>This field is fully documented in the Debian packaging manual. If the source package paragraph contains a multi-line "Description" field, its value (apart from the first line) will be prepended to the Description field of each binary package, separated by a blank line. The following fields are defined by YADA. Often, only the "Install" field need be used. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Tag</term>
					<listitem>
						<para>List  of  tags  describing  the  qualities  of  the package. See <command>debtags</command> package for description. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Install</term>
					<listitem>
						<para>An executable field, used to build the filesystem image for the binary package. This field is called with "binary" target and "binary-indep" target for "all" architecture or "binary-arch" for other architecture. </para>
						<para>Several extra commands are available: </para>
						<variablelist>
							<varlistentry>
								<term><command>yada</command> <option>install</option> <optional><option>-bin|-conf|-data|-dir|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script|-src|-sscript|-cgi</option></optional> <optional><option>-x|-non-x</option></optional> <optional><option>-stripped|-unstripped</option></optional> <optional><option>-exec|-no-exec</option></optional> <optional><option>-into <replaceable>dir</replaceable></option></optional> <optional><option>-as <replaceable>name</replaceable></option></optional> <optional><option>-subdir <replaceable>subdir</replaceable></option></optional> <optional><option>-lang <replaceable>lang</replaceable></option></optional> <optional><option>-section <replaceable>mansect</replaceable></option></optional> <optional><option>-gzip|-bzip2</option></optional> <optional><option>-ucf</option></optional> <replaceable>file</replaceable>... </term>
								<listitem>
									<para>Install the <replaceable>file</replaceable>s named into the binary package filesystem image. There are many options to affect how the installation is done. </para>
									<variablelist>
										<varlistentry>
											<term><option>-bin</option></term>
											<listitem>
												<para>Install user binaries (into <filename>/usr/bin</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-conf</option></term>
											<listitem>
												<para>Install configuration files (into <filename>/etc</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-data</option></term>
											<listitem>
												<para>Install data files. (This is the default.) </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-dir</option></term>
											<listitem>
												<para>Create directories in the filesystem image corresponding to each <replaceable>file</replaceable>, which should be specified as absolute pathnames on the installed destination system. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-doc</option></term>
											<listitem>
												<para>Install documentation files (into <filename>/usr/share/doc/<varname>$PACKAGE</varname></filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-game</option></term>
											<listitem>
												<para>Install game binaries (into <filename>/usr/games</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-include</option></term>
											<listitem>
												<para>Install include headers (into <filename>/usr/include</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-lib</option></term>
											<listitem>
												<para>Install shared libraries (into <filename>/usr/lib</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-libexec</option></term>
											<listitem>
												<para>Install additional executables (into <filename>/usr/lib</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-man</option></term>
											<listitem>
												<para>Install man pages (into <filename>/usr/man/man?</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-sbin</option></term>
											<listitem>
												<para>Install system binaries (into <filename>/usr/sbin</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-script</option></term>
											<listitem>
												<para>Install user scripts (into <filename>/usr/bin</filename>). It also means the same as unstripped, if there is no other file type specified. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-src</option></term>
											<listitem>
												<para>Install source files (into <filename>/usr/src</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-sscript</option></term>
											<listitem>
												<para>Install system scripts (into <filename>/usr/sbin</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-cgi</option></term>
											<listitem>
												<para>Install CGI files (into <filename>/usr/lib/cgi-bin</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-x</option></term>
											<listitem>
												<para>Install X-related files (they will be installed into the <filename>/usr/include/X11</filename> or <filename>/usr/lib/X11</filename> or <filename>/usr/share/X11</filename> hierarchy instead of into <filename>/usr</filename>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-non-x</option></term>
											<listitem>
												<para>Install ordinary, non-X-related files (the default). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-stripped</option></term>
											<listitem>
												<para>Strip the files after installing them (the default for binaries and shared libraries if environment variable <varname>DEB_BUILD_OPTIONS</varname> matches "nostrip" string). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-unstripped</option></term>
											<listitem>
												<para>Do not strip (the default for everything else). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-exec</option></term>
											<listitem>
												<para>Make the installed files executable (the default for binaries). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-no-exec</option></term>
											<listitem>
												<para>Make the installed files non-executable (the default for everything else). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
										<term><option>-into <replaceable>dir</replaceable></option></term>
											<listitem>
												<para>Override the normal destination directory with <replaceable>dir</replaceable> (specified as an absolute pathname on the destination system). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
										<term><option>-as <replaceable>name</replaceable></option></term>
											<listitem>
										<para>Rename the <replaceable>file</replaceable> to <replaceable>name</replaceable> when installing it (only available when installing a single <replaceable>file</replaceable>). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
										<term><option>-subdir <replaceable>subdir</replaceable></option></term>
											<listitem>
												<para>Put the file into a subdirectory of the location it would normally be installed into. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
										<term><option>-lang <replaceable>lang</replaceable></option></term>
											<listitem>
												<para>Add another subdirectory to the location it would normally be installed into. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
										<term><option>-section <replaceable>mansect</replaceable></option></term>
											<listitem>
										<para>Install man pages into section <replaceable>mansect</replaceable>, overriding yada's normal smarts for working out the appropriate section. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-gzip</option></term>
											<listitem>
												<para>Compress file with <command>gzip</command> <option>-9</option> after install. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-bzip2</option></term>
											<listitem>
												<para>Compress file with <command>bzip2</command> after install. </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-ucf</option></term>
											<listitem>
												<para>Use Update Configuration File (ucf) handling for configuration files. The original file will be installed into <filename>/usr/share/ucf/<replaceable>path</replaceable></filename> and additional ucf calls with <option>--three-way</option> option will be used in postinst and postrm scripts. This offers a chance to see a merge of the changes between old maintainer version and the new maintainer version into the local copy of the configuration file. </para>
											</listitem>
										</varlistentry>
									</variablelist>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>copy</option> <optional><option>-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script|-src|-sscript|-cgi</option></optional> <optional><option>-x|-non-x</option></optional>   <optional><option>-into <replaceable>dir</replaceable></option></optional> <optional><option>-as <replaceable>name</replaceable></option></optional> <optional><option>-subdir <replaceable>subdir</replaceable></option></optional> <optional><option>-lang <replaceable>lang</replaceable></option></optional> <optional><option>-section <replaceable>mansect</replaceable></option></optional>   <replaceable>file|dir</replaceable>... </term>
								<listitem>
									<para>Copy a <replaceable>file</replaceable> or <replaceable>dir</replaceable> with preserving file attributes into the binary package filesystem image. See <command>yada</command> <option>install</option> for additional arguments. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>move</option> <optional><option>-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script|-src|-sscript|-cgi</option></optional> <optional><option>-x|-non-x</option></optional>   <optional><option>-into <replaceable>dir</replaceable></option></optional> <optional><option>-as <replaceable>name</replaceable></option></optional> <optional><option>-subdir <replaceable>subdir</replaceable></option></optional> <optional><option>-lang <replaceable>lang</replaceable></option></optional> <optional><option>-section <replaceable>mansect</replaceable></option></optional>   <replaceable>file|dir</replaceable>... </term>
								<listitem>
									<para>Move a <replaceable>file</replaceable> or <replaceable>dir</replaceable> into the binary package filesystem image. See <command>yada</command> <option>install</option> for additional arguments. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>rename</option> <optional><option>-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script|-src|-sscript|-cgi</option></optional> <optional><option>-x|-non-x</option></optional>   <optional><option>-into <replaceable>dir</replaceable></option></optional> <optional><option>-as <replaceable>name</replaceable></option></optional> <optional><option>-subdir <replaceable>subdir</replaceable></option></optional> <optional><option>-lang <replaceable>lang</replaceable></option></optional> <optional><option>-section <replaceable>mansect</replaceable></option></optional>   <replaceable>file|dir</replaceable>... </term>
								<listitem>
									<para>Rename a <replaceable>file</replaceable> or <replaceable>dir</replaceable> in the binary package filesystem image. See <command>yada</command> <option>install</option> for additional arguments. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>symlink</option> <optional><option>-bin|-conf|-data|-doc|-game|-include|-lib|-libexec|-man|-sbin|-script|-src|-sscript|-cgi</option></optional> <optional><option>-x|-non-x</option></optional>   <optional><option>-into <replaceable>dir</replaceable></option></optional> <optional><option>-as <replaceable>name</replaceable></option></optional> <optional><option>-subdir <replaceable>subdir</replaceable></option></optional> <optional><option>-lang <replaceable>lang</replaceable></option></optional> <optional><option>-section <replaceable>mansect</replaceable></option></optional>   <replaceable>file|dir</replaceable>... </term>
								<listitem>
									<para>Make a symlink of <replaceable>file</replaceable> or <replaceable>dir</replaceable> as <replaceable>name</replaceable> in the binary package filesystem image. See <command>yada</command> <option>install</option> for additional arguments. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>undocumented</option> <optional><option>-x|-non-x</option></optional> <optional><option>-section <replaceable>mansect</replaceable></option></optional> <option><replaceable>name</replaceable></option>... </term>
								<listitem>
									<para>Mark the <replaceable>name</replaceable>s as undocumented, by creating manpage symlinks to <filename>undocumented.7</filename>. You can either give names with the man page section appended (e.g. <filename>foo.1</filename> or <filename>blurzle.3x</filename>) or give the section explicitly, in which case the names will not have suffixes which look like sections stripped. <option>-x</option> and <option>-non-x</option> work as for <command>yada</command> <option>install</option>. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>shlibdeps</option> <optional><option>args</option></optional> </term>
								<listitem>
									<para>This command finds the files execlutables and libraries which are dynamicaly linked. The command is called automatically, but you call use it explicity if you need to set <varname>LD_LIBRARY_PATH</varname> environment variable. All arguments will be passed to <citerefentry><refentrytitle>dpkg-shlibdeps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>makeshlibs</option> <optional><option>-V<optional><option><replaceable>deps</replaceable></option></optional>|--version<optional>=<replaceable>deps</replaceable></optional></option></optional> <optional><option>-X<replaceable>item</replaceable>|--exclude=<replaceable>item</replaceable></option></optional> </term>
								<listitem>
									<para>This command automatically scans for shared libraries, and generates a shlibs file for the libraries it finds. </para>
									<variablelist>
										<varlistentry>
											<term><option>-V<optional><replaceable>deps</replaceable></optional></option></term>
											<listitem>
												<para>By default, the shlibs file generated by this command program does not make packages depend on any particular version of the package containing the shared library. It may be necessary for you to add some version dependancy information to the shlibs file. If <option>-V</option> is specified with no dependancy information, the current version of the package is plugged into a dependancy that looks like "package-name (&gt;= packageversion)". If <option>-V</option> is specified with parameters, the parameters can be used to specify the exact dependancy information needed (be sure to include the package name). </para>
											</listitem>
										</varlistentry>
										<varlistentry>
											<term><option>-X<replaceable>item</replaceable></option></term>
											<listitem>
												<para>Exclude files that contain <replaceable>item</replaceable> anywhere in their filename from being treated as shared libraries. </para>
											</listitem>
										</varlistentry>
									</variablelist>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>strip</option> <optional><option>-X<replaceable>item</replaceable>|--exclude=<replaceable>item</replaceable></option></optional> </term>
								<listitem>
									<para>This command strips executables, shared libraries, and some static libraries. It assumes that files that have names like <filename>lib*_g.a</filename> are static libraries used in debugging, and will not strip them. The command is called automatically if environment variable <varname>DEB_BUILD_OPTIONS</varname> does not match "nostrip" string and the package doesn't have "Contains: unstripped" field. </para>
									<variablelist>
										<varlistentry>
											<term><option>-X<replaceable>item</replaceable></option></term>
											<listitem>
												<para>Exclude files that contain "item" anywhere in their filename from being stripped. You may use this option multiple times to build up a list of things to exclude. </para>
											</listitem>
										</varlistentry>
									</variablelist>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>patch <replaceable>patchfiles</replaceable></option> </term>
								<listitem>
									<para>This command applies patches that match command argument. See description of Patch field for more informations. The standalone using of yada patch command could be useful for conditional applying the patches. I.e.: </para>
									<programlisting>

	Build: sh
	 yada patch "debian/patches/any/*"
	 if [ "$DEB_BUILD_ARCH" = "i386" ]; then
	     yada patch "debian/patches/i386/*"
	 fi
 </programlisting>
									<para>The command is automatically called at the start of Build script if the Patch field is used. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term><command>yada</command> <option>unpatch</option> </term>
								<listitem>
									<para>This command removes all patches previously applied by yada patch command. The command is automatically called at the end of Clean script if the Patch field is used. If not, the command have to be called explicity: </para>
									<programlisting>

	Clean: sh
	 [...]
	 yada unpatch
 </programlisting>
								</listitem>
							</varlistentry>
						</variablelist>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Finalise (or Finalize)</term>
					<listitem>
						<para>After the "Install" field is executed, all user and group ownerships in the filesystem image are set to "root", and all permissions are set to "rwxr-xr-x" for directories and for plain files which have an execute bit already set, and "rw-r--r--" for all other plain files. The Finalise executable field is used to set up any permissions or ownerships needed in the filesystem image which differ from the defaults. </para>
						<para>The <varname>ROOT</varname>, <varname>CONTROL</varname>, <varname>PACKAGE</varname>, <varname>VERSION</varname> and <varname>DEB_*</varname> variables are available as in the "Install" field. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Preinst, Postinst, Prerm, Postrm, Config</term>
					<listitem>
						<para>These executable fields are transformed into the maintainer scripts for the binary package. Several common tasks done by maintainer scripts are prepended automatically if certain other fields are specified. The <varname>PACKAGE</varname> and <varname>VERSION</varname> variables are set for these fields. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Templates</term>
					<listitem>
						<para>If this field is specified, its value is placed into a control file "templates" used by debconf system. The YADA supports <citerefentry><refentrytitle>po-debconf</refentrytitle><manvolnum>7</manvolnum></citerefentry> system, so translatable fields can be prepended with an underscore. If the file <filename>debian/po/templates.pot</filename> exists, the <citerefentry><refentrytitle>po2debconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> command for merging translations are called at build time. </para>
						<para>You can update <filename>debian/po/</filename> directory with <citerefentry><refentrytitle>debconf-updatepo</refentrytitle><manvolnum>1</manvolnum></citerefentry> command. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Doc-Depends</term>
					<listitem>
						<para>Normally, YADA creates a directory named <filename>/usr/share/doc/<replaceable>package</replaceable>/</filename> automatically and places the copyright file and changelogs in it. If the package depends on another binary package, created by the same source package, whose <filename>/usr/share/doc/<replaceable>package</replaceable>/</filename> directory is appropriate, give that package's name as the value of this field, and an appropriate symlink will be created. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Alternatives</term>
					<listitem>
						<para>If your package includes files to be registered using <citerefentry><refentrytitle>update-alternatives</refentrytitle><manvolnum>8</manvolnum></citerefentry>, specify them using this field. Please read the man page for <citerefentry><refentrytitle>update-alternatives</refentrytitle><manvolnum>8</manvolnum></citerefentry> to understand the terminology in the following. Each alternative to be installed is specified by a single line. </para>
						<para>Master links are specified by a line containing the full generic pathname, followed by the name of the symlink in the alternatives directory, followed by the full pathname of the alternative, followed by the priority of the alternative. The three names are separated by right-arrows (each made of a hyphen followed by a greater-than symbol: "-&gt;"), and the priority is surrounded by round brackets (parentheses). </para>
						<para>Slave links are specified by a line starting with two greater-than symbols ("&gt;&gt;"), followed by the full generic pathname, followed by the name of the slave symlink in the alternatives directory, followed by the full pathname of the alternative. The three names are separated by right-arrows (each made of a hyphen followed by a greater-than symbol: "-&gt;"). Each line describing a slave link is grouped together with the master link most recently described. </para>
						<para>An example: </para>
						<programlisting>

	Alternatives:
	 /usr/bin/editor -&gt; editor -&gt; /usr/bin/nvi (30)
	 &gt;&gt; /usr/man/man1/editor.1.gz -&gt; editor.1.gz -&gt; /usr/man/man1/nvi.1.gz 
</programlisting>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Diversions</term>
					<listitem>
						<para>If your package includes files to be registered using <citerefentry><refentrytitle>dpkg-divert</refentrytitle><manvolnum>8</manvolnum></citerefentry>, specify them using this field. Please read the man page for <citerefentry><refentrytitle>dpkg-divert</refentrytitle><manvolnum>8</manvolnum></citerefentry> to understand the terminology in the following. Each diversion to be installed is specified by a single line. The diversion is specified by a line containing the path of overriding file, followed by the path of overriden file. The two names are separated by right-arrows (each made of a hyphen followed by a greater-than symbol: "-&gt;"). </para>
						<para>An example: </para>
						<programlisting>

	Diversions:
	 /usr/sbin/smail -&gt; /usr/sbin/smail.real
 </programlisting>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Menu</term>
					<listitem>
						<para>If this field is specified, its value is placed into a file in the <filename>/usr/lib/menu/</filename> directory, and <citerefentry><refentrytitle>update-menus</refentrytitle><manvolnum>8</manvolnum></citerefentry> is called at the appropriate moments during package installation and removal. See <citerefentry><refentrytitle>menufile</refentrytitle><manvolnum>5</manvolnum></citerefentry> for documentation on how to write this field. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Init</term>
					<listitem>
						<para>This executable field is transformed into the init script placed in <filename>/etc/init.d/</filename> directory, and <citerefentry><refentrytitle>update-rc.d</refentrytitle><manvolnum>8</manvolnum></citerefentry> is called at the appropriate moments during package installation and removal. The first line of this script have to contain the arguments for <citerefentry><refentrytitle>update-rc.d</refentrytitle><manvolnum>8</manvolnum></citerefentry> command. If the init script name is ommited (the first argument), then the package name is used. </para>
						<para>An example: </para>
						<programlisting>

	Init: sh
	 defaults 20
	 # The example init script
	 #
	 # The first line contains arguments for update-rc.d
	 # The first argument is ommited, so the full string might be:
	 # package-name defaults 20
	 #
	 NAME=daemon
	 DAEMON=/usr/bin/daemon
	 case "$1" in
	   start)
	     start-stop-daemon --start --quiet --pidfile /var/run/$NAME.pid \
	       --exec $DAEMON;;
	   stop)
	     start-stop-daemon --stop --quiet --pidfile /var/run/$NAME.pid \
	       --exec $DAEMON;;
	 esac
 </programlisting>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Logrotate</term>
					<listitem>
						<para>If this field is specified, its value is placed into a file in the <filename>/etc/logrotate/</filename> directory. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Cron</term>
					<listitem>
						<para>If this field is specified, its value is used as system-wide crontab file in the <filename>/etc/cron.d/</filename> directory. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Cron-Hourly, Cron-Daily, Cron-Weekly, Cron-Monthly</term>
					<listitem>
						<para>These executable fields are transformed into the system-wide crontab scripts for the binary package. These scripts will be installed into <filename>/etc/cron.{hourly,daily,weekly,monthly}</filename> directories. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Modutils</term>
					<listitem>
						<para>If this field is specified, its value is placed into a file in the <filename>/etc/modutils/</filename> directory. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Pam</term>
					<listitem>
						<para>If this field is specified, its value is placed into a file in the <filename>/etc/pam.d/</filename> directory. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Shlibs</term>
					<listitem>
						<para>If this field is specified, its value is used as the contents of the package's "shlibs" control area file. </para>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Contains</term>
					<listitem>
						<para>This field controls additional calls from maintainer's scripts. The value is a list of tags: </para>
						<variablelist>
							<varlistentry>
								<term>libs</term>
								<listitem>
									<para>Assumes the package contains shared libraries, and calls <citerefentry><refentrytitle>ldconfig</refentrytitle><manvolnum>8</manvolnum></citerefentry> at the appropriate point during package installation. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term>unstripped</term>
								<listitem>
									<para>Assumes the package contains unstripped binaries, so it is not stripped automatically by <command>yada</command> <option>strip</option>. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term>xfonts</term>
								<listitem>
									<para>Assumes the package contains X Window System's fonts, and calls <citerefentry><refentrytitle>update-fonts-alias</refentrytitle><manvolnum>8</manvolnum></citerefentry> and <citerefentry><refentrytitle>update-fonts-scale</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para>
								</listitem>
							</varlistentry>
							<varlistentry>
								<term>kernel-modules</term>
								<listitem>
									<para>Assumes the package contains kernel modules, and this package can be used with <citerefentry><refentrytitle>make-kpkg</refentrytitle><manvolnum>1</manvolnum></citerefentry> utility. It also doesn't strip binaries. </para>
								</listitem>
							</varlistentry>
						</variablelist>
						<para>An example: </para>
						<programlisting>

	Contains: libs
</programlisting>
					</listitem>
				</varlistentry>
				<varlistentry>
					<term>Overrides</term>
					<listitem>
						<para>Lintian is a Debian package checker which generates information about policy violations of package. The format of Lintian's output is: </para>
						<screen>


	X: package: full information about violation
</screen>
						<para>i.e.: </para>
						<screen>


	W: securecgi: setuid-binary usr/lib/cgi-bin/securecgi 4755 root/root
</screen>
						<para>The Overrides field allows to ignore some Lintian's messages. In this example, to ignore above message it is required to put the Overrides field at binary section: </para>
						<programlisting>

	Package: securecgi
	Overrides: setuid-binary usr/lib/cgi-bin/securecgi 4755 root/root
</programlisting>
					</listitem>
				</varlistentry>
			</variablelist>
		</sect2>
	</sect1>
	<sect1>
		<title>Macro preprocessor</title>
		<para>Macro preprocessor resolves all macro commands and macro variables used in <filename>debian/packages</filename>file and produces a temporary file <filename>debian/packages-tmp</filename>. </para>
		<para>Macro commands begin with percent mark ("%"): </para>
		<variablelist>
			<varlistentry>
				<term>%define</term>
				<listitem>
					<para>Definition of macro variable. This variable can be used further in common section or another macro command. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%include</term>
				<listitem>
					<para>The preprocessor will include another file specified as parameter for this macro command. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%if, %else, %endif</term>
				<listitem>
					<para>These macro commands are used to make conditional skipping. The first should be followed by text. If the condition text is not equal 0 or is not an empty string then the condition is true. The conditional macro commands can be nested. </para>
				</listitem>
			</varlistentry>
		</variablelist>
		<para>Macro variables: </para>
		<variablelist>
			<varlistentry>
				<term>%{MACRO_VAR}</term>
				<listitem>
					<para>Expands to variable predefined with "%define" command or generates warning if the variable is not defined already. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%{$ENV_VAR}</term>
				<listitem>
					<para>Expands to environment variable. If variable is not defined, expands to empty string. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%{?MACRO_VAR:string}</term>
				<listitem>
					<para>Expands to given string if macro variable is set and its value is true. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%{!?MACRO_VAR:string}</term>
				<listitem>
					<para>Expands to given string if macro variable is not defined or its value is not true. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%{?$ENV_VAR:string}</term>
				<listitem>
					<para>Expands to given string if environment variable is set and its value is true. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%{!?$ENV_VAR:string}</term>
				<listitem>
					<para>Expands to given string if environment variable is not defined or its value is not true. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>%`command`</term>
				<listitem>
					<para>Executes given command and expands to its output. </para>
				</listitem>
			</varlistentry>
		</variablelist>
		<para>There are following predefined macro variables: </para>
		<variablelist>
			<varlistentry>
				<term><varname>VERSION</varname></term>
				<listitem>
					<para>Defines the version of the source package. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><varname>SOURCE</varname></term>
				<listitem>
					<para>Defines the name of the source package. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><varname>YADA_COMMAND</varname></term>
				<listitem>
					<para>Defines how YADA program is called. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><varname>YADA_VERSION</varname></term>
				<listitem>
					<para>Defines YADA version. Internal version name is overriden by <varname>$YADA_VERSION</varname> environment variable. This setting it is used in generated Build-Depends field from <filename>debian/control</filename>file. </para>
				</listitem>
			</varlistentry>
		</variablelist>
		<para>There are following special macro variables: </para>
		<variablelist>
			<varlistentry>
				<term><varname>with_*</varname>, <varname>without_*</varname></term>
				<listitem>
					<para>If %{with_*} macro is set, then %{without_*} macro is unset. If %{without_*} macro is set, then %{with_*} macro is unset. If <varname>$YADA_WITH_*</varname> environment variable is set, it is used as %{with_*} macro variable, and its name is converted from uppercase to lowercase. If <varname>$YADA_WITHOUT_*</varname> environment variable is set, it is used as %{without_*} macro variable, and its name is converted from uppercase to lowercase. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><varname>DEB_BUILD_*</varname>, <varname>DEB_HOST_*</varname></term>
				<listitem>
					<para>These macro variables are set based on <citerefentry><refentrytitle>dpkg-architecture</refentrytitle><manvolnum>1</manvolnum></citerefentry> command output. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><varname>with_DEB_BUILD_*</varname>, <varname>without_DEB_BUILD_*</varname>, <varname>with_DEB_HOST_*</varname>, <varname>without_DEB_HOST_*</varname></term>
				<listitem>
					<para>These macro variables are set based on <citerefentry><refentrytitle>dpkg-architecture</refentrytitle><manvolnum>1</manvolnum></citerefentry> command output. If, i.e. %{DEB_HOST_ARCH} is set to "i386", then %{with_DEB_HOST_ARCH_i386} macro is set. </para>
				</listitem>
			</varlistentry>
		</variablelist>
		<para>Macro variables can be nested. </para>
		<para>The example usage of macro preprocessor: </para>
		<programlisting>

	%define KSRC %{?$KSRC:%{$KSRC}}%{!?$KSRC:/usr/src/linux}
	%define KVERS %{?$KVERS:%{$KVERS}}%{!?$KVERS:%`sed -n -e '/UTS_RELEASE/s/^[^"]*"\([^"]*\
	%define KDREV %{?$KDREV:%{$KDREV}}%{!?$KDREV:UNKNOWN}
	%define APPEND_TO_VERSION %{$APPEND_TO_VERSION}
	%define FLAVOUR %{$FLAVOUR}
	%define KMAINT %{?$KMAINT:%{$KMAINT}}%{!?$KMAINT:%{$DEBFULLMAIL}}
	%define KEMAIL %{?$KEMAIL:%{$KEMAIL}}%{!?$KEMAIL:%{$DEBEMAIL}}
	
	Source: foo-modules-source
	Build-Depends: yada (&gt;= %{YADA_VERSION})
	[...]
	
	Package: foo-modules-%{KVERS}
	Architecture: any
	%if %{KDREV}
	Recommends: kernel-image-%{KVERS} (= %{KDREV})
	%else
	Recommends: kernel-image-%{KVERS}
	%endif
	Description: Some foo kernel modules
	 The example usage of YADA macro preprocessor.
	Contains: unstripped
	Install: sh
	%if %{with_foo}
	 yada install -lib -unstripped -into /lib/modules/%{KVERS}/kernel/foo src/foo.o
	%endif
	[...]
</programlisting>
	</sect1>
	<sect1>
		<title>FAQ</title>
		<variablelist>
			<varlistentry>
				<term>Q:</term>
				<listitem>
					<para>How to make a backport for a package which uses YADA? </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>A:</term>
				<listitem>
					<para>If YADA is not available for older distribution release, copy the <filename>/usr/bin/yada</filename> into <filename>debian/</filename> subdirectory and call <command>debian/yada</command> <option>rebuild</option>. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Q:</term>
				<listitem>
					<para>Can I export DebConf templates or other script to external file? </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>A:</term>
				<listitem>
					<para>You can use macro commands. Example <filename>debian/package</filename> file: </para>
					<programlisting>

	Package: mypackage
	Depends: otherpackage, []
	Install:
	 # some installing commands
	Templates:
	%`sed -e 's/^$/./' -e 's/^/ /' debian/packages.templates`
	# no space in first row!
	Config: sh
	[...]
</programlisting>
					<para>Example debian/package.templates file: </para>
					<programlisting>

	Template: %{PACKAGE}/debconf-template
	Type: note
	Description: DebConf template in external file
	 As you might see, you can use macros in the template file.
</programlisting>
					<para>Don't use <filename>debian/templates</filename> file. This file is automatically created based on <filename>debian/packages</filename>file. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Q:</term>
				<listitem>
					<para>How YADA supports po-debconf? </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>A:</term>
				<listitem>
					<para>Run <command>yada</command> <option>rebuild templates</option> and then <command>debconf-gettextize</command> or <command>debconf-updatepo</command>. Delete <filename>debian/templates</filename> file after all. </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Q:</term>
				<listitem>
					<para>Is there any syntax highlighting for <filename>debian/packages</filename>? </para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>A:</term>
				<listitem>
					<para>There is a file prepared for Midnight Commander. You can find <filename>debian-control.syntax</filename> file in documentation directory, then put it into <filename>~/.mc/cedit</filename> directory. Make sure there is a line in <filename>~/.mc/cedit/Syntax</filename> file: </para>
					<programlisting>

	file (control|packages)$ Debian\scontrol\sfile
	include debian-control.syntax
</programlisting>
				</listitem>
			</varlistentry>
		</variablelist>
	</sect1>
</article>