<!entity % versiondata SYSTEM "version.ent"> %versiondata;
]>
<debiandoc>
- <!--
- Debian GNU/Linux Policy Manual.
- Copyright (C)1996,1997,1998 Ian Jackson and Christian Schwarz;
- released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- Initial version 1996, Ian Jackson, ijackson@gnu.ai.mit.edu
- Revised November 27, 1996, David A. Morris, bweaver@debian.org
- New sections March 15, 1997, Christian Schwarz, schwarz@debian.org
- Reworked/Restructured April-July 1997, Christian Schwarz, schwarz@debian.org
- Maintainer since 1997, Christian Schwarz, schwarz@debian.org
- Christoph Lameter contributed the "Web Standard"
- The debian-policy mailing list has taken responsibility for the
- contents of this document since September 1998, with the package
- maintainers responsible for packaging administrivia only.
- -->
<book>
<titlepag>
<title>Debian Policy Manual</title>
- <author>
- <name>Ian Jackson </name>
- <email>ijackson@gnu.ai.mit.edu</email>
- </author>
- <author>
- <name>Christian Schwarz</name>
- <email>schwarz@debian.org</email>
- </author>
- <author>
- <name>revised: David A. Morris</name>
- <email>bweaver@debian.org</email>
- </author>
- <author>
- <name>The Debian Policy mailing List</name>
- <email>debian-policy@lists.debian.org</email>
- </author>
+ <author><ref id="authors"></author>
<version>version &version;, &date;</version>
<abstract>
contents of the Debian archive and several design issues of
the operating system, as well as technical requirements that
each package must satisfy to be included in the distribution.
- The policy package itself is maintained by a group of
- maintainers that have no editorial powers. The current list
- of maintainers is:
- <enumlist>
- <item>
- <p>Julian Gilbey <email>jdg@debian.org</email></p>
- </item>
- <item>
- <p>Manoj Srivastava <email>srivasta@debian.org</email></p>
- </item>
- </enumlist>
</abstract>
<copyright>
<copyrightsummary>
- Copyright ©1996,1997,1998 Ian Jackson
+ Copyright © 1996,1997,1998 Ian Jackson
and Christian Schwarz.
</copyrightsummary>
<p>
</copyright>
</titlepag>
- <toc detail="sect">
+ <toc detail="sect1">
<chapt id="scope">
<heading>About this manual</heading>
merely informative, and are not part of Debian policy itself.
</p>
-
<p>
In this manual, the words <em>must</em>, <em>should</em> and
<em>may</em>, and the adjectives <em>required</em>,
only.
</p>
</sect>
+
<sect>
<heading>New versions of this document</heading>
<p>
changes between versions of this document.
</p>
</sect>
- <sect>
- <heading>Feedback</heading>
+
+ <sect id="authors">
+ <heading>Authors and Maintainers</heading>
<p>
- As the Debian GNU/Linux system is continuously evolving this
- manual does so too.
- </p>
+ Originally called "Debian GNU/Linux Policy Manual", this
+ manual was initially written in 1996 by Ian Jackson.
+ It was revised on November 27th, 1996 by David A. Morris.
+ Christian Schwarz added new sections on March 15th, 1997,
+ and reworked/restructured it in April-July 1997.
+ Christoph Lameter contributed the "Web Standard".
+ </p>
+
+ <p>
+ Since September 1998, the responsibility for the contents of
+ this document lies on the debian-policy mailing list. Proposals
+ are discussed there and inserted into policy after a certain
+ consensus is established.
+ <!-- insert shameless policy-process plug here eventually -->
+ The actual editing is done by a group of maintainers that have
+ no editorial powers. These are the current maintainers:
+
+ <enumlist>
+ <item>Julian Gilbey</item>
+ <item>Branden Robinson</item>
+ <item>Josip Rodin</item>
+ <item>Manoj Srivastava</item>
+ </enumlist>
+ </p>
+
<p>
While the authors of this document have tried hard to avoid
typos and other errors, these do still occur. If you discover
<email>debian-policy@lists.debian.org</email>, or submit a
bug report against the <tt>debian-policy</tt> package.
</p>
+
+ <p>
+ Please do not try to reach the individual authors or maintainers
+ of the Policy Manual regarding changes to the Policy.
+ </p>
</sect>
</chapt>
<tt>required</tt> or at least <tt>important</tt>, and many
of them will be tagged <tt>essential</tt> (see below).</p>
-
+
</sect1>
reconfigure the package if necessary. You should
<em>not</em> configure the package and edit the generated
<prgn>Makefile</prgn>! This makes it impossible for
- someone else to later reconfigure the package.</p></sect1>
-
-
- <sect1>
- <heading>Documenting your changes</heading>
+ someone else to later reconfigure the package.</p>
<p>
You should document your changes and updates to the source
- package properly in the <file>debian/changelog</file> file. (Note
- that mistakes in changelogs are usually best rectified by
- making a new changelog entry rather than "rewriting history"
- by editing old changelog entries.)</p>
-
- <p>
- In non-experimental packages you must use a format for
- <file>debian/changelog</file> which is supported by the most
- recent released version of <prgn>dpkg</prgn>.<footnote>
- <p>
- If you wish to use an alternative format, you may do
- so as long as you include a parser for it in your
- source package. The parser must have an API
- compatible with that expected by
- <prgn>dpkg-genchanges</prgn> and
- <prgn>dpkg-gencontrol</prgn>. If there is general
- interest in the new format, you should contact the
- <package>dpkg</package> maintainer to have the parser
- script for it included in the <prgn>dpkg</prgn>
- package. (You will need to agree that the parser and
- its manpage may be distributed under the GNU GPL, just
- as the rest of `dpkg' is.)
- </p>
- </footnote>
+ package properly in the <file>debian/changelog</file> file.
+ For more information, please see <ref id="changelogs">.
</p>
</sect1>
The <tt>Build-Depends</tt> and
<tt>Build-Conflicts</tt> fields must be satisfied when
any of the following targets is invoked:
- <tt>build</tt>, <tt>binary</tt>, <tt>binary-arch</tt>,
- <tt>build-arch</tt>, <tt>build-indep</tt>
- and <tt>binary-indep</tt>.
+ <tt>build</tt>, <tt>clean</tt>, <tt>binary</tt>,
+ <tt>binary-arch</tt>, <tt>build-arch</tt>,
+ <tt>build-indep</tt> and <tt>binary-indep</tt>.
</p>
</item>
<tag><tt>Build-Depends-Indep</tt>,
The <tt>Build-Depends-Indep</tt> and
<tt>Build-Conflicts-Indep</tt> fields must be
satisfied when any of the following targets is
- invoked: <tt>build</tt>, <tt>build-indep</tt>,
- <tt>binary</tt> and <tt>binary-indep</tt>.
+ invoked: <tt>build</tt>, <tt>clean</tt>,
+ <tt>build-indep</tt>, <tt>binary</tt> and
+ <tt>binary-indep</tt>.
</p>
</item>
</taglist>
To get the default behavior for your package, put in your
<prgn>postinst</prgn> script
<example compact="compact">
- update-rc.d <var>package</var> defaults
+ update-rc.d <var>package</var> defaults
</example>
and in your <prgn>postrm</prgn>
<example compact="compact">
if [ "$1" = purge ]; then
- update-rc.d <var>package</var> remove
+ update-rc.d <var>package</var> remove
fi
</example>. Note that is your package changes runlevels
or priority, you may have to remove and recreate the
</p>
<p>
- If no manual page is available for a particular program,
- utility, function or configuration file and this is reported
- as a bug to the Debian Bug Tracking System, a symbolic link
- from the requested manual page to the <manref
- name="undocumented" section="7"> manual page may be
- provided. This symbolic link can be created from
- <file>debian/rules</file> like this:
- <example compact="compact">
-ln -s ../man7/undocumented.7.gz \
- debian/tmp/usr/share/man/man[1-9]/<var>requested_manpage</var>.[1-9].gz
- </example>
- This manpage claims that the lack of a manpage has been
- reported as a bug, so you may only do this if it really has
- (you can report it yourself, if you like). Do not close the
- bug report until a proper manpage is available.</p>
+ There should be a manual page at for every program at the
+ very least, and possibly one for every configuration file,
+ protocol, utility, and function. If no manual page is
+ available, this is considered as a bug and should be
+ reported to the Debian Bug Tracking System (the maintainer
+ of the package is allowed to write this bug report
+ themselves, if they so desire). Do not close the bug report
+ until a proper manpage is available.<footnote>
+ <p>
+ It is not very hard to write a man page. See the
+ <url id="http://www.schweikhardt.net/man_page_howto.html"
+ name="Man-Page-HOWTO">,
+ <manref name="man" section="7">, the examples
+ created by <prgn>debmake</prgn> or <prgn>dh_make</prgn>,
+ the helper programs <prgn>help2man</prgn>, or the
+ directory <file>/usr/share/doc/man-db/examples</file>.
+ </p>
+ </footnote>
+ </p>
<p>
You may forward a complaint about a missing manpage to the
anyway.</p>
<p>
- Manual pages should be installed compressed using <tt>gzip
- -9</tt>.</p>
+ Manual pages should be installed compressed using <prgn>gzip</prgn>
+ <tt>-9</tt>.</p>
<p>
If one manpage needs to be accessible via several names it
course!</p>
<p>
- Files in <file>/usr/share/doc</file> should not be referenced by
- any program, and the system administrator should be able to
- delete them without causing any programs to break. Any files
- that are referenced by programs but are also useful as
- standalone documentation should be installed under
- <file>/usr/share/<var>package</var>/</file> with symbolic links
- from <file>/usr/share/doc/<var>package</var>/</file>.
+ Packages must not require the existance of any files in
+ <file>/usr/share/doc/</file> in order to function
+ <footnote>
+ <p>
+ The system administrator should be able to
+ delete files in <file>/usr/share/doc/</file> without causing
+ any programs to break.
+ </p>
+ </footnote>.
+ Any files that are referenced by programs but are also
+ useful as standalone documentation should be installed under
+ <file>/usr/share/doc/</file> with symbolic links from
+ <file>/usr/share/doc/<package></file>
</p>
- </sect>
-
- <sect id="usrdoc">
- <heading>Accessing the documentation</heading>
+ <p>
+ <file>/usr/share/doc/<var>package</var></file> may be a symbolic
+ link to another directory in <file>/usr/share/doc</file> only if
+ the two packages both come from the same source and the
+ first package Depends on the second.
+ </p>
<p>
Former Debian releases placed all additional documentation
- in <file>/usr/doc/<var>package</var></file>. This has now
+ in <file>/usr/doc/<var>package</var></file>. This has been
changed to <file>/usr/share/doc/<var>package</var></file>,
and packages must not put documentation in the directory
<file>/usr/doc/<var>package</var></file>. <footnote>
<p>
In addition, the copyright file must say where the upstream
- sources (if any) were obtained, and should explain briefly what
- modifications were made in the Debian version of the package
- compared to the upstream one. It should name the original
+ sources (if any) were obtained. It should name the original
authors of the package and the Debian maintainer(s) who were
involved with its creation.</p>
</p>
</sect>
- <sect id="instchangelog">
+ <sect id="changelogs">
<heading>Changelog files</heading>
+ <p>
+ The Debian changelog file (<file>debian/changelog</file>) should
+ explain briefly what modifications were made in the Debian version
+ of the package compared to the upstream one. Other changes and
+ updates to the package should also be documented in this file.
+ </p>
+
+ <p>
+ Mistakes in changelogs are usually best rectified by
+ making a new changelog entry rather than "rewriting history"
+ by editing old changelog entries.
+ </p>
+
+ <p>
+ The format of the <file>debian/changelog</file> file is described
+ in <ref id="dpkgchangelog">. In non-experimental packages you must
+ use a format for <file>debian/changelog</file> which is supported
+ by the most recent released version of <prgn>dpkg</prgn>.<footnote>
+ <p>
+ If you wish to use an alternative format, you may do so as long
+ as you include a parser for it in your source package. The
+ parser must have an API compatible with that expected by
+ <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-gencontrol</prgn>.
+ If there is general interest in the new format, you should
+ contact the <package>dpkg</package> maintainer to have the
+ parser script for it included in the <prgn>dpkg</prgn> package.
+ (You will need to agree that the parser and its manpage may be
+ distributed under the GNU GPL, just as the rest of `dpkg' is.)
+ </p>
+ </footnote>
+ </p>
+
<p>
Packages that are not Debian-native must contain a
compressed copy of the <file>debian/changelog</file> file from
the Debian source tree in
<file>/usr/share/doc/<var>package</var></file> with the name
- <file>changelog.Debian.gz</file>. If an upstream changelog is
- available, it should be accessible as
+ <file>changelog.Debian.gz</file>.
+ </p>
+
+ <p>
+ If an upstream changelog is available, it should be accessible as
<file>/usr/share/doc/<var>package</var>/changelog.gz</file> in
plain text. If the upstream changelog is distributed in
HTML, it should be made available in that form as
</footnote>
</p>
- <p>
- <file>/usr/share/doc/<var>package</var></file> may be a symbolic
- link to another directory in <file>/usr/share/doc</file> only if
- the two packages both come from the same source and the
- first package Depends on the second.
- </p>
-
-
<p>
All of these files should be installed compressed using
<tt>gzip -9</tt>, as they will become large with time even
there is a separate upstream maintainer, but no upstream
changelog, then the Debian changelog should still be called
<file>changelog.Debian.gz</file>.</p>
+
</sect>
</chapt>
projects / debian / debian-policy.git / blobdiff