gender neutral. #384178

[developers-reference.git] / developers-reference.sgml

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 903282b620db2a5964d7db1b874b662364b8b3ba..a6713b2451e7ad133223cf3fb21f666934d2de53 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -7,7 +7,7 @@
   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
 
   <!-- CVS revision of this document -->
   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
 
   <!-- CVS revision of this document -->

-  <!ENTITY cvs-rev "$Revision: 1.316 $">
+  <!ENTITY cvs-rev "$Revision: 1.322 $">

 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->


@@ -252,7 +252,7 @@ Version 4 (primary) keys can either use the RSA or the DSA algorithms,
 so this has nothing to do with GnuPG's question about "which kind
 of key do you want: (1) DSA and Elgamal, (2) DSA (sign only), (5)
 RSA (sign only)".  If you don't have any special requirements just pick
 so this has nothing to do with GnuPG's question about "which kind
 of key do you want: (1) DSA and Elgamal, (2) DSA (sign only), (5)
 RSA (sign only)".  If you don't have any special requirements just pick

-the defailt.
+the default.

 <p>
 The easiest way to tell whether an existing key is a v4 key or a v3
 (or v2) key is to look at the fingerprint:
 <p>
 The easiest way to tell whether an existing key is a v4 key or a v3
 (or v2) key is to look at the fingerprint:


@@ -474,7 +474,9 @@ Send an gpg-signed email about why you are leaving the project to
 &email-debian-private;.
            <item>
 Notify the Debian key ring maintainers that you are leaving by
 &email-debian-private;.
            <item>
 Notify the Debian key ring maintainers that you are leaving by

-emailing to &email-debian-keyring;.
+opening a ticket in Debian RT by sending a mail 
+to keyring@rt.debian.org with the words 'Debian RT' somewhere in the subject
+line (case doesn't matter).

 </enumlist>
 
 
 </enumlist>
 
 


@@ -3182,19 +3184,9 @@ patch to be sent. If you want the package to be recompiled for all
 architectures, then you do a source NMU as usual and you will have to
 send a patch.
          <p>
 architectures, then you do a source NMU as usual and you will have to
 send a patch.
          <p>

-If the source NMU (non-maintainer upload) fixes some existing bugs,
-these bugs should be tagged <em>fixed</em> in the Bug Tracking
-System rather than closed.  By convention, only the official package
-maintainer or the original bug submitter close bugs.
-Fortunately, Debian's archive system recognizes NMUs and thus marks
-the bugs fixed in the NMU appropriately if the person doing the NMU
-has listed all bugs in the changelog with the <tt>Closes:
-bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for
-more information describing how to close bugs via the changelog).
-Tagging the bugs <em>fixed</em> ensures that everyone knows that the
-bug was fixed in an NMU; however the bug is left open until the
-changes in the NMU are incorporated officially into the package by
-the official package maintainer.
+Bugs fixed by source NMUs used to be tagged fixed instead of closed,
+but since version tracking is in place, such bugs are now also
+closed with the NMU version.

          <p>
 Also, after doing an NMU, you have to send
 the information to the existing bugs that are fixed by your NMU,
          <p>
 Also, after doing an NMU, you have to send
 the information to the existing bugs that are fixed by your NMU,


@@ -4331,8 +4323,7 @@ would write a scientific paper.
        <sect2>Be gender neutral
        <p>
 The world is made of men and women. Please use gender-neutral
        <sect2>Be gender neutral
        <p>
 The world is made of men and women. Please use gender-neutral

-constructions in your writing. This is not Political Correctness, this
-is showing respect to all humanity.
+constructions in your writing.

 
 
        <sect1>Templates fields definition
 
 
        <sect1>Templates fields definition


@@ -4385,17 +4376,13 @@ This type is now considered obsolete: don't use it.
 
        <sect3>error:
        <p>
 
        <sect3>error:
        <p>

-<strong>THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.</strong>
-       <p>
-It has been added to cdebconf, the C version of debconf, first used in
-the Debian Installer.
-       <p>
-Please do not use it unless debconf supports it.
-       <p>
-This type is designed to handle error message. It is mostly similar to
+This type is designed to handle error messages. It is mostly similar to

 the "note" type. Frontends may present it differently (for instance,
 the dialog frontend of cdebconf draws a red screen instead of the
 usual blue one).
 the "note" type. Frontends may present it differently (for instance,
 the dialog frontend of cdebconf draws a red screen instead of the
 usual blue one).

+       <p>
+It is recommended to use this type for any message that needs user
+attention for a correction of any kind.

 
 
        <sect2>Description: short and extended description
 
 
        <sect2>Description: short and extended description


@@ -5013,6 +5000,56 @@ build process.
        </p>
        </sect2>
     </sect1>
        </p>
        </sect2>
     </sect1>

+    <sect1 id="bpp-dbg">
+        <heading>Best practices for debug packages</heading>
+       <p>
+A debug package is a package with a name ending in "-dbg", that contains
+additional information that gdb can use. Since Debian binaries are
+stripped by default, debugging information, including function names and
+line numbers, is otherwise not available when running gdb on Debian binaries.
+Debug packages allow users who need this additional debugging information to
+install it, without bloating a regular system with the information.
+       <p>
+It is up to a package's maintainer whether to create a debug package or
+not. Maintainers are encouraged to create debug packages for library
+packages, since this can aid in debugging many programs linked to a
+library. In general, debug packages do not need to be added for all
+programs; doing so would bloat the archive. But if a maintainer finds
+that users often need a debugging version of a program, it can be
+worthwhile to make a debug package for it. Programs that are core
+infrastructure, such as apache and the X server are also good candidates
+for debug packages.
+       <p>
+Some debug packages may contain an entire special debugging build of a
+library or other binary, but most of them can save space and build time
+by instead containing separated debugging symbols that gdb can find and
+load on the fly when debugging a program or library. The convention in
+Debian is to keep these symbols in <file>/usr/lib/debug/<em>path</em></file>,
+where <em>path</em> is the path to the executable or library. For example,
+debugging symbols for <file>/usr/bin/foo</file> go in
+<file>/usr/lib/debug/usr/bin/foo</file>, and
+debugging symbols for <file>/usr/lib/libfoo.so.1</file> go in
+<file>/usr/lib/debug/usr/lib/libfoo.so.1</file>.
+       <p>
+The debugging symbols can be extracted from an object file using 
+"objcopy --only-keep-debug". Then the object file can be stripped, and
+"objcopy --add-gnu-debuglink" used to specify the path to the debugging
+symbol file. <manref name="objcopy" section="1"> explains in detail how this
+works.
+       <p>
+The dh_strip command in debhelper supports creating debug packages, and
+can take care of using objcopy to separate out the debugging symbols for
+you. If your package uses debhelper, all you need to do is call 
+"dh_strip --dbg-package=libfoo-dbg", and add an entry to debian/control
+for the debug package.
+       <p>
+Note that the Debian package should depend on the package that it
+provides debugging symbols for, and this dependency should be versioned.
+For example:
+
+<example>
+Depends: libfoo-dbg (= ${binary:Version})
+</example>

 
 
       </sect>
 
 
       </sect>