+subset needed, and thus save some disk space).
+ <p>
+The second case can be easily managed in <file>debian/rules</file>.
+You just need to move the appropriate files from the build directory
+into the package's temporary trees. You can do this using
+<prgn>install</prgn> or <prgn>dh_install</prgn>
+from <package>debhelper</package>. Be sure to check the different
+permutations of the various packages, ensuring that you have the
+inter-package dependencies set right in <file>debian/control</file>.
+ <p>
+The first case is a bit more difficult since it involves multiple
+recompiles of the same software but with different configuration
+options. The <package>vim</package> source package is an example of how to manage
+this using an hand-crafted <file>debian/rules</file> file.
+
+<!-- &FIXME; Find a good debhelper example with multiple configure/make
+ cycles -->
+ </sect1>
+ </sect>
+
+
+ <sect id="bpp-debian-control">
+ <heading>Best practices for <file>debian/control</file></heading>
+ <p>
+The following practices are relevant to the
+<file>debian/control</file> file. They supplement the <url
+id="&url-debian-policy;ch-binary.html#s-descriptions"
+name="Policy on package descriptions">.
+ <p>
+The description of the package, as defined by the corresponding field
+in the <file>control</file> file, contains both the package synopsis
+and the long description for the package. <ref id="bpp-desc-basics">
+describes common guidelines for both parts of the package description.
+Following that, <ref id="bpp-pkg-synopsis"> provides guidelines
+specific to the synopsis, and <ref id="bpp-pkg-desc"> contains
+guidelines specific to the description.
+
+ <sect1 id="bpp-desc-basics">
+ <heading>General guidelines for package descriptions</heading>
+ <p>
+The package description should be written for the average likely user,
+the average person who will use and benefit from the package. For
+instance, development packages are for developers, and can be
+technical in their language. More general-purpose applications, such
+as editors, should be written for a less technical user.
+ <p>
+Our review of package descriptions lead us to conclude that most
+package descriptions are technical, that is, are not written to make
+sense for non-technical users. Unless your package really is only for
+technical users, this is a problem.
+ <p>
+How do you write for non-technical users? Avoid jargon. Avoid
+referring to other applications or frameworks that the user might not
+be familiar with — "GNOME" or "KDE" is fine, since users are
+probably familiar with these terms, but "GTK+" is
+probably not. Try not to assume any knowledge at all. If you must
+use technical terms, introduce them.
+ <p>
+Be objective. Package descriptions are not the place for advocating
+your package, no matter how much you love it. Remember that the
+reader may not care about the same things you care about.
+ <p>
+References to the names of any other software packages, protocol names,
+standards, or specifications should use their canonical forms, if one
+exists. For example, use "X Window System", "X11", or "X"; not "X
+Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
+Use "GNOME", not "Gnome". Use "PostScript", not "Postscript" or
+"postscript".
+ <p>
+If you are having problems writing your description, you may wish to
+send it along to &email-debian-l10n-english; and request feedback.
+ </sect1>
+
+
+ <sect1 id="bpp-pkg-synopsis">
+ <heading>The package synopsis, or short description</heading>
+ <p>
+The synopsis line (the short description) should be concise. It
+must not repeat the package's name (this is policy).
+ <p>
+It's a good idea to think of the synopsis as an appositive clause, not
+a full sentence. An appositive clause is defined in WordNet as a
+grammatical relation between a word and a noun phrase that follows,
+e.g., "Rudolph the red-nosed reindeer". The appositive clause here is
+"red-nosed reindeer". Since the synopsis is a clause, rather than a
+full sentence, we recommend that it neither start with a capital nor
+end with a full stop (period). It should also not begin with an
+article, either definite ("the") or indefinite ("a" or "an").
+ <p>
+It might help to imagine that the synopsis is combined with the
+package name in the following way:
+
+<example><var>package-name</var> is a <var>synopsis</var>.</example>
+
+Alternatively, it might make sense to think of it as
+
+<example><var>package-name</var> is <var>synopsis</var>.</example>
+
+or, if the package name itself is a plural (such as
+"developers-tools")
+
+<example><var>package-name</var> are <var>synopsis</var>.</example>
+
+This way of forming a sentence from the package name and synopsis
+should be considered as a heuristic and not a strict rule. There are
+some cases where it doesn't make sense to try to form a sentence.
+ </sect1>
+
+ <sect1 id="bpp-pkg-desc">
+ <heading>The long description</heading>
+ <p>
+The long description is the primary information available to the user
+about a package before they install it. It should provide all the
+information needed to let the user decide whether to install the
+package. Assume that the user has already read the package synopsis.
+ <p>
+The long description should consist of full and complete sentences.
+ <p>
+The first paragraph of the long description should answer the
+following questions: what does the package do? what task does it help
+the user accomplish? It is important to describe this in a
+non-technical way, unless of course the audience for the package is
+necessarily technical.
+ <p>
+The following paragraphs should answer the following questions: Why do
+I as a user need this package? What other features does the package
+have? What outstanding features and deficiencies are there compared
+to other packages (e.g., "if you need X, use Y instead")? Is this
+package related to other packages in some way that is not handled by
+the package manager (e.g., "this is the client for the foo server")?
+ <p>
+Be careful to avoid spelling and grammar mistakes. Ensure that you
+spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
+for <file>debian/control</file> files:
+
+<example>ispell -d american -g debian/control</example>
+ <p>
+Users usually expect these questions to be answered in the package
+description:
+ <list>
+ <item>
+What does the package do? If it is an add-on to another package,
+then the short description of the package we are an add-on to
+should be put in here.
+ <item>
+Why should I want this package? This is related to the above,
+but not the same (this is a mail user agent; this is cool, fast,
+interfaces with PGP and LDAP and IMAP, has features X, Y, and Z).
+ <item>
+If this package should not be installed directly, but is pulled in
+by another package, this should be mentioned.
+ <item>
+If the package is experimental, or there are other reasons it
+should not be used, if there are other packages that should be
+used instead, it should be here as well.
+ <item>
+How is this package different from the competition? Is it a better
+implementation? more features? different features? Why should I
+choose this package.
+<!-- FIXME: what's this?
+(the second questions is about the class of packages, and
+this about this particular package, if you have information related to both).
+-->
+ </list>
+
+ </sect1>
+
+
+ <sect1 id="bpp-upstream-info">
+ <heading>Upstream home page</heading>
+ <p>
+We recommend that you add the URL for the package's home page to the
+package description in <file>debian/control</file>. This information
+should be added at the
+end of description, using the following format:
+
+<example> .
+ Homepage: http://some-project.some-place.org/</example>
+
+Note the spaces prepending the line, which serves to break the lines
+correctly. To see an example of how this displays, see <url
+id="&url-eg-desc-upstream-info;">.
+ <p>
+If there is no home page for the software, this should naturally be
+left out.
+ <p>
+Note that we expect this field will eventually be replaced by a proper
+<file>debian/control</file> field understood by <prgn>dpkg</prgn> and
+<tt>&packages-host;</tt>. If you don't want to bother migrating the
+home page from the description to this field, you should probably wait
+until that is available.</p>
+ </sect1>
+ </sect>
+
+
+ <sect id="bpp-debian-changelog">
+ <heading>Best practices for <file>debian/changelog</file></heading>
+ <p>
+The following practices supplement the <url name="Policy on changelog
+files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
+
+ <sect1 id="bpp-changelog-do">
+ <heading>Writing useful changelog entries</heading>
+ <p>
+The changelog entry for a package revision documents changes in that
+revision, and only them. Concentrate on describing significant and
+user-visible changes that were made since the last version.
+ <p>
+Focus on <em>what</em> was changed — who, how and when are
+usually less important. Having said that, remember to politely
+attribute people who have provided notable help in making the package
+(e.g., those who have sent in patches).
+ <p>
+There's no need to elaborate the trivial and obvious changes. You can
+also aggregate several changes in one entry. On the other hand, don't
+be overly terse if you have undertaken a major change. Be especially
+clear if there are changes that affect the behaviour of the program.
+For further explanations, use the <file>README.Debian</file> file.
+ <p>
+Use common English so that the majority of readers can comprehend it.
+Avoid abbreviations, "tech-speak" and jargon when explaining changes
+that close bugs, especially for bugs filed by users that did not
+strike you as particularly technically savvy. Be polite, don't swear.
+ <p>
+It is sometimes desirable to prefix changelog entries with the names
+of the files that were changed. However, there's no need to
+explicitly list each and every last one of the changed files,
+especially if the change was small or repetitive. You may use
+wildcards.
+ <p>
+When referring to bugs, don't assume anything. Say what the problem
+was, how it was fixed, and append the "closes: #nnnnn" string. See
+<ref id="upload-bugfix"> for more information.
+
+
+ <sect1 id="bpp-changelog-misconceptions">
+ <heading>Common misconceptions about changelog entries</heading>
+ <p>
+The changelog entries should <strong>not</strong> document generic
+packaging issues ("Hey, if you're looking for foo.conf, it's in
+/etc/blah/."), since administrators and users are supposed to be at
+least remotely acquainted with how such things are generally arranged
+on Debian systems. Do, however, mention if you change the location of
+a configuration file.
+ <p>
+The only bugs closed with a changelog entry should be those that are
+actually fixed in the same package revision. Closing unrelated bugs
+in the changelog is bad practice. See <ref id="upload-bugfix">.
+ <p>
+The changelog entries should <strong>not</strong> be used for random
+discussion with bug reporters ("I don't see segfaults when starting
+foo with option bar; send in more info"), general statements on life,
+the universe and everything ("sorry this upload took me so long, but I
+caught the flu"), or pleas for help ("the bug list on this package is
+huge, please lend me a hand"). Such things usually won't be noticed
+by their target audience, but may annoy people who wish to read
+information about actual changes in the package. See <ref
+id="bug-answering"> for more information on how to use the bug
+tracking system.
+ <p>
+It is an old tradition to acknowledge bugs fixed in non-maintainer
+uploads in the first changelog entry of the proper maintainer upload,
+for instance, in a changelog entry like this:
+<example>
+ * Maintainer upload, closes: #42345, #44484, #42444.
+</example>
+This will close the NMU bugs tagged "fixed" when the package makes
+it into the archive. The bug for the fact that an NMU was done can be
+closed the same way. Of course, it's also perfectly acceptable to
+close NMU-fixed bugs by other means; see <ref id="bug-answering">.
+ </sect1>
+
+ <sect1 id="bpp-changelog-errors">
+ <heading>Common errors in changelog entries</heading>
+ <p>
+The following examples demonstrate some common errors or example of
+bad style in changelog entries.
+
+ <p>
+<example>
+ * Fixed all outstanding bugs.
+</example>
+This doesn't tell readers anything too useful, obviously.
+
+ <p>
+<example>
+ * Applied patch from Jane Random.
+</example>
+What was the patch about?
+
+ <p>
+<example>
+ * Late night install target overhaul.
+</example>
+Overhaul which accomplished what? Is the mention of late night
+supposed to remind us that we shouldn't trust that code?
+
+ <p>
+<example>
+ * Fix vsync FU w/ ancient CRTs.
+</example>
+Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
+a curse word!) was actually about, or how it was fixed.
+
+ <p>
+<example>
+ * This is not a bug, closes: #nnnnnn.
+</example>
+First of all, there's absolutely no need to upload the package to
+convey this information; instead, use the bug tracking system.
+Secondly, there's no explanation as to why the report is not a bug.
+
+ <p>
+<example>
+ * Has been fixed for ages, but I forgot to close; closes: #54321.
+</example>
+If for some reason you didn't mention the bug number in a previous changelog
+entry, there's no problem, just close the bug normally in the BTS. There's
+no need to touch the changelog file, presuming the description of the fix is
+already in (this applies to the fixes by the upstream authors/maintainers as
+well, you don't have to track bugs that they fixed ages ago in your
+changelog).
+
+ <p>
+<example>
+ * Closes: #12345, #12346, #15432
+</example>
+Where's the description? If you can't think of a descriptive message,
+start by inserting the title of each different bug.
+ </sect1>
+
+ <sect1 id="bpp-news-debian">
+ <heading>Supplementing changelogs with NEWS.Debian files</heading>
+ <p>
+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 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 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 miss such notes.
+ <p>
+The file format is the same as a debian changelog file, but leave off
+the asterisks and describe each news item with a full paragraph when
+necessary rather than the more concise summaries that would go in a
+changelog. It's a good idea to run your file through dpkg-parsechangelog to
+check its formatting as it will not be automatically checked during build
+as the changelog is. Here is an example of a real NEWS.Debian file:
+<example>
+cron (3.0pl1-74) unstable; urgency=low
+
+ The checksecurity script is no longer included with the cron package:
+ it now has its own package, "checksecurity". If you liked the
+ functionality provided with that script, please install the new
+ package.
+
+ -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
+</example>
+ <p>
+The NEWS.Debian file is installed as
+/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and
+always has that name even in Debian native packages. If you use debhelper,
+dh_installchangelogs will install debian/NEWS files for you.
+ <p>
+Unlike changelog files, you need not update NEWS.Debian files with every
+release. Only update them if you have something particularly newsworthy
+that user should know about. If you have no news at all, there's no need
+to ship a NEWS.Debian file in your package. No news is good news!
+ </sect>
+
+<!--
+ <sect1 id="pkg-mgmt-cvs">Managing a package with CVS
+ <p>
+ &FIXME; presentation of cvs-buildpackage, updating sources
+ via CVS (debian/rules refresh).
+ <url id="http://www.debian.org/devel/cvs_packages">
+-->
+
+
+ <sect id="bpp-debian-maint-scripts">
+ <heading>Best practices for maintainer scripts</heading>
+ <p>
+Maintainer scripts include the files <file>debian/postinst</file>,
+<file>debian/preinst</file>, <file>debian/prerm</file> and
+<file>debian/postrm</file>. These scripts take care of any package
+installation or deinstallation setup which isn't handled merely by the
+creation or removal of files and directories. The following
+instructions supplement the <url id="&url-debian-policy;" name="Debian
+Policy">.
+ <p>
+Maintainer scripts must be idempotent. That means that you need to
+make sure nothing bad will happen if the script is called twice where
+it would usually be called once.
+ <p>
+Standard input and output may be redirected (e.g. into pipes) for
+logging purposes, so don't rely on them being a tty.
+ <p>
+All prompting or interactive configuration should be kept to a
+minimum. When it is necessary, you should use the
+<package>debconf</package> package for the interface. Remember that
+prompting in any case can only be in the <tt>configure</tt> stage of
+the <file>postinst</file> script.
+ <p>
+Keep the maintainer scripts as simple as possible. We suggest you use
+pure POSIX shell scripts. Remember, if you do need any bash features,
+the maintainer script must have a bash shebang line. POSIX shell or
+Bash are preferred to Perl, since they enable
+<package>debhelper</package> to easily add bits to the scripts.
+ <p>
+If you change your maintainer scripts, be sure to test package
+removal, double installation, and purging. Be sure that a purged
+package is completely gone, that is, it must remove any files created,
+directly or indirectly, in any maintainer script.
+ <p>
+If you need to check for the existence of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hard-code the path of a command in your
+maintainer script, the following POSIX-compliant shell function may
+help:
+
+&example-pathfind;
+
+You can use this function to search <tt>$PATH</tt> for a command name,
+passed as an argument. It returns true (zero) if the command was
+found, and false if not. This is really the most portable way, since
+<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
+POSIX.
+ <p>
+While <prgn>which</prgn> is an acceptable alternative, since
+it is from the required <package>debianutils</package> package, it's
+not on the root partition. That is, it's in <file>/usr/bin</file> rather
+than <file>/bin</file>, so one can't use it in scripts which are run
+before the <file>/usr</file> partition is mounted. Most scripts won't have
+this problem, though.
+ </sect>
+
+
+ <sect id="bpp-config-mgmt">
+ <heading>Configuration management with <package>debconf</package></heading>
+ <p>
+<package>Debconf</package> is a configuration management system which
+can be used by all the various packaging scripts
+(<file>postinst</file> mainly) to request feedback from the user
+concerning how to configure the package. Direct user interactions must
+now be avoided in favor of <package>debconf</package>
+interaction. This will enable non-interactive installations in the
+future.
+ <p>
+Debconf is a great tool but it is often poorly used. Many common mistakes
+are listed in the <manref name="debconf-devel" section="7"> man page.
+It is something that you must read if you decide to use debconf.
+Also, we document some best practices here.
+ <p>
+These guidelines include some writing style and typography
+recommendations, general considerations about debconf usage as well as
+more specific recommendations for some parts of the distribution (for
+instance, the installation system).
+
+ <sect1>Do not abuse debconf
+ <p>
+Since debconf appeared in Debian, it has been widely abused and
+several criticisms received by the Debian distribution come from
+debconf abuse with the need of answering a wide bunch of questions
+before getting any little thing installed.
+ <p>
+Keep usage notes to what they belong: the NEWS.Debian, or
+README.Debian file. Only use notes for important notes which may
+directly affect the package usability. Remember that notes will always
+block the install until confirmed or bother the user by email.
+ <p>
+Carefully choose the questions priorities in maintainer scripts. See
+<manref name="debconf-devel" section="7"> for details about priorities.
+Most questions should use medium and low priorities.
+
+ <sect1>General recommendations for authors and translators
+ <p>
+ <sect2>Write correct English
+ <p>
+Most Debian package maintainers are not native English speakers. So,
+writing properly phrased templates may not be easy for them.
+ <p>
+Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+list. Have your templates proofread.
+ <p>
+Badly written templates give a poor image of your package, of your
+work...or even of Debian itself.
+ <p>
+Avoid technical jargon as much as possible. If some terms sound common
+to you, they may be impossible to understand for others. If you cannot
+avoid them, try to explain them (use the extended description). When
+doing so, try to balance between verbosity and simplicity.
+
+ <sect2>Be kind to translators
+ <p>
+Debconf templates may be translated. Debconf, along with its sister
+package po-debconf offers a simple framework for getting
+templates translated by translation teams or even individuals.
+ <p>
+Please use gettext-based templates. Install po-debconf on your
+development system and read its documentation ("man po-debconf" is a
+good start).
+ <p>
+Avoid changing templates too often. Changing templates text induces
+more work to translators which will get their translation "fuzzied". If
+you plan changes to your original templates, please contact
+translators. Most active translators are very reactive and getting
+their work included along with your modified templates will save you
+additional uploads. If you use gettext-based templates, the
+translator's name and e-mail addresses are mentioned in the po files
+headers.
+ <p>
+If in doubt, you may also contact the translation team for a given
+language (debian-l10n-xxxxx@lists.debian.org), or the
+debian-i18n@lists.debian.org mailing list.
+
+ <sect2>Do not make assumptions about interfaces
+ <p>
+Templates text should not make reference to widgets belonging to some
+debconf interfaces. Sentences like "If you answer Yes..." have no
+meaning for users of graphical interfaces which use checkboxes for
+boolean questions.
+ <p>
+More generally speaking, try to avoid referring to user actions.
+Just give facts.
+
+ <sect2>Do not use first person
+ <p>
+You should avoid the use of first person ("I will do this..." or "We
+recommend..."). The computer is not a person and the Debconf tempaltes
+do not speak for the Debian developers. You should use neutral
+construction and often the passive form. Those of you who already
+wrote scientific publications, just write your templates like you
+would write a scientific paper.
+
+ <sect2>Be gender neutral
+ <p>
+The world is made of men and women. Please use gender-neutral
+constructions in your writing. This is not Political Correctness, this
+is showing respect to all humanity.
+
+
+ <sect1>Templates fields definition
+ <p>
+This part gives some information which is mostly taken from the
+<manref name="debconf-devel" section="7"> manual page.
+
+ <sect2>Type
+ <p>
+
+ <sect3>string:
+ <p>
+Results in a free-form input field that the user can type any string into.
+
+ <sect3>password:
+ <p>
+Prompts the user for a password. Use this with caution; be aware that
+the password the user enters will be written to debconf's
+database. You should probably clean that value out of the database as
+soon as is possible.
+
+ <sect3>boolean:
+ <p>
+A true/false choice. Remember: true/false, NOT YES/NO...
+
+ <sect3>select:
+ <p>
+A choice between one of a number of values. The choices must be
+specified in a field named 'Choices'. Separate the possible values
+with commas and spaces, like this: Choices: yes, no, maybe
+
+ <sect3>multiselect:
+ <p>
+Like the select data type, except the user can choose any number of
+
+ items from the choices list (or chose none of them).
+
+ <sect3>note:
+ <p>
+Rather than being a question per se, this datatype indicates a note
+that can be displayed to the user. It should be used only for
+important notes that the user really should see, since debconf will go
+to great pains to make sure the user sees it; halting the install for
+them to press a key, and even mailing the note to them in some
+cases.
+
+ <sect3>text:
+ <p>
+This type is now considered obsolete: don't use it.
+
+ <sect3>error:
+ <p>
+<strong>THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.</strong>
+ <p>
+It has been added to cdebconf, the C version of debconf, first used in
+the Debian Installer.
+ <p>
+Please do not use it unless debconf supports it.
+ <p>
+This type is designed to handle error message. It is mostly similar to
+the "note" type. Frontends may present it differently (for instance,
+the dialog frontend of cdebconf draws a red screen instead of the
+usual blue one).
+
+
+ <sect2>Description: short and extended description
+ <p>
+Templates descriptions have two parts: short and extended. The short
+description is in the "Description:" line of the template.
+ <p>
+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 translators, as usually translations tend to end up
+being longer than the original.
+ <p>
+The short description should be able to stand on its own. Some
+interfaces do not show the long description by default, or only if the
+user explicitely asks for it or even do not show it at all. Avoid
+things like "What do you want to do?"
+ <p>
+The short description does not necessarily have to be a full
+sentence. This is part of the "keep it short and efficient"
+recommendation.
+ <p>
+The extended description should not repeat the short description word
+for word. If you can't think up a long description, then first, think
+some more. Post to debian-devel. Ask for help. Take a writing class!
+That extended description is important. If after all that you still
+can't come up with anything, leave it blank.