<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.151 $">
+ <!entity cvs-rev "$Revision: 1.152 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<p>
There is infrastructure and several tools to help automate the package
porting. This section contains a brief overview of this automation and
-portingto these tools; see the package documentation or references for
+porting to these tools; see the package documentation or references for
full information.</p>
<sect2>
name="Debian Policy">, which defines explicit baseline requirements
which all Debian packages must fulfill. Yet there is also a shared
history of experience which goes beyond the Debian Policy, an
-accumulatation of years of experience in packaging. Many very
+accumulation of years of experience in packaging. Many very
talented people have created great tools, tools which help you, the
Debian maintainer, create and maintain excellent packages.
<p>
<package>debmake</package>, were "monolithic": you couldn't pick and
choose which part of the helper you found useful, but had to use the
helper to do everything. <package>debhelper</package>, however, is a
-number of sep
erate little <prgn>dh_*</prgn> programs. For instance,
-<prgn>dh_installman</prgn> installs and compresses manpages,
+number of sep
arate little <prgn>dh_*</prgn> programs. For instance,
+<prgn>dh_installman</prgn> installs and compresses man pages,
<prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it
offers enough flexibility to be able to use the little helper scripts,
where useful, in conjunction with hand-crafted commands in
learn its expectations and behavior.
<p>
Some people feel that vanilla <file>debian/rules</file> files are
-better, since you don't have to learn the intricies of any helper
+better, since you don't have to learn the intricacies of any helper
system. This decision is completely up to you. Use what works for
you. Many examples of vanilla <file>debian/rules</file> files are
available at <url id="&url-rules-files;">.
<prgn>install</prgn> (vanilla approach) 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 dependancies set right in <file>debian/control</file>.
+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 configure
<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 shbang line. Posix shell or
+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>
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 existance of a command, you should use
+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 hardcode the path of the command in your
+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:
<sect1 id="bpp-upstream-info">
<heading>Upstream home page</heading>
<p>
-We recommend that you add the URL for the package's homepage to the
-package description in <file>debian/control</file>, and a link to a
-screenshot, if one is handy. This information should be added at the
+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/
- Screenshot: http://some-project.some-place.org/</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
<p>
If there is no home page for the software, this should naturally be
left empty.
+ <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>
and provide that in your CVS area.
<p>
If you maintain XML or SGML documentation, we suggest that you isolate
-any language-independant information and define those as entities in a
+any language-independent information and define those as entities in a
separate file which is included by all the different
translations. This makes it much easier, for instance, to keep URLs
up-to-date across multiple files.
especially on more volatile architectures. Some very good packaging
practices for any package using <prgn>autoconf</prgn> and/or
<prgn>automake</prgn> have been synthesized in
-&file-bpp-autotools;. You're strongly encouraged to read this file and
+&file-bpp-autotools; from the <package>autotools-dev</package>
+package. You're strongly encouraged to read this file and
to follow the given recommendations.
Good practices for library packaging have been grouped in
<url id="&url-libpkg-guide;" name="the library packaging guide">.
+
+ <sect1 id="bpp-docs">Documentation
+ <p>
+Be sure to follow the <url id="&url-debian-policy;ch-docs.html"
+ name="Policy on documentation">.</p>
+ <p>
+If your package contains documentation built from XML or SGML, we
+recommend you not ship the XML or SGML source in the binary
+package(s). If users want the source of the documentation, they
+should retrieve the source package.</p>
+ <p>
+Policy specifies that documentation should be shipped in HTML format.
+We also recommend shipping documentation in PDF and ASCII format if
+convenient and quality output is possible. However, it is generally
+not appropriate to ship ASCII versions of documentation whose source
+format is HTML.</p>
+ <p>
+Major shipped manuals should register themselves with
+<package>doc-base</package> on installation. See the
+<package>doc-base</package> package documentation for more
+information.</p>
+
+
<sect1 id="bpp-other">Specific types of packages
<p>
Several specific types of packages have special sub-policies and
complete list of available scripts.</p>
</sect1>
+ <sect1 id="autotools-dev">
+ <heading><package>autotools-dev</package></heading>
+ <p>
+Contains best practices for people maintaining packages that use
+<prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains
+canonical <file>config.sub</file> and <file>config.guess</file> files
+which are known to work on all Debian ports.</p>
+ </sect1>
+
+ <sect1 id="dpkg-repack">
+ <heading><package>dpkg-repack</package></heading>
+ <p>
+<prgn>dpkg-repack</prgn> creates Debian package file out of a package
+that has already been installed. If any changes have been made to the
+package while it was unpacked (e.g., files in <file>/etc</file> were
+modified), the new package will inherit the changes.</p>
+ <p>
+This utility can make it easy to copy packages from one computer to
+another, or to recreate packages that are installed on your system
+but no longer available elsewhere, or to store the current state of a
+package before you upgrade it.</p>
+ </sect1>
+
+ <sect1 id="alien">
+ <heading><package>alien</package></heading>
+ <p>
+<prgn>alien</prgn> converts binary packages between various packaging
+formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),
+Solaris and Slackware packages.</p>
+ </sect1>
+
+ <sect1 id="debsums">
+ <heading><package>debsums</package></heading>
+ <p>
+<prgn>debsums</prgn> checks installed packages against their MD5 sums.
+Note that not all packages have MD5 sums, since they aren't required
+by Policy.</p>
+ </sect1>
+
<sect1 id="dpkg-dev-el">
<heading><package>dpkg-dev-el</package></heading>
<p>
<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
enhanced to support cross-compiling.
</sect1>
+
+
+ <sect id="tools-doc">
+ <heading>Documentation and information</heading>
+ <p>
+The following packages provide information for maintainers or help
+with building documentation.
+
+ <sect1 id="debiandoc-sgml">
+ <heading><package>debiandoc-sgml</package></heading>
+ <p>
+<package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,
+which is commonly used for Debian documentation. This manual, for
+instance, is written in DebianDoc. It also provides scripts for
+building and styling the source to various output formats.</p>
+ <p>
+Documentation for the DTD can be found in the
+<package>debiandoc-sgml-doc</package> package.</p>
+ </sect1>
+
+ <sect1 id="debian-keyring">
+ <heading><package>debian-keyring</package></heading>
+ <p>
+Contains the public GPG and PGP keys of Debian developers. See <ref
+id="key-maint"> and the package documentation for more
+information.</p>
+ </sect1>
+
+ <sect1 id="debview">
+ <heading><package>debview</package></heading>
+ <p>
+<package>debview</package> provides an Emacs mode for viewing Debian
+binary packages. This lets you examine a package without unpacking
+it.</p>
+ </sect1>
</sect>
<!-- FIXME: add the following
- alien
- dpkg-repack
- debsums
- debiandoc-sgml, debiandoc-sgml-doc
- debian-keyring
questionable:
ucf
dpkg-awk
grep-dctrl
- debview
d-shlibs
wajig
magpie
~ianmdlvl / developers-reference.git / commitdiff