rewrote the mailing lists section to have logical subsections; expanded on the meanin...

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

diff --git a/developers-reference.sgml b/developers-reference.sgml
index fe20bafd3ebe539c16ff36d0f7b599fb52cbace6..3b1206feb930bff99b49e0076307e098b909c228 100644 (file)
--- 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.120 $">
+  <!entity cvs-rev "$Revision: 1.121 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -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
@@ -408,29 +408,64 @@ 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
@@ -446,13 +481,6 @@ in the <file>~debian/archive/debian-private</file> directory.
 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>