<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.187 $">
+ <!entity cvs-rev "$Revision: 1.194 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<book>
<title>Debian Developer's Reference
- <author>Adam Di Carlo, current maintainer <email>aph@debian.org</email>
- <author>Raphaël Hertzog, co-maintainer <email>hertzog@debian.org</email>
- <author>Christian Schwarz <email>schwarz@debian.org</email>
- <author>Ian Jackson <email>ijackson@gnu.ai.mit.edu</email>
+ <author>Developer's Reference Team &email-devel-ref;
+ <author>Adam Di Carlo, editor
+ <author>Raphaël Hertzog
+ <author>Christian Schwarz
+ <author>Ian Jackson
<version>ver. &version;, &date-en;
<copyright>
In order to inform the other developers, there's two things that you should do.
First send a mail to &email-debian-private; with "[VAC] " prepended to the
subject of your message<footnote>This is so that the message can be easily
-filtered by people who don't want to read vacation notices.</footnote>,
-giving the period of time when you will be on vacation. You can also give
+filtered by people who don't want to read vacation notices.</footnote>
+and state the period of time when you will be on vacation. You can also give
some special instructions on what to do if a problem occurs.
<p>
The other thing to do is to mark yourself as "on vacation" in the
Cross-posting (sending the same message to multiple lists) is discouraged.
As ever on the net, please trim down the quoting of articles you're
replying to. In general, please adhere to the usual conventions for
-posting messages. Please read the <url name="code of conduct"
-id="&url-debian-lists;"> for more information.
+posting messages.
+ <p>
+Please read the <url name="code of conduct" id="&url-debian-lists;">
+for more information.
<sect1 id="mailing-lists-special">Special lists
<p>
freeze period, since the <em>unstable</em> distribution remains in
place in parallel with <em>testing</em>.
- <sect2>Experimental
+ <sect2 id="experimental">Experimental
<p>
The <em>experimental</em> distribution is a special distribution.
It is not a full distribution in the same sense as `stable' and
warned. In short, all bets are off for the <em>experimental</em>
distribution.
<p>
+These are the <manref name="sources.list" section="5"> lines for
+<em>experimental</em>:
+<example>
+deb http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main
+deb-src http://ftp.<var>xy</var>.debian.org/debian/ ../project/experimental main
+</example>
+ <p>
If there is a chance that the software could do grave damage to a system,
it is likely to be better to put it into <em>experimental</em>.
For instance, an experimental compressed file system should probably go
at the same time but it usually doesn't make sense to use that feature
because the dependencies of the package may vary with the distribution.
In particular, it never makes sense to combine the <em>experimental</em>
-distribution with anything else.
+distribution with anything else (see <ref id="experimental">).
<sect1 id="upload-stable">Uploads to <em>stable</em>
<p>
</sect1>
</sect>
- <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 sh-bang 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 the 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 id="bpp-debian-control">
+ <sect id="bpp-debian-control">
<heading>Best practices for <file>debian/control</file></heading>
<p>
The following practices are relevant to the
<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.
-
-
+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>
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, but "GTK+" is
+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
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">
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). Imagine that the synopsis is combined
-with the package name in the following way:
-
-<example>The <var>package-name</var> is a <var>synopsis</var>.</example>
+end with a full stop (period). It should also not begin with an
+article, either definite ("the") or indefinite ("a" or "an").
<p>
-If the package name is an acronym, it is sometimes useful to expand
-the acronym. For instance, the synopsis for <package>vim</package> is
-"Vi IMproved - enhanced vi editor".
+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 sentance 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 sentance.
+ </sect1>
<sect1 id="bpp-pkg-desc">
<heading>The long description</heading>
package. Assume that the user has already read the package synopsis.
<p>
The long description should consist of full and complete sentences.
-It is recommended to use two spaces after full stops in sentences. We
-realize this is an American style rather than European, but it is
-additionally helpful in creating visual space in fixed-width fonts.
<p>
The first paragraph of the long description should answer the
following questions: what does the package do? what task does it help
for <file>debian/control</file> files:
<example>ispell -d american -g debian/control</example>
-
</sect1>
+
<sect1 id="bpp-upstream-info">
<heading>Upstream home page</heading>
<p>
id="&url-eg-desc-upstream-info;">.
<p>
If there is no home page for the software, this should naturally be
-left empty.
+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
<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 sh-bang 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 the 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
<!-- FIXME: add the following
questionable:
+ dbs (referred to above)
+ dpatch (referred to above)
ucf
dpkg-awk
grep-dctrl
~ianmdlvl / developers-reference.git / blobdiff