X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=3b1206feb930bff99b49e0076307e098b909c228;hp=811fa695da45e70708ecabbd49bc9dffc2009b22;hb=af4a79e2cde3500ee7977db96bf127159508ddab;hpb=0c552242fa027c6682a6aca8314e422570bea0c8

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 811fa69..3b1206f 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.110 $">
+  <!entity cvs-rev "$Revision: 1.121 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -38,7 +38,7 @@
 
       <copyright>
 	<copyrightsummary>
-copyright &copy;1998&ndash;2002 Adam Di Carlo</copyrightsummary>
+copyright &copy;1998&mdash;2002 Adam Di Carlo</copyrightsummary>
 	<copyrightsummary>
 copyright &copy;1997, 1998 Christian Schwarz</copyrightsummary>
 	<p>
@@ -54,7 +54,7 @@ General Public License for more details.
 	<p>
 A copy of the GNU General Public License is available as &file-GPL; in
 the &debian-formal; distribution or on the World Wide Web at <url
-id="&url-gpl;" name="the GNU website">.  You can also obtain it by
+id="&url-gpl;" name="the GNU web site">.  You can also obtain it by
 writing to the &fsf-addr;.
 
     <toc detail="sect1">
@@ -111,7 +111,7 @@ to &email-debian-devel-req;.  In case of problems, contact the list
 administrator at &email-listmaster;.  More information on available
 mailing lists can be found in <ref id="mailing-lists">.
 &email-debian-devel-announce; is another list which is mandatory
-for anyone who wish to follow Debian's development.
+for anyone who wishes to follow Debian's development.
 	<p>
 You should subscribe and lurk (that is, read without posting) for a
 bit before doing any coding, and you should post about your intentions
@@ -128,8 +128,8 @@ should get in contact with existing Debian maintainers who are working
 on similar tasks.  That way, you can learn from experienced developers.
 For example, if you are interested in packaging existing software for
 Debian you should try to get a sponsor.  A sponsor will work together
-with you on your package and upload it to the Debian archive once he
-is happy with the packaging work you have done.  You can find a sponsor
+with you on your package and upload it to the Debian archive once they
+are happy with the packaging work you have done.  You can find a sponsor
 by mailing the &email-debian-mentors; mailing list, describing your
 package and yourself and asking for a sponsor (see <ref id="sponsoring">
 for more information on sponsoring).  On the other hand, if you are
@@ -201,7 +201,7 @@ OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
 2440">.
 	<p>
 The recommended public key algorithm for use in Debian development
-work is the DSA (sometimes call ``DSS'' or ``DH/ElGamal'').  Other key
+work is DSA (sometimes call ``DSS'' or ``DH/ElGamal'').  Other key
 types may be used however.  Your key length must be at least 1024
 bits; there is no reason to use a smaller key, and doing so would be
 much less secure.  Your key must be signed with at least your own user
@@ -272,7 +272,7 @@ available in <ref id="newmaint">.
 
       <sect id="user-maint">Maintaining your Debian information
 	<p>
-There's a LDAP database containing many informations concerning all
+There's a LDAP database containing information about all
 developers, you can access it at <url id="&url-debian-db;">. You can
 update your password (this password is propagated to most of the machines
 that are accessible to you), your address, your country, the latitude and
@@ -288,13 +288,13 @@ You have to keep the information available there up-to-date.
       <sect id="key-maint">Maintaining your public key
 	<p>
 Be very careful with your private keys.  Do not place them on any
-public servers or multiuser machines, such as
-<tt>&master-host;</tt>.  Back your keys up; keep a copy offline.
+public servers or multiuser machines, such as the Debian servers
+(see <ref id="server-machines">).  Back your keys up; keep a copy offline.
 Read the documentation that comes with your software; read the <url
 id="&url-pgp-faq;" name="PGP FAQ">.
 	<p>
 If you add signatures to your public key, or add user identities, you
-can update the debian key ring by sending your key to the key server at
+can update the Debian key ring by sending your key to the key server at
 <tt>&keyserver-host;</tt>.  If you need to add a completely new key,
 or remove an old key, send mail to &email-debian-keyring;.  The same
 key extraction routines discussed in <ref id="registering"> apply.
@@ -317,8 +317,8 @@ there. If you want to follow the debate preceding a vote, you
 may want to subscribe to &email-debian-vote;.
 	<p>
 The list of all the proposals (past and current) is available on the
-web at <url id="url-vote">. You will find there additionnal information
-about how to make a vote proposal.
+<url id="&url-vote;" name="Debian Voting Information"> page. You will find
+there additional information about how to make a vote proposal.
 
 
       <sect id="inform-vacation">Going on vacation gracefully
@@ -402,57 +402,85 @@ emailing to &email-debian-keyring;.
    <chapt id="resources">Resources for Debian Developers
      <p>
 In this chapter you will find a very brief road map of the Debian
-mailing lists, the main Debian servers, other Debian machines
+mailing lists, the Debian machines
 which may be available to you as a developer, and all the other
 resources that are available to help you in your maintainer work.
 
       <sect id="mailing-lists">Mailing lists
 	<p>
-The mailing list server is at <tt>&lists-host;</tt>.  Mail
+The mailing list server is at <tt>&lists-host;</tt>.
+	<p>
+Online archives of mailing lists are available at <url
+id="&url-lists-archives;">.
+
+	<sect1 id="core-devel-mailing-lists">Core development mailing lists
+	<p>
+The core Debian mailing lists that developers should use are:
+<list>
+  <item>&email-debian-devel-announce;, used to announce important things to
+        developers.
+        All developers are expected to be subscribed to this list.
+  </item>
+  <item>&email-debian-devel;, used to discuss various development related
+        technical issues.
+  </item>
+  <item>&email-debian-policy;, where the Debian Policy is discussed and
+        voted on.
+  </item>
+  <item>&email-debian-project;, used to discuss various non-technical
+        issues related to the project.
+  </item>
+</list>
+	<p>
+There are
+other mailing lists available for a variety of special topics; see
+<url id="&url-debian-lists-subscribe;"> for a list.
+
+	<sect1 id="mailing-lists-subunsub">Subscribing and unsubscribing
+	<p>
+To subscribe to or unsubscribe from any of the Debian mailing lists, email
 <tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
 <tt>debian-<var>foo</var></tt> is the name of the list, with the word
 <tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
-<tt>unsubscribe</tt> to unsubscribe.  More detailed instructions on
-how to subscribe and unsubscribe to the mailing lists can be found at
-<url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;">
-or locally in &file-mail-lists; if you have the
-<package>doc-debian</package> package installed.
+<tt>unsubscribe</tt> to unsubscribe.
+	<p>
+If you prefer to use a web page to subscribe to multiple mailing lists,
+there's one at <url id="&url-debian-lists-subscribe;">.
+	<p>
+You can download the current list of mailing lists and basic usage
+instructions from <url id="&url-debian-lists;">
+or install the <package>doc-debian</package> package and have it
+locally in &file-mail-lists;.
+
+	<sect1 id="mailing-lists-rules">Basic rules for use
 	<p>
 When replying to messages on the mailing list, please do not send a
 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
 request to be copied.  Anyone who posts to a mailing list should read
 it to see the responses.
 	<p>
-The following are the core Debian mailing lists: &email-debian-devel;,
-&email-debian-policy;, &email-debian-user;, &email-debian-private;,
-&email-debian-announce;, and &email-debian-devel-announce;.  All
-developers are expected to be subscribed to at least
-&email-debian-devel-announce;.  There are
-other mailing lists available for a variety of special topics; see
-<url id="&url-debian-lists-subscribe;"> for a list.  Cross-posting
-(sending the same message to multiple lists) is discouraged.
+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.
+
+	<sect1 id="mailing-lists-special">Special lists
 	<p>
 &email-debian-private; is a special mailing list for private
 discussions amongst Debian developers.  It is meant to be used for
-posts which for whatever reason should not be published publically.
+posts which for whatever reason should not be published publicly.
 As such, it is a low volume list, and users are urged not to use
 &email-debian-private; unless it is really necessary.  Moreover, do
 <em>not</em> forward email from that list to anyone.  Archives of this
 list are not available on the web for obvious reasons, but you can see
-them using your shell account on <tt>&master-host;</tt> and looking
+them using your shell account on <tt>lists.debian.org</tt> and looking
 in the <file>~debian/archive/debian-private</file> directory.
 	<p>
 &email-debian-email; is a special mailing list used as a grab-bag 
 for Debian related correspondence such as contacting upstream authors
 about licenses, bugs, etc. or discussing the project with others where it
 might be useful to have the discussion archived somewhere.
-	<p>
-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.
-	<p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
 
       <sect id="irc-channels">IRC channels
 	<p>
@@ -465,70 +493,90 @@ The main channel <em>#debian-devel</em> is very active since more
 than 150 persons are always logged in. It's a channel for people who work
 on Debian, it's not a support channel (there's <em>#debian</em> for that).
 It is however open to anyone who wants to lurk (and learn). Its topic is
-always full of interesting informations. Since it's an open channel, you
+always full of interesting information. Since it's an open channel, you
 should not speak there of issues that are discussed in
 &email-debian-private;. There's a key protected channel
 <em>#debian-private</em> for that purpose. The key is available 
-in the archives of debian-private in <file>&master-host;:&file-debian-private-archive;</file>, just <prgn>zgrep</prgn> for <em>#debian-private</em> in
+in the archives of debian-private in
+<file>master.debian.org:&file-debian-private-archive;</file>,
+just <prgn>zgrep</prgn> for <em>#debian-private</em> in
 all the files.
 	<p>
-There are other additionnal channels dedicated to specific subjects.
+There are other additional channels dedicated to specific subjects.
 <em>#debian-bugs</em> is used for coordinating bug squash parties.
 <em>#debian-boot</em> is used to coordinate the work on the boot
 floppies (i.e. the installer). <em>#debian-doc</em> is
-occasionnaly used to work on documentation like the one you are
+occasionally used to work on documentation like the one you are
 reading. Other channels are dedicated to an architecture or a set of
-packages : <em>#debian-bsd</em>, <em>#debian-kde</em>,
+packages: <em>#debian-bsd</em>, <em>#debian-kde</em>,
 <em>#debian-sf</em> (SourceForge package), <em>#debian-oo</em> (OpenOffice
 package) ...
 	<p>
-Some non-english channels exist, for example <em>#debian-devel-fr</em> for
-french speaking people interested in Debian's development.
+Some non-English channels exist, for example <em>#debian-devel-fr</em> for
+French speaking people interested in Debian's development.
 
 
       <sect id="doc-rsrcs">Documentation
 	<p>
-This document contains many informations very useful to Debian developers,
+This document contains a lot of information very useful to Debian developers,
 but it can not contain everything. Most of the other interesting documents
 are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
 Take the time to browse all the links, you will learn many more things.
 
-      <sect id="server-machines">Debian servers
+
+      <sect id="server-machines">Debian machines
+	<p>
+Debian has several computers working as servers, most of which serve
+critical functions in the Debian project. Most of the machines are used
+for porting activities, and they all have a permanent connection to the
+Internet.
+	<p>
+Most of the machines are available for individual developers to use,
+as long as the developers follow the rules set forth in the
+<url name="Debian Machine Usage Policies" id="&url-dmup;">.
+	<p>
+Generally speaking, you can use these machines for Debian-related purposes
+as you see fit.  Please be kind to system administrators, and do not use
+up tons and tons of disk space, network bandwidth, or CPU without first
+getting the approval of the admins.  Usually these machines are run by
+volunteers.
 	<p>
-Debian servers are well known servers which serve critical functions
-in the Debian project.  Every developer should know what these servers
-are and what they do.
+Please take care to protect your Debian passwords and SSH keys installed on
+Debian machines. Avoid login or upload methods which send passwords over
+the Internet in the clear, such as telnet, FTP, POP etc.
+	<p>
+Please do not put any material that doesn't relate to Debian on the Debian
+servers, unless you have prior permission.
+	<p>
+The current list of Debian machines is available at
+<url id="&url-devel-machines;">. That web page contains machine names,
+contact information, information about who can log in, SSH keys etc.
 	<p>
 If you have a problem with the operation of a Debian server, and you
 think that the system operators need to be notified of this problem,
-please find the contact address for the particular machine at <url
-id="&url-devel-machines;">.  If you have a non-operating problems
-(such as packages to be remove, suggestions for the web site, etc.),
+the Debian system administrator team is reachable at
+<email>debian-admin@lists.debian.org</email>.
+	<p>
+If you have a problem with a certain service, not related to the system
+administration (such as packages to be removed from the archive,
+suggestions for the web site, etc.),
 generally you'll report a bug against a ``pseudo-package''.  See <ref
 id="submit-bug"> for information on how to submit bugs.
 
-      <sect1 id="servers-master">The master server
+      <sect1 id="servers-bugs">The bugs server
 	<p>
-<tt>&master-host;</tt> is the canonical location for the Bug Tracking
+<tt>bugs.debian.org</tt> is the canonical location for the Bug Tracking
 System (BTS).  If you plan on doing some statistical analysis or
 processing of Debian bugs, this would be the place to do it.  Please
 describe your plans on &email-debian-devel; before implementing
 anything, however, to reduce unnecessary duplication of effort or
 wasted processing time.
 	<p>
-All Debian developers have accounts on <tt>&master-host;</tt>.
-Please take care to protect your password to this machine.  Try to
-avoid login or upload methods which send passwords over the Internet
-in the clear.
-	<p>
-If you find a problem with <tt>&master-host;</tt> such as disk
-full, suspicious activity, or whatever, send an email to
-&email-debian-admin;.
+All Debian developers have accounts on <tt>bugs.debian.org</tt>.
 
       <sect1 id="servers-ftp-master">The ftp-master server
 	<p>
-The ftp-master server, <tt>&ftp-master-host;</tt> (or
-<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
+The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
 archive (excluding the non-US packages). Generally, package uploads
 go to this server; see <ref id="upload">.
 	<p>
@@ -537,34 +585,59 @@ bugs against the <package>ftp.debian.org</package> pseudo-package or
 an email to &email-ftpmaster;, but also see the procedures in
 <ref id="archive-manip">.
 
-      <sect1 id="servers-www">The WWW server
+      <sect1 id="servers-non-us">The non-US server
 	<p>
-The main web server, <tt>&www-host;</tt>, is also known as
-<tt>klecker.debian.org</tt>.  All developers are given accounts on this
-machine.
+The non-US server, <tt>non-us.debian.org</tt>,
+holds the canonical copy of the non-US part of the Debian archive.
+If you need to upload a package into one of the non-US sections, upload it
+to this server; see <ref id="upload-non-us">.
 	<p>
-If you have some Debian-specific information which you want to serve
-up on the web, you can do this by putting material in the
-<file>public_html</file> directory under your home directory.  You should
-do this on <tt>klecker.debian.org</tt>. Any material you put in those areas
-are accessible via the URL
-<tt>http://people.debian.org/~<var>user-id</var>/</tt>.
-You should only use this particular location because it will be backed up,
-whereas on other hosts it won't. Please do not put any material on Debian
-servers not relating to Debian, unless you have prior permission.
-Send mail to &email-debian-devel; if you have any questions.
+Problems with the non-US package archive should generally be submitted as
+bugs against the <package>nonus.debian.org</package> pseudo-package (notice
+the lack of hyphen between "non" and "us" in the pseudo-package name
+&mdash; that's for backwards compatibility). Remember to check whether or
+not someone else has already reported the problem on the
+<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+
+      <sect1 id="servers-www">The www-master server
+	<p>
+The main web server is <tt>www-master.debian.org</tt>.
+It holds the official web pages, the face
+of Debian for most newbies.
 	<p>
 If you find a problem with the Debian web server, you should generally
 submit a bug against the pseudo-package,
-<package>www.debian.org</package>.  First check whether or not someone
+<package>www.debian.org</package>. Remember to check whether or not someone
 else has already reported the problem on the
 <url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
 
+      <sect1 id="servers-people">The people web server
+	<p>
+<tt>people.debian.org</tt> is the server used
+for developers' own web pages about anything related to Debian.
+	<p>
+If you have some Debian-specific information which you want to serve
+on the web, you can do this by putting material in the
+<file>public_html</file> directory under your home directory on
+<tt>people.debian.org</tt>.
+This will be accessible at the URL
+<tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
+	<p>
+You should only use this particular location because it will be backed up,
+whereas on other hosts it won't.
+	<p>
+Usually the only reason to use a different host is when you need to publish
+materials subject to the U.S. export restrictions, in which case you can use
+one of the other servers located outside the United States, such as the
+aforementioned <tt>non-us.debian.org</tt>.
+	<p>
+Send mail to &email-debian-devel; if you have any questions.
 
       <sect1 id="servers-cvs">The CVS server
 	<p>
-<tt>cvs.debian.org</tt> is also known as <tt>klecker.debian.org</tt>,
-discussed above.  If you need to use a publically accessible CVS
+Our CVS server is located on <tt>cvs.debian.org</tt>.
+	<p>
+If you need to use a publicly accessible CVS
 server, for instance, to help coordinate work on a package between
 many different developers, you can request a CVS area on the server.
 	  <p>
@@ -578,7 +651,7 @@ To request a CVS area, send a request via email to
 the Debian account that should own the CVS root area, and why you need it.
 
 
-      <sect1 id="devel-db">The Developers Database
+    <sect id="devel-db">The Developers Database
 	<p>
 The Developers Database, at <url id="&url-debian-db;">, is an LDAP
 directory for managing Debian developer attributes.  You can use this
@@ -611,21 +684,6 @@ interested in helping Debian.  As such, developers generally do not
 have accounts on these machines.
 
 
-      <sect id="other-machines">Other Debian developer machines
-	<p>
-There are other Debian machines which may be made available to you.
-You can use these for Debian-related purposes as you see fit.  Please
-be kind to system administrators, and do not use up tons and tons of
-disk space, network bandwidth, or CPU without first getting the
-approval of the local maintainers.  Usually these machines are run by
-volunteers.  Generally, these machines are for porting activities.
-	<p>
-Aside from the servers mentioned in <ref id="server-machines">, there
-is a list of machines available to Debian developers at <url
-id="&url-devel-machines;">.
-
-
-
     <sect id="archive">The Debian archive
 	<p>
 The &debian-formal; distribution consists of a lot of packages
@@ -641,14 +699,15 @@ As you can see, the top-level directory contains two directories,
 packages actually are, and which is handled by the archive maintenance
 database and the accompanying programs. The former contains the
 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
-Each of those distribution directories is divided in equivalent
-subdirectories purpose of which is equal, so we will only explain how it
-looks in stable. The <file>Packages</file> and <file>Sources</file> files in the
+The <file>Packages</file> and <file>Sources</file> files in the
 distribution subdirectories can reference files in the <file>pool/</file>
-directory.
+directory. The directory tree below each of the distributions is arranged
+in an identical manner.  What we describe below for <em>stable</em> is
+equally applicable to the <em>unstable</em> and <em>testing</em>
+distributions. 
 	<p>
 <file>dists/stable</file> contains three directories, namely <file>main</file>,
-<file>contrib</file>, and <file>non-free</file>.
+<file>contrib</file>, and <file>non-free</file>. 
 	<p>
 In each of the areas, there is a directory for the source packages
 (<file>source</file>) and a directory for each supported architecture
@@ -726,7 +785,7 @@ shipped for <em>i386</em> and <em>m68k</em> architectures.  Debian 2.1
 ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
 <em>sparc</em> architectures.  Debian 2.2 added support for the
 <em>powerpc</em> and <em>arm</em> architectures. Debian 3.0 adds
-support of five new architectures : <em>ia64</em>, <em>hppa</em>,
+support of five new architectures: <em>ia64</em>, <em>hppa</em>,
 <em>s390</em>, <em>mips</em> and <em>mipsel</em>.
 	<p>
 Information for developers or uses about the specific ports are
@@ -832,7 +891,7 @@ that time (although it can be found at <tt>&archive-host;</tt>).
 This development cycle is based on the assumption that the
 <em>unstable</em> distribution becomes <em>stable</em> after passing a
 period of being in <em>testing</em>.  Even once a distribution is
-considered stable, a few bugs inevitably remain &mdash that's why the
+considered stable, a few bugs inevitably remain &mdash; that's why the
 stable distribution is updated every now and then. However, these
 updates are tested very carefully and have to be introduced into the
 archive individually to reduce the risk of introducing new bugs.  You
@@ -887,7 +946,7 @@ New software which isn't likely to damage your system can go directly into
 <em>unstable</em>.
 	  <p>
 An alternative to <em>experimental</em> is to use your personal web space
-on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
+on <tt>people.debian.org</tt>.
 
 
       <sect1 id="codenames">Release code names
@@ -935,20 +994,20 @@ installing them in the Debian archive. It consists of a set of
 directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
 and <tt>&non-us-host;</tt>.
 	<p>
-Packages are uploaded by all the maintainers into an <file>unchecked</file>
-directory. This directory is scanned every 15 minutes by the katie script
-that verifies the integrity of the package and the cryptographic
-signature.  If the package is considered ready to be installed, it
-is moved into an <file>accepted</file> directory. If it is the first upload of
-the package then it is moved in a <file>new</file> directory waiting an
-approval of the ftpmasters. If the package contains files to be installed
-"by-hand" is is moved in the <file>byhand</file> directory waiting a manual
-installation by the ftpmasters. Otherwise, if any error has been detected,
+Packages are uploaded by all the maintainers into a directory called
+<file>unchecked</file>. This directory is scanned every 15 minutes by the katie script
+that verifies the integrity of the uploaded packages and the cryptographic
+signatures.  If the package is considered ready to be installed, it
+is moved into the <file>accepted</file> directory. If this is the first upload of
+the package, it is moved in the <file>new</file> directory, where it waits
+for an approval of the ftpmasters. If the package contains files to be installed
+"by-hand" is is moved in the <file>byhand</file> directory, where it waits
+for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
 the package is refused and is moved in the <file>reject</file> directory.
 	<p>
 Once the package is accepted the system sends a confirmation
 mail to the maintainer, closes all the bugs marked as fixed by the upload
-and the autobuilders may start recompiling it. The package is now publically
+and the auto-builders may start recompiling it. The package is now publicly
 accessible at <url id="&url-incoming;"> (there is no
 such URL for packages in the non-US archive) until it is really installed
 in the Debian archive. This happens only once a day, the package
@@ -968,7 +1027,7 @@ why you can not remove an upload once it has been accepted.
       <sect1 id="delayed-incoming">Delayed incoming
 	<p>	
 The <file>unchecked</file> directory has a special <file>DELAYED</file>
-subdirectory. It is itself subdivised in nine directories
+subdirectory. It is itself subdivided in nine directories
 called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded in
 one of those directories will be moved in the real unchecked
 directory after the corresponding number of days.
@@ -980,10 +1039,10 @@ be moved in <file>4-day</file>). This feature is particularly useful
 for people who are doing non-maintainer uploads. Instead of
 waiting before uploading a NMU, it is uploaded as soon as it is
 ready but in one of those <file>DELAYED/<var>x</var>-day</file> directories.
-That leaves the corresponding number of days to the maintainer
-in order to react and upload himself another fix if he is not
-completely satisfied with the NMU. Alternatively he can remove
-the NMU by himself.
+That leaves the corresponding number of days for the maintainer
+to react and upload another fix themselves if they are not
+completely satisfied with the NMU. Alternatively they can remove
+the NMU.
 	<p>
 The use of that delayed feature can be simplified with a bit
 of integration with your upload tool.  For instance, if you use 
@@ -995,9 +1054,6 @@ $cfg{'delayed'} = {
          fqdn => "&ftp-master-host;",
          login => "yourdebianlogin",
          incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
-         visibleuser => "yourdebianlogin",
-         visiblename => "debian.org",
-         fullname => "Your Full Name",
          dinstall_runs => 1,
          method => "scpb"
 };
@@ -1014,11 +1070,11 @@ updated packages. They generate the <file>Packages</file> files for
 the <em>testing</em> distribution, but they do so in an intelligent manner
 trying to avoid any inconsistency and trying to use only
 non-buggy packages.
-	<p>The inclusion of a package from <em>unstable</em> is conditionned:
+	<p>The inclusion of a package from <em>unstable</em> is conditional on the following:
 <list>
     <item>
 The package must have been available in <em>unstable</em> for several days;
-the precise number depends on the urgency field's value of the upload. It
+the precise number depends on the upload's urgency field. It
 is 10 days for low urgency, 5 days for medium urgency and 2 days for high
 urgency. Those delays may be doubled during a freeze;
     <item>
@@ -1045,7 +1101,7 @@ the <prgn>grep-excuses</prgn> program part of the
 to keep someone informed of the progression of his packages in testing.
 	<p>
 The <file>update_excuses</file> file does not always give the precise reason
-why the package is refused, one may have to find it by himself by looking
+why the package is refused, one may have to find it on their own by looking
 what would break with the inclusion of the package. The <url
 id="&url-testing-faq;" name="testing FAQ"> gives some more information
 about the usual problems which may be causing such troubles.
@@ -1060,8 +1116,8 @@ contacted, and he will force the inclusion of the packages.
 
       <sect1 id="pkg-info-web">On the web
 	<p>
-Each package has several dedicated web pages that contains many
-informations. <tt>http://&packages-host;/<var>package-name</var></tt>
+Each package has several dedicated web pages that contain a lot of
+information. <tt>http://&packages-host;/<var>package-name</var></tt>
 will display each version of the package
 available in the various distributions.  The per-version detailed
 information includes the package description,
@@ -1103,7 +1159,7 @@ sent through the PTS is classified and associated to one of
 the keyword listed below. This will let you select the mails that
 you want to receive.
 	<p>
-By default you will get :
+By default you will get:
 <taglist>
     <tag><tt>bts</tt>
     <item>
@@ -1135,7 +1191,7 @@ informed of the package's status (bug statistics, porting overview,
 progression in testing, ...).
 </taglist>
 	<p>
-You can also decide to receive some more information :
+You can also decide to receive some more information:
 <taglist>
     <tag><tt>upload-binary</tt>
     <item>
@@ -1180,19 +1236,19 @@ various commands to <email>pts@qa.debian.org</email>.
   Tells you the keywords that you are accepting. Each mail sent through
   the Package Tracking System is associated to a keyword and you receive
   only the mails associated to keywords that you are accepting. Here is
-  the list of available keywords :
+  the list of available keywords:
   <list>
-  <item><tt>bts</tt> : mails coming from the Debian Bug Tracking System
-  <item><tt>bts-control</tt> : reply to mails sent to
+  <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
+  <item><tt>bts-control</tt>: reply to mails sent to
         <email>control@bugs.debian.org</email>
-  <item><tt>summary</tt> : automatic summary mails about the state of a package
-  <item><tt>cvs</tt> : notification of cvs commits
-  <item><tt>upload-source</tt> : announce of a new source upload that
+  <item><tt>summary</tt>: automatic summary mails about the state of a package
+  <item><tt>cvs</tt>: notification of CVS commits
+  <item><tt>upload-source</tt>: announce of a new source upload that
         has been accepted
-  <item><tt>upload-binary</tt> : announce of a new binary-only upload (porting)
-  <item><tt>katie-other</tt> : other mails from ftpmasters
+  <item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)
+  <item><tt>katie-other</tt>: other mails from ftpmasters
         (override disparity, etc.)
-  <item><tt>default</tt> : all the other mails (those which aren't "automatic")
+  <item><tt>default</tt>: all the other mails (those which aren't "automatic")
   </list>
 
 <tag><tt>keyword &lt;srcpackage&gt; [&lt;email&gt;]</tt>
@@ -1226,7 +1282,7 @@ mailbox with <prgn>procmail</prgn>. The added headers are
 <tt>X-Unsubscribe</tt>.
 	<p>
 Here is an example of added headers for a source upload notification
-on the <package>dpkg</package> package :
+on the <package>dpkg</package> package:
 <example>
 X-Loop: dpkg@&pts-host;
 X-PTS-Package: dpkg
@@ -1236,12 +1292,12 @@ X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
 
 	<sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS
 	<p>
-If you use a publically accessible CVS repository for maintaining
+If you use a publicly accessible CVS repository for maintaining
 your Debian package you may want to forward the commit notification
 to the PTS so that the subscribers (possible co-maintainers) can
 closely follow the package's evolution.
 	<p>
-It's very easy to setup. Once your cvs repository generates commit
+It's very easy to setup. Once your CVS repository generates commit
 notifications, you just have to make sure it sends a copy of those mails
 to <tt><var>srcpackage</var>_cvs@&pts-host;</tt>. Only people who
 accepts the <em>cvs</em> keyword will receive the notifications.
@@ -1551,13 +1607,13 @@ maintenance software will process it by running <prgn>dinstall</prgn>
 on your changes file: <example>dinstall -n foo.changes</example>.
 Note that <prgn>dput</prgn> can do this for you automatically.
 
-	<sect2 id="upload-non-us">Uploading to <tt>non-US</tt> (pandora)
+	<sect2 id="upload-non-us">Uploading to <tt>non-US</tt>
 	  <p>
 As discussed above, export controlled software should not be uploaded
 to <tt>ftp-master</tt>.  Instead, upload the package to
 <ftpsite>non-us.debian.org</ftpsite>, placing the files in
 &non-us-upload-dir; (again, both <ref id="dupload"> and <ref
-id="dput"> can do this for you if invocated properly). By default,
+id="dput"> can do this for you if invoked properly). By default,
 you can use the same account/password that works on
 <tt>ftp-master</tt>.  If you use anonymous FTP to upload, place the
 files into &upload-queue;.
@@ -1814,7 +1870,7 @@ id="nmu-guidelines"> need to be followed.
 	<p>
 Bug fixes to unstable by non-maintainers are also acceptable, but only
 as a last resort or with permission.  The following protocol should
-be respected to do an NMU :
+be respected to do an NMU:
 	<p>
 <list>
 	    <item>
@@ -1834,8 +1890,8 @@ Make sure your patch is as small and as non-disruptive as it can be.
 	    <item>
 Upload your package to incoming in <file>DELAYED/7-day</file> (cf.
 <ref id="delayed-incoming">), send the final patch to the maintainer via
-the BTS, and explain him that he has 7 days to react if he wants to cancel
-the NMU.
+the BTS, and explain to them that they have 7 days to react if they want
+to cancel the NMU.
 	    <item>
 Follow what happens, you're responsible for any bug that you introduced
 with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
@@ -1888,11 +1944,7 @@ absolutely necessary for someone other than the usual maintainer to
 make a release based on a new upstream version then the person making
 the release should start with the <var>debian-revision</var> value
 `0.1'.  The usual maintainer of a package should start their
-<var>debian-revision</var> numbering at `1'.  Note that if you do
-this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
-<tt>-sa</tt> switch to force the build system to pick up the new
-source package (normally it only looks for Debian revisions of '0' or
-'1' &mdash; it's not yet clever enough to know about `0.1').
+<var>debian-revision</var> numbering at `1'. 
 
 
 	<sect2 id="nmu-changelog">
@@ -1975,10 +2027,10 @@ BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog
 entry of your next upload.
 	<p>
 In any case, you should not be upset by the NMU. An NMU is not a
-personal attack against the maintainer. It is just the proof that
-someone cares enough about the package and was willing to help
-you in your work. You should be thankful to him and you may want to
-ask him if he would be interested to help you on a more frequent
+personal attack against the maintainer. It is a proof that
+someone cares enough about the package and that they were willing to help
+you in your work, so you should be thankful. You may also want to
+ask them if they would be interested to help you on a more frequent
 basis as co-maintainer or backup maintainer
 (see <ref id="collaborative-maint">).
 
@@ -2195,7 +2247,7 @@ conjunction with <em>auto-builders</em>, which are ``slave'' hosts
 which simply check out and attempt to auto-build packages which need
 to be ported.  There is also an email interface to the system, which
 allows porters to ``check out'' a source package (usually one which
-cannot yet be autobuilt) and work on it.
+cannot yet be auto-built) and work on it.
 	  <p>
 <package>buildd</package> is not yet available as a package; however,
 most porting efforts are either using it currently or planning to use
@@ -2228,12 +2280,43 @@ headers for cross-compiling in a way similar to
 enhanced to support cross-compiling.
 
 
-    <sect id="collaborative-maint">Collaborative maintenance
-      <p>
-&FIXME; Speak about Uploaders: field, about the intelligent use
-of the PTS. Insist that it's a "must have" for base and standard
-packages.
-
+    <sect id="collaborative-maint">
+        <heading>Collaborative maintenance</heading>
+        <p>
+"Collaborative maintenance" is a term describing the sharing of Debian
+package maintenance duties by several people.  This collaboration is
+almost a good idea, since it generally results in higher quality and
+faster bug fix turnaround time.  It is strongly recommended that
+packages in which a priority of <tt>Standard</tt> or which are part of
+the base set have co-maintainers.</p>
+        <p>
+Generally there is a primary maintainer and one or more
+co-maintainers.  The primary maintainer is the whose name is listed in
+the <tt>Maintainer</tt> field of the <file>debian/control</file> file.
+Co-maintainers are all the other maintainers.</p>
+        <p>
+In its most basic form, the process of adding a new co-maintainer is
+quite easy:<list>
+            <item>
+              <p>
+Setup the co-maintainer with access to the sources you build the
+package from.  Generally this implies you are using a network-capable
+version control system, such as <prgn>CVS</prgn> or
+<prgn>Subversion</prgn>.</p>
+            </item>
+            <item>
+              <p>
+Add the co-maintainer's correct maintainer name and address to the
+<tt>Uploaders</tt> field in the global part of the
+<file>debian/control</file> file.</p>
+            </item>
+            <item>
+              <p>
+Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers
+should subscribe themselves to the appropriate source package.</p>
+            </item>
+          </list></p>
+      </sect>
 
     <sect id="archive-manip">
       <heading>Moving, Removing, Renaming, Adopting, and Orphaning
@@ -2372,8 +2455,8 @@ automatically once you upload a new version with an updated
 <tt>Maintainer:</tt> field, although it can take a few hours after the
 upload is done. If you do not expect to upload a new version for a while,
 you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
-make sure that the old maintainer is not embarassed by the fact that
-he will continue to receive the bugs during that time.
+make sure that the old maintainer has no problem with the fact that
+they will continue to receive the bugs during that time.
 
 
     <sect id="bug-handling">Handling package bugs
@@ -2449,14 +2532,14 @@ enough information to let the user correct his problem (give pointers
 to the good documentation and so on). If the same report comes up
 again and again you may ask yourself if the documentation is good
 enough or if the program shouldn't detect its misuse in order to
-give an informatory error message. This is an issue that may need
+give an informative error message. This is an issue that may need
 to be brought to the upstream author.
     <p>
 If the bug submitter disagree with your decision to close the bug,
-he may reopen it until you find an agreement on how to handle it.
+they may reopen it until you find an agreement on how to handle it.
 If you don't find any, you may want to tag the bug <tt>wontfix</tt>
 to let people know that the bug exists but that it won't be corrected.
-If this situation is inacceptable, you (or the submitter) may want to
+If this situation is unacceptable, you (or the submitter) may want to
 require a decision of the technical committee by reassigning the bug
 to <package>tech-ctte</package> (you may use the clone command of
 the BTS if you wish to keep it reported against your package).
@@ -2501,7 +2584,7 @@ it will be closed with the next upload (add the <tt>closes:</tt> in
 the <file>changelog</file>). This is particularly useful if you
 are several developers working on the same package.
     <item>
-Once a corrected package is availabe in the <em>unstable</em>
+Once a corrected package is available in the <em>unstable</em>
 distribution, you can close the bug. This can be done automatically,
 read <ref id="upload-bugfix">.
 </enumlist>
@@ -2615,11 +2698,11 @@ The good solution is to keep separate patches within the
 <file>debian/patches</file> directory and to apply them on the fly at
 build time. The package <package>dbs</package> provides an
 implementation of such a system, you just have to build-depend on dbs to
-be able to use its functionnalities. The package
+be able to use its functionalities. The package
 <package>hello-dbs</package> is a simple example that demonstrates how to
 use <package>dbs</package>.
 	<p>
-Additionnaly, dbs provides facilities to create the patches and to keep
+Additionally, dbs provides facilities to create the patches and to keep
 track of what they are for.
 
 	<sect1 id="multiple-binary">Multiple binary packages
@@ -2628,7 +2711,7 @@ A single source package will often build several binary packages, either
 to provide several flavors of the same software (examples are the
 vim-* packages) or to make several small packages instead of a big one
 (it's interesting if the user doesn't need all the packages and can thus
-save some diskspace).
+save some disk space).
 	<p>
 The second case can be easily managed by <prgn>dh_install</prgn> (from
 <package>debhelper</package>) to move files from the build directory to
@@ -2663,8 +2746,8 @@ automatically done by <prgn>dh_installdebconf</prgn> (package
 do the same with <prgn>debconf-mergetemplate</prgn>
 (package <package>debconf-utils</package>). 
 	<p>
-When the package maintainer needs to update the templates file, he only
-changes <file>debian/templates</file>.  When English strings in this file
+When the package maintainer needs to update the templates file, they only
+change <file>debian/templates</file>.  When English strings in this file
 and in <file>debian/templates.xx</file> differ, translators do know that
 their translation is outdated.
 	<p>
@@ -2697,8 +2780,8 @@ Good practices for library packaging have been grouped in
 	
 	<sect1 id="bpp-other-specific-practices">Other specific packages
 	<p>
-Several subsets of packages have special subpolicies and corresponding
-packaging rules and practices :
+Several subsets of packages have special sub-policies and corresponding
+packaging rules and practices:
 <list>
     <item>
 Perl related packages have a <url name="perl policy" id="&url-perl-policy;">,
@@ -2706,7 +2789,7 @@ some examples of packages following that policy are
 <package>libdbd-pg-perl</package> (binary perl module) or 
 <package>libmldbm-perl</package> (arch independent perl module).
     <item>
-Python related packages have their python policy :
+Python related packages have their python policy:
 &file-python-policy; (in the python package).
     <item>
 Emacs related packages have the <url id="&url-emacs-policy;"
@@ -2715,8 +2798,8 @@ name="emacs policy">.
 Java related packages have their <url id="&url-java-policy;"
 name="java policy">.
     <item>
-Ocaml related packages have their ocaml policy : &file-ocaml-policy; (in
-the ocaml package). A good example is the <package>camlzip</package>
+Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in
+the <package>ocaml</package> package). A good example is the <package>camlzip</package>
 source package.
 </list>
 
@@ -2727,13 +2810,13 @@ source package.
 	<p>
 Debconf is a configuration management system, it is used by all the
 various packaging scripts (postinst mainly) to request feedback from the
-user in the intent to configure the package. Direct user interactions
+user concerning how to configure the package. Direct user interactions
 must now be avoided in favor of debconf interaction. This will enable
 non-interactive installations in the future.
 	<p>
 Debconf is a great tool but it is often badly used ... many common mistakes
-are listed in the <manref name="debconf-devel" section="8"> manpage. 
-It is something that you must have read if you decide to use debconf.
+are listed in the <manref name="debconf-devel" section="8"> man page. 
+It is something that you must read if you decide to use debconf.
 
 <!--
 	<sect1 id="custom-config-files">Custom configuration files
@@ -2751,28 +2834,32 @@ It is something that you must have read if you decide to use debconf.
 -->	
 
     <sect id="misc-advice">
-	<heading>Miscellaenous advice</heading>
+	<heading>Miscellaneous advice</heading>
 
 	<sect1 id="writing-desc">
 	    <heading>Writing useful descriptions</heading>
 	    <p>
 The description of the package (as defined by the corresponding field
 in the <file>control</file> file) is usually the first information
-available to the user before he installs it. As such, it should
+available to the user before they install it. As such, it should
 provide all the required information to let him decide whether
 to install the package.
 	    <p>
 For example, apart from the usual description that you adapt from the
 upstream <file>README</file>, you should include the URL of the
-website if there's any. If the package is not yet considered stable
+web site if there's any. If the package is not yet considered stable
 by the author, you may also want to warn the user that the
 package is not ready for production use.
 	    <p>
+For consistency and for an aesthetic concern, you should capitalize the
+first letter of the description.
+	    <p>
 Last but not least, since the first user impression is based on
-that description, you should be careful to avoid english
+that description, you should be careful to avoid English
 mistakes. Ensure that you spell check it.
-<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that :
-<example>ispell -d american -g debian/control</example>
+<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that:
+<example>ispell -d american -g debian/control</example>.
+
 
 
 
@@ -2817,7 +2904,7 @@ out all the bugs you submitted, you just have to visit
       <sect1 id="submit-many-bugs">Reporting lots of bugs at once
 	<p>
 Reporting a great number of bugs for the same problem on a great
-number of different packages &mdash i.e., more than 10 &mdash is a deprecated
+number of different packages &mdash; i.e., more than 10 &mdash; is a deprecated
 practice.  Take all possible steps to avoid submitting bulk bugs at
 all.  For instance, if checking for the problem can be automated, add
 a new check to <package>lintian</package> so that an error or warning
@@ -2858,8 +2945,8 @@ If you do not get a reply after a few weeks you should collect all
 useful information about this maintainer. Start by logging into 
 the <url id="&url-debian-db;" name="Debian Developer's Database">
 and doing a full search to check whether the maintainer is on vacation
-and when he was last seen. Collect any important package names
-he maintains and any Release Critical bugs filled against them.
+and when they were last seen. Collect any important package names
+they maintain and any Release Critical bugs filed against them.
       <p>
 Send all this information to &email-debian-qa;, in order to let the 
 QA people do whatever is needed.
@@ -2879,7 +2966,7 @@ email the maintainer, whatever their individual email address (or
 addresses) may be.  Replace <tt>&lt;package&gt;</tt> with the name of
 a source or a binary package.
       <p>
-You may also be interested by contacting the persons who are
+You may also be interested in contacting the persons who are
 subscribed to a given source package via <ref id="pkg-tracking-system">.
 You can do so by using the <tt>&lt;package-name&gt;@&pts-host;</tt>
 email address.
@@ -2907,7 +2994,7 @@ id="&url-sponsors;">.
 New maintainers usually have certain difficulties creating Debian packages
 &mdash; this is quite understandable. That is why the sponsor is there, to check
 the package and verify that it is good enough for inclusion in Debian.
-(Note that if the sponsored package is new, the FTP admins will also have to
+(Note that if the sponsored package is new, the ftpmasters will also have to
 inspect it before letting it in.)
 	<p>
 Sponsoring merely by signing the upload or just recompiling is
@@ -2930,9 +3017,9 @@ You can not simply upload a binary <file>.deb</file> from the sponsoree. In
 theory, you should only ask only for the diff file, and the location of the
 original source tarball, and then you should download the source and apply
 the diff yourself. In practice, you may want to use the source package
-built by your sponsoree. In that case you have to check that he hasn't
-altered the upstream files in the <file>.orig.tar.gz</file> file that he's
-providing.
+built by your sponsoree. In that case, you have to check that they haven't
+altered the upstream files in the <file>.orig.tar.gz</file> file that
+they're providing.
 	<p>
 Do not be afraid to write the sponsoree back and point out changes
 that need to be made.  It often takes several rounds of back-and-forth