From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Thu, 12 Dec 2002 18:44:37 +0000 (+0000)
Subject: Sec "Upstream home page": some revisions based on discussion on policy
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=4ad2c87a85ae14ce5681e7ba0bdbe51a2b5175cb

Sec "Upstream home page": some revisions based on discussion on policy
list

Sec "Documentation" added under Sec "Common packaging situations" for
best practices for documentation

Add tools entries for autotools-dev, dpkg-repack, alien, debsums; new
Sec "Documentation and information", add entries there for debview,
debiandoc-sgml, debian-keyring; we believe this manual now covers all
of the established, general Debian maintainer tool packages

spell-checking pass


git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1995 313b444b-1b9f-4f58-a734-7bb04f332e8d
---

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 0505322..ba2a9b7 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!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 -->
   <!--
@@ -2246,7 +2246,7 @@ blessing or status, so buyer, beware.
           <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>
@@ -2920,7 +2920,7 @@ Debian's quality is largely due to the <url id="&url-debian-policy;"
 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>
@@ -2962,8 +2962,8 @@ common and best (in our opinion) helper system is
 <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 seperate little <prgn>dh_*</prgn> programs.  For instance,
-<prgn>dh_installman</prgn> installs and compresses manpages,
+number of separate 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
@@ -2981,7 +2981,7 @@ helper, you do need to take the time to learn to use that helper, to
 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;">.
@@ -3024,7 +3024,7 @@ into the package's temporary trees.  You can do this using
 <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
@@ -3062,7 +3062,7 @@ 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 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>
@@ -3071,11 +3071,11 @@ 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 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:
 
@@ -3125,14 +3125,13 @@ intend to use you may ask on &email-debian-l10n-english;.
         <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
@@ -3140,6 +3139,12 @@ id="&url-eg-desc-upstream-info;">.
           <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>
 
@@ -3223,7 +3228,7 @@ original file the translation is based on.  You might wish to adapt
 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.
@@ -3249,7 +3254,8 @@ Keeping <prgn>autoconf</prgn>'s <file>config.sub</file> and
 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.
 
 
@@ -3264,6 +3270,29 @@ breaking.
 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
@@ -3844,6 +3873,45 @@ See the <manref name="devscripts" section="1"> manual page for a
 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>
@@ -3879,20 +3947,49 @@ headers for cross-compiling in a way similar to
 <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