chiark / gitweb /
Fixed all examples, fixed many (not all, yet) entities.
authordebacle <debacle@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sat, 30 Jun 2007 13:21:18 +0000 (13:21 +0000)
committerdebacle <debacle@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sat, 30 Jun 2007 13:21:18 +0000 (13:21 +0000)
git-svn-id: svn://anonscm.debian.org/ddp/developers-reference/trunk@4910 313b444b-1b9f-4f58-a734-7bb04f332e8d

12 files changed:
Makefile
best-pkging-practices.dbk
beyond-pkging.dbk
common.ent [new file with mode: 0644]
developer-duties.dbk
index.dbk
l10n.dbk
new-maintainer.dbk
pkgs.dbk
resources.dbk
scope.dbk
tools.dbk

index 8dfc96d..2dfbe39 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 # Makefile, used for the developers-reference in DocBook XML
 
-SOURCES                := $(wildcard *.dbk)
+SOURCES                := $(wildcard *.dbk *.ent)
 
 FORMATS                := html txt pdf
 LANGS           := fr ja
@@ -12,8 +12,11 @@ TARGETS              := $(foreach fmt,$(FORMATS),developers-reference.$(fmt)) \
 XP=xsltproc --nonet --novalid --xinclude
 XL=xmllint --nonet --noout --postvalid --xinclude
 # fop is currently in contrib, but can go to main, see #366783
-# alternatives: docbook2pdf (seems to die on UTF-8), dblatex (0.2.4
-# just hangs here) and xmllint (not mature enough, waits in NEW)
+# Alternatives:
+# - dblatex (0.2.6 has a minor problem with programlisting inside of
+#   footnote, and a major one with lang="ja");
+# - docbook2pdf (seems to die on UTF-8, #431085); and
+# - xmllint (not mature enough, waits in NEW, #182445)
 FOP=fop
 # The "-k 0" should be removed as soon as the translations are ready
 TRANSLATE=po4a-translate -f docbook -k 0
@@ -36,9 +39,12 @@ DBK2FO=$$TOP/fop.xsl
 all:    $(TARGETS)
 
 .PHONY: validate
-validate:
+validate:                      $(SOURCES)
        $(XL) index.dbk
 
+%/validate:                    $(addprefix %/,$(SOURCES))
+       cd $(@D) && $(XL) index.dbk
+
 .PHONY: developers-reference.html %/developers-reference.html
 developers-reference.html:     $(PWD)/index.html
 %/developers-reference.html:   $(addprefix %/,index.html)
@@ -47,18 +53,20 @@ developers-reference.html:  $(PWD)/index.html
 .PRECIOUS:                     %/index.html
 index.html:                    $(PWD)/developers-reference.html
 %/index.html:                  $(addprefix %/,$(SOURCES))
-       mkdir -p $(@D) || true
        cd $(@D) && $(XP) $(DBK2HTML) index.dbk
 
 # There must be an easier way than recursive make!
-.PRECIOUS:             %.dbk
+.PRECIOUS:             %.dbk %.ent
 ifndef LINGUA
-%.dbk: FORCE
-       [ "$$LINGUA" = . ] || make $@ LINGUA=$(@D)
+%.dbk %.ent: FORCE
+       [ "$$LINGUA" = . ] || $(MAKE) $@ LINGUA=$(@D)
 FORCE:
 else
 $(LINGUA)/%.dbk:       %.dbk $(patsubst %.dbk,po4a/$(LINGUA)/%.po,%.dbk)
        $(TRANSLATE) -m $< -p po4a/$(@:.dbk=.po) -l $@
+
+$(LINGUA)/%.ent:       %.ent
+       cd $(@D) && ln -sf ../$(@F) .
 endif
 
 developers-reference.txt:      $(PWD)/developers-reference.txt
index 63b7f87..981c35f 100644 (file)
@@ -1,11 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="best-pkging-practices">
 <title>Best Packaging Practices</title>
 <para>
 Debian's quality is largely due to the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink>, which
+url="&url-debian-policy;">Debian Policy</ulink>, 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 accumulation of years of experience in packaging.  Many very
@@ -153,7 +155,7 @@ this using an hand-crafted <filename>debian/rules</filename> file.
 <para>
 The following practices are relevant to the <filename>debian/control</filename>
 file.  They supplement the <ulink
-url="http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions">Policy
+url="&url-debian-policy;ch-binary.html#s-descriptions">Policy
 on package descriptions</ulink>.
 </para>
 <para>
@@ -201,7 +203,7 @@ Postscript or postscript.
 </para>
 <para>
 If you are having problems writing your description, you may wish to send it
-along to <email>debian-l10n-english@lists.debian.org</email> and request
+along to <email>debian-l10n-english@&lists-host;</email> and request
 feedback.
 </para>
 </section>
@@ -278,10 +280,10 @@ it.  Both <command>ispell</command> and <command>aspell</command> have special
 modes for checking <filename>debian/control</filename> files:
 </para>
 <screen>
- -d american -g debian/control
+ispell -d american -g debian/control
 </screen>
 <screen>
- -d en -D -c debian/control
+aspell -d en -D -c debian/control
 </screen>
 <para>
 Users usually expect these questions to be answered in the package description:
@@ -341,7 +343,7 @@ added at the end of description, using the following format:
 <para>
 Note the spaces prepending the line, which serves to break the lines correctly.
 To see an example of how this displays, see <ulink
-url="http://packages.debian.org/unstable/web/wml"></ulink>.
+url="http://&packages-host;/unstable/web/wml"></ulink>.
 </para>
 <para>
 If there is no home page for the software, this should naturally be left out.
@@ -349,11 +351,11 @@ If there is no home page for the software, this should naturally be left out.
 <para>
 Note that we expect this field will eventually be replaced by a proper
 <filename>debian/control</filename> field understood by <command>dpkg</command>
-and <literal>packages.debian.org</literal>.  If you don't want to bother
+and <literal>&packages-host;</literal>.  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.  Please make sure that this line matches the
 regular expression <literal>/^ Homepage: [^ ]*$/</literal>, as this allows
-<filename>packages.debian.org</filename> to parse it correctly.
+<filename>&packages-host;</filename> to parse it correctly.
 </para>
 </section>
 
@@ -427,7 +429,7 @@ the URL is in the <literal>svn://</literal> scheme (instead of
 <title>Best practices for <filename>debian/changelog</filename></title>
 <para>
 The following practices supplement the <ulink
-url="http://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs">Policy
+url="&url-debian-policy;ch-docs.html#s-changelogs">Policy
 on changelog files</ulink>.
 </para>
 <section id="bpp-changelog-do">
@@ -582,7 +584,7 @@ as it will not be automatically checked during build as the changelog is.  Here
 is an example of a real NEWS.Debian file:
 </para>
 <screen>
- (3.0pl1-74) unstable; urgency=low
+cron (3.0pl1-74) unstable; urgency=low
 
     The checksecurity script is no longer included with the cron package:
     it now has its own package, checksecurity. If you liked the
@@ -613,7 +615,7 @@ NEWS.Debian file in your package.  No news is good news!
 <para>
 FIXME: presentation of cvs-buildpackage, updating sources
 via CVS (debian/rules refresh).
-<ulink url="http://www.debian.org/devel/cvs_packages">"http://www.debian.org/devel/cvs_packages"</ulink>
+<ulink url="&url-devel-docs;cvs_packages">"&url-devel-docs;cvs_packages"</ulink>
 </para>
 </section>
 -->
@@ -626,7 +628,7 @@ Maintainer scripts include the files <filename>debian/postinst</filename>,
 <filename>debian/postrm</filename>.  These scripts take care of any package
 installation or deinstallation setup which isn't handled merely by the creation
 or removal of files and directories.  The following instructions supplement the
-<ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink>.
+<ulink url="&url-debian-policy;">Debian Policy</ulink>.
 </para>
 <para>
 Maintainer scripts must be idempotent.  That means that you need to make sure
@@ -661,27 +663,12 @@ maintainer script.
 If you need to check for the existence of a command, you should use something
 like
 </para>
-<screen>
- [ -x /usr/sbin/install-docs ]; then ...
-</screen>
+<programlisting>if [ -x /usr/sbin/install-docs ]; then ...</programlisting>
 <para>
 If you don't wish to hard-code the path of a command in your maintainer script,
 the following POSIX-compliant shell function may help:
 </para>
-<screen>
-() {
-    OLDIFS=$IFS
-    IFS=:
-    for p in $PATH; do
-        if [ -x $p/$* ]; then
-            IFS=$OLDIFS
-            return 0
-        fi
-    done
-    IFS=$OLDIFS
-    return 1
-}
-</screen>
+&example-pathfind;
 <para>
 You can use this function to search <literal>$PATH</literal> for a command
 name, passed as an argument.  It returns true (zero) if the command was found,
@@ -753,7 +740,7 @@ Most Debian package maintainers are not native English speakers.  So, writing
 properly phrased templates may not be easy for them.
 </para>
 <para>
-Please use (and abuse) <email>debian-l10n-english@lists.debian.org</email>
+Please use (and abuse) <email>debian-l10n-english@&lists-host;</email>
 mailing list.  Have your templates proofread.
 </para>
 <para>
@@ -796,11 +783,11 @@ translations and request them for updates.
 </para>
 <para>
 If in doubt, you may also contact the translation team for a given language
-(debian-l10n-xxxxx@lists.debian.org), or the
-<email>debian-i18n@lists.debian.org</email> mailing list.
+(debian-l10n-xxxxx@&lists-host;), or the
+<email>debian-i18n@&lists-host;</email> mailing list.
 </para>
 <para>
-Calls for translations posted to <email>debian-i18n@lists.debian.org</email>
+Calls for translations posted to <email>debian-i18n@&lists-host;</email>
 with the <filename>debian/po/templates.pot</filename> file attached or
 referenced in a URL are encouraged.  Be sure to mentions in these calls for new
 translations which languages you have existing translations for, in order to
@@ -831,10 +818,8 @@ Put all incomplete PO files out of the way.  You can check the completeness by
 using (needs the <systemitem role="package">gettext</systemitem> package
 installed):
 </para>
-<screen>
- i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
---statistics $i; done
-</screen>
+<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done</programlisting>
 </listitem>
 <listitem>
 <para>
@@ -860,9 +845,7 @@ modified in translations.  You can see this by running the above again
 <para>
 use the following command:
 </para>
-<screen>
- i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done
-</screen>
+<programlisting>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</programlisting>
 </listitem>
 <listitem>
 <para>
@@ -1206,7 +1189,7 @@ using English.
 Example, taken from the geneweb package templates:
 </para>
 <screen>
-: geneweb/lang
+Template: geneweb/lang
 Type: select
 __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
 # This is the default choice. Translators may put their own language here
@@ -1300,7 +1283,7 @@ differences between two versions of the documentation, so, for instance, they
 can see what needs to be retranslated.  It is recommended that the translated
 documentation maintain a note about what source control revision the
 translation is based on.  An interesting system is provided by <ulink
-url="http://cvs.debian.org/boot-floppies/documentation/doc-check?rev=HEAD\|[amp
+url="&url-cvsweb;boot-floppies/documentation/doc-check?rev=HEAD\|[amp
 ]\|content-type=text/vnd.viewcvs-markup">doc-check</ulink> in the <systemitem
 role="package">boot-floppies</systemitem> package, which shows an overview of
 the translation status for any given language, using structured comments for
@@ -1337,7 +1320,7 @@ Keeping <command>autoconf</command>'s <filename>config.sub</filename> and
 especially on more volatile architectures.  Some very good packaging practices
 for any package using <command>autoconf</command> and/or
 <command>automake</command> have been synthesized in
-<filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename> from the
+&file-bpp-autotools; from the
 <systemitem role="package">autotools-dev</systemitem> package.  You're strongly
 encouraged to read this file and to follow the given recommendations.
 </para>
@@ -1353,7 +1336,7 @@ library can result in dozens of dependent packages breaking.
 </para>
 <para>
 Good practices for library packaging have been grouped in <ulink
-url="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/">the library
+url="&url-libpkg-guide;">the library
 packaging guide</ulink>.
 </para>
 </section>
@@ -1362,7 +1345,7 @@ packaging guide</ulink>.
 <title>Documentation</title>
 <para>
 Be sure to follow the <ulink
-url="http://www.debian.org/doc/debian-policy/ch-docs.html">Policy on
+url="&url-debian-policy;ch-docs.html">Policy on
 documentation</ulink>.
 </para>
 <para>
@@ -1395,7 +1378,7 @@ packaging rules and practices:
 <listitem>
 <para>
 Perl related packages have a <ulink
-url="http://www.debian.org/doc/packaging-manuals/perl-policy/">Perl
+url="&url-perl-policy;">Perl
 policy</ulink>, some examples of packages following that policy are <systemitem
 role="package">libdbd-pg-perl</systemitem> (binary perl module) or <systemitem
 role="package">libmldbm-perl</systemitem> (arch independent perl module).
@@ -1411,14 +1394,14 @@ Python related packages have their python policy; see
 <listitem>
 <para>
 Emacs related packages have the <ulink
-url="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy">emacs
+url="&url-emacs-policy;">emacs
 policy</ulink>.
 </para>
 </listitem>
 <listitem>
 <para>
 Java related packages have their <ulink
-url="http://www.debian.org/doc/packaging-manuals/java-policy/">java
+url="&url-java-policy;">java
 policy</ulink>.
 </para>
 </listitem>
@@ -1440,7 +1423,7 @@ in the <systemitem role="package">sgml-base-doc</systemitem> package.
 <para>
 Lisp packages should register themselves with <systemitem
 role="package">common-lisp-controller</systemitem>, about which see
-<filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>.
+&file-lisp-controller;.
 </para>
 </listitem>
 <!-- TODO: mozilla extension policy, once that becomes available -->
@@ -1495,12 +1478,12 @@ If you need a certain locale during build, you can create a temporary file via
 this trick:
 </para>
 <para>
-If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name
+If you set <varname>LOCPATH</varname> to the equivalent of <literal>/usr/lib/locale</literal>, and <varname>LC_ALL</varname> to the name
 of the locale you generate, you should get what you want without being root.
 Something like this:
 </para>
 <screen>
-=debian/tmpdir/usr/lib/locale
+LOCALE_PATH=debian/tmpdir/usr/lib/locale
 LOCALE_NAME=en_IN
 LOCALE_CHARSET=UTF-8
 
@@ -1530,18 +1513,8 @@ description.
 <para>
 So, when you are creating such a package, please make sure to add this text to
 your short description.  If you are looking for examples, just run:
-</para>
-<screen>
--cache search .|grep dummy
-</screen>
-<para>
-or
-</para>
-<screen>
--cache search .|grep transitional
-</screen>
-<para>
-.
+<command>apt-cache search .|grep dummy</command> or
+<command>apt-cache search .|grep transitional</command>.
 </para>
 </section>
 
@@ -1585,7 +1558,7 @@ tarballs as pristine source.  Its strategy is equivalent to the following:
 It unpacks the tarball in an empty temporary directory by doing
 </para>
 <screen>
- path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
+zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
 </screen>
 </listitem>
 <listitem>
@@ -1648,7 +1621,7 @@ repackaged source was obtained, and how this can be reproduced in the
 <literal>get-orig-source</literal> target in your
 <filename>debian/rules</filename> file that repeats the process, as described
 in the Policy Manual, <ulink
-url="http://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules">Main
+url="&url-debian-policy;ch-source.html#s-debianrules">Main
 building script: debian/rules</ulink>.
 </para>
 </listitem>
@@ -1718,9 +1691,10 @@ postfix indicating the encoding should be appended to the original filename.
 Note that you don't need to depend on <systemitem
 role="package">sharutils</systemitem> to get the <command>uudecode</command>
 program if you use <command>perl</command>'s <literal>pack</literal> function.
-The code could look like </para> <screen> -file: perl -ne 'print(pack u, $$_);'
-$(file) &gt; $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, $$_);'
-$(file).uuencoded &gt; $(file) </screen> </footnote>.  The file would then be
+The code could look like
+</para>
+&example-uu;
+</footnote>.  The file would then be
 decoded and copied to its place during the build process.  Thus the change will
 be visible quite easy.
 </para>
@@ -1788,7 +1762,7 @@ Note that the Debian package should depend on the package that it provides
 debugging symbols for, and this dependency should be versioned.  For example:
 </para>
 <screen>
-: libfoo-dbg (= ${binary:Version})
+Depends: libfoo-dbg (= ${binary:Version})
 </screen>
 </section>
 
index f5c7be8..9b8de92 100644 (file)
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="beyond-pkging">
 <title>Beyond Packaging</title>
 <para>
@@ -21,9 +23,9 @@ Debian developers are often the first line testers.  Finding and reporting bugs
 in other developers' packages improves the quality of Debian.
 </para>
 <para>
-Read the <ulink url="http://www.debian.org/Bugs/Reporting">instructions for
+Read the <ulink url="&url-bts-report;">instructions for
 reporting bugs</ulink> in the Debian <ulink
-url="http://www.debian.org/Bugs/">bug tracking system</ulink>.
+url="&url-bts;">bug tracking system</ulink>.
 </para>
 <para>
 Try to submit the bug from a normal user account at which you are likely to
@@ -38,7 +40,7 @@ generally ease the process.
 <para>
 Make sure the bug is not already filed against a package.  Each package has a
 bug list easily reachable at
-<literal>http://bugs.debian.org/<replaceable>packagename</replaceable></literal>
+<literal>http://&bugs-host;/<replaceable>packagename</replaceable></literal>
 Utilities like <citerefentry> <refentrytitle>querybts</refentrytitle>
 <manvolnum>1</manvolnum> </citerefentry> can also provide you with this
 information (and <command>reportbug</command> will usually invoke
@@ -62,7 +64,7 @@ From time to time you may want to check what has been going on with the bug
 reports that you submitted.  Take this opportunity to close those that you
 can't reproduce anymore.  To find out all the bugs you submitted, you just have
 to visit
-<literal>http://bugs.debian.org/from:<replaceable>&lt;your-email-addr&gt;</replaceable></literal>.
+<literal>http://&bugs-host;/from:<replaceable>&lt;your-email-addr&gt;</replaceable></literal>.
 </para>
 <section id="submit-many-bugs">
 <title>Reporting lots of bugs at once (mass bug filing)</title>
@@ -75,7 +77,7 @@ role="package">lintian</systemitem> so that an error or warning is emitted.
 </para>
 <para>
 If you report more than 10 bugs on the same topic at once, it is recommended
-that you send a message to <email>debian-devel@lists.debian.org</email>
+that you send a message to <email>debian-devel@&lists-host;</email>
 describing your intention before submitting the report, and mentioning the fact
 in the subject of your mail.  This will allow other developers to verify that
 the bug is a real problem.  In addition, it will help prevent a situation in
@@ -85,11 +87,11 @@ which several maintainers start filing the same bug report simultaneously.
 Please use the programms <command>dd-list</command> and if appropriate
 <command>whodepends</command> (from the package devscripts) to generate a list
 of all affected packages, and include the output in your mail to
-<email>debian-devel@lists.debian.org</email>.
+<email>debian-devel@&lists-host;</email>.
 </para>
 <para>
 Note that when sending lots of bugs on the same subject, you should send the
-bug report to <email>maintonly@bugs.debian.org</email> so that the bug report
+bug report to <email>maintonly@&bugs-host;</email> so that the bug report
 is not forwarded to the bug distribution mailing list.
 </para>
 </section>
@@ -108,8 +110,8 @@ linkend="lintian"/> ) as possible.  If you do not find that possible, then you
 should consider orphaning some of your packages (see <xref
 linkend="orphaning"/> ).  Alternatively, you may ask the help of other people
 in order to catch up with the backlog of bugs that you have (you can ask for
-help on <email>debian-qa@lists.debian.org</email> or
-<email>debian-devel@lists.debian.org</email>).  At the same time, you can look
+help on <email>debian-qa@&lists-host;</email> or
+<email>debian-devel@&lists-host;</email>).  At the same time, you can look
 for co-maintainers (see <xref linkend="collaborative-maint"/> ).
 </para>
 </section>
@@ -119,7 +121,7 @@ for co-maintainers (see <xref linkend="collaborative-maint"/> ).
 <para>
 From time to time the QA group organizes bug squashing parties to get rid of as
 many problems as possible.  They are announced on
-<email>debian-devel-announce@lists.debian.org</email> and the announcement
+<email>debian-devel-announce@&lists-host;</email> and the announcement
 explains which area will be the focus of the party: usually they focus on
 release critical bugs but it may happen that they decide to help finish a major
 upgrade (like a new perl version which requires recompilation of all the binary
@@ -160,7 +162,7 @@ version is available and that you need it.
 <para>
 Looking up the email address of the maintainer for the package can be
 distracting.  Fortunately, there is a simple email alias,
-<literal>&lt;package&gt;@packages.debian.org</literal>, which provides a way to
+<literal>&lt;package&gt;@&packages-host;</literal>, which provides a way to
 email the maintainer, whatever their individual email address (or addresses)
 may be.  Replace <literal>&lt;package&gt;</literal> with the name of a source
 or a binary package.
@@ -168,7 +170,7 @@ or a binary package.
 <para>
 You may also be interested in contacting the persons who are subscribed to a
 given source package via <xref linkend="pkg-tracking-system"/> .  You can do so
-by using the <literal>&lt;package&gt;@packages.qa.debian.org</literal> email
+by using the <literal>&lt;package&gt;@&pts-host;</literal> email
 address.
 </para>
 <!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
@@ -189,12 +191,7 @@ maintainers who are deemed Missing In Action is recorded.  When a member of the
 QA group contacts an inactive maintainer or finds more information about one,
 this is recorded in the MIA database.  This system is available in
 /org/qa.debian.org/mia on the host qa.debian.org, and can be queried with a
-tool known as <command>mia-query</command>.  Use
-</para>
-<screen>
--query --help
-</screen>
-<para>
+tool known as <command>mia-query</command>.  Use <command>mia-query --help</command>
 to see how to query the database.  If you find that no information has been
 recorded about an inactive maintainer yet, or that you can add more
 information, you should generally proceed as follows.
@@ -215,7 +212,7 @@ maintainer in question as possible.  This includes:
 <listitem>
 <para>
 The echelon information available through the <ulink
-url="https://db.debian.org/">developers' LDAP database</ulink>, which indicates
+url="&url-debian-db;">developers' LDAP database</ulink>, which indicates
 when the developer last posted to a Debian mailing list.  (This includes
 uploads via debian-*-changes lists.) Also, remember to check whether the
 maintainer is marked as on vacation in the database.
@@ -248,7 +245,7 @@ happened to the person they sponsored.
 </para>
 <para>
 It is also allowed to post a query to
-<email>debian-devel@lists.debian.org</email>, asking if anyone is aware of the
+<email>debian-devel@&lists-host;</email>, asking if anyone is aware of the
 whereabouts of the missing maintainer.  Please Cc: the person in question.
 </para>
 <para>
@@ -348,7 +345,7 @@ package is in acceptable shape.  Being a sponsor means being a mentor.
 Once the package meets Debian standards, build and sign it with
 </para>
 <screen>
--buildpackage -k<replaceable>KEY-ID</replaceable>
+dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>
 </screen>
 <para>
 before uploading it to the incoming directory.  Of course, you can also use any
@@ -375,7 +372,7 @@ linkend="pkg-tracking-system"/> .
 <title>Advocating new developers</title>
 <para>
 See the page about <ulink
-url="http://www.debian.org/devel/join/nm-advocate">advocating a prospective
+url="&url-devel-docs;join/nm-advocate">advocating a prospective
 developer</ulink> at the Debian web site.
 </para>
 </section>
@@ -384,7 +381,7 @@ developer</ulink> at the Debian web site.
 <title>Handling new maintainer applications</title>
 <para>
 Please see <ulink
-url="http://www.debian.org/devel/join/nm-amchecklist">Checklist for Application
+url="&url-devel-docs;join/nm-amchecklist">Checklist for Application
 Managers</ulink> at the Debian web site.
 </para>
 </section>
diff --git a/common.ent b/common.ent
new file mode 100644 (file)
index 0000000..5a09ece
--- /dev/null
@@ -0,0 +1,251 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- common entities file
+
+     Bits of text which are language independent.  In some cases it
+     makes sense to break these out because repetitively maintaining
+     them in different translations of the Developer's Reference is
+     wasteful.  In other cases, the data is rather volatile and
+     breaking it out make maintenance easier.
+  -->
+
+<!-- volatile information -->
+
+<!ENTITY number-of-pkgs "9000">
+<!ENTITY number-of-maintainers "900">
+
+<!ENTITY number-of-arches "12">
+
+<!-- standard information -->
+<!ENTITY fsf-addr "Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA">
+<!ENTITY file-GPL "<filename>/usr/share/common-licenses/GPL</filename>">
+<!ENTITY debian-formal "Debian GNU/Linux">
+
+<!--
+     URLs, Debian
+  -->
+<!ENTITY www-debian-org "www.debian.org">
+<!ENTITY ftp-debian-org "ftp.debian.org">
+<!ENTITY lists-host "lists.debian.org">
+<!ENTITY archive-host "archive.debian.org">
+<!ENTITY keyserver-host "keyring.debian.org">
+<!ENTITY packages-host "packages.debian.org">
+<!ENTITY bugs-host "bugs.debian.org">
+<!ENTITY pts-host "packages.qa.debian.org">
+<!ENTITY ftp-master-host "ftp-master.debian.org">
+<!ENTITY ftp-master-mirror "merkel.debian.org">
+<!ENTITY non-us-host "non-us.debian.org">
+<!ENTITY upload-queue "/pub/UploadQueue/">
+
+<!ENTITY url-debian-policy "http://&www-debian-org;/doc/debian-policy/">
+<!ENTITY url-perl-policy "http://&www-debian-org;/doc/packaging-manuals/perl-policy/">
+<!ENTITY url-emacs-policy "http://&www-debian-org;/doc/packaging-manuals/debian-emacs-policy">
+<!ENTITY url-java-policy "http://&www-debian-org;/doc/packaging-manuals/java-policy/">
+<!ENTITY url-libpkg-guide "http://www.netfort.gr.jp/~dancer/column/libpkg-guide/">
+
+<!ENTITY url-social-contract "http://&www-debian-org;/social_contract">
+<!ENTITY url-constitution "http://&www-debian-org;/devel/constitution">
+<!ENTITY url-dfsg "&url-social-contract;#guidelines">
+<!ENTITY url-debian-lists "http://&www-debian-org;/MailingLists/">
+<!ENTITY url-debian-lists-new "&url-debian-lists;HOWTO_start_list">
+<!ENTITY url-bts "http://&www-debian-org;/Bugs/">
+<!ENTITY url-bts-report "&url-bts;Reporting">
+<!ENTITY url-bts-devel "&url-bts;Developer">
+<!ENTITY url-bts-control "&url-bts;server-control">
+<!ENTITY url-debian-mirrors "http://&www-debian-org;/mirror/">
+<!ENTITY url-debian-mirroring "&url-debian-mirrors;">
+<!ENTITY url-debian-ports "http://&www-debian-org;/ports/">
+<!ENTITY url-debian-port-lists "http://&lists-host;/ports.html">
+<!ENTITY url-wnpp "http://&www-debian-org;/devel/wnpp/">
+<!ENTITY url-devel-docs "http://&www-debian-org;/devel/">
+<!ENTITY url-vote "http://&www-debian-org;/vote/">
+<!ENTITY url-cvsweb "http://cvs.debian.org/">
+<!ENTITY url-devel-machines "http://db.debian.org/machines.cgi">
+<!ENTITY url-buildd "http://buildd.debian.org/">
+<!ENTITY url-lintian "http://lintian.debian.org/">
+<!ENTITY url-debian-qa "http://qa.debian.org/">
+<!ENTITY url-debian-qa-orphaned "&url-debian-qa;orphaned.html">
+<!ENTITY url-debian-db "https://db.debian.org/">
+<!ENTITY url-debian-db-login "&url-debian-db;login.html">
+<!ENTITY url-debian-db-mail-gw "http://db.debian.org/doc-mail.html">
+<!ENTITY url-debian-db-doc "http://db.debian.org/doc-general.html">
+<!ENTITY url-newmaint "&url-devel-docs;join/newmaint">
+<!ENTITY url-newmaint-db "http://nm.debian.org/">
+<!ENTITY url-newmaint-advocate "&url-devel-docs;join/nm-advocate">
+<!ENTITY url-newmaint-amchecklist "&url-devel-docs;join/nm-amchecklist">
+<!ENTITY url-newmaint-apply "http://nm.debian.org/newnm.php">
+<!ENTITY url-newmaint-id "http://&www-debian-org;/devel/join/nm-step2">
+<!ENTITY url-newmaint-guide "http://&www-debian-org;/doc/maint-guide/">
+<!ENTITY url-gpg-coord "http://nm.debian.org/gpg.php">
+<!ENTITY url-debian-security-advisories "http://&www-debian-org;/security/">
+<!ENTITY url-tech-ctte "http://&www-debian-org;/devel/tech-ctte">
+<!ENTITY url-ddpo "http://qa.debian.org/developer.php">
+
+<!ENTITY url-debian-keyring "http://&ftp-debian-org;/debian/doc/debian-keyring.tar.gz">
+<!ENTITY url-readme-non-us "http://&ftp-debian-org;/debian/README.non-US">
+<!ENTITY url-incoming "http://incoming.debian.org/">
+<!ENTITY url-testing-maint "http://www.debian.org/devel/testing">
+<!-- deprecated -->
+<!ENTITY url-testing-faq "&url-testing-maint;">
+
+<!ENTITY us-upload-dir "<filename>/org/ftp.debian.org/incoming/</filename>">
+<!ENTITY non-us-upload-dir "<filename>/org/non-us.debian.org/incoming/</filename>">
+<!ENTITY url-chiark-readme "ftp://ftp.chiark.greenend.org.uk/pub/debian/private/project/README.how-to-upload">
+<!ENTITY url-upload-erlangen "ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue/">
+<!ENTITY url-upload-samosa "ftp://samosa.debian.org/pub/UploadQueue/">
+<!ENTITY url-upload-jp "ftp://master.debian.or.jp/pub/Incoming/upload/">
+
+<!ENTITY url-mentors "http://people.debian.org/~mpalmer/debian-mentors_FAQ.html">
+<!ENTITY url-sponsors "http://www.internatif.org/bortzmeyer/debian/sponsor/">
+
+<!ENTITY url-rules-files "http://arch.debian.org/arch/private/srivasta/">
+
+<!ENTITY url-debconf-l10n-help "http://&www-debian-org;/intl/l10n/templates/hints">
+
+<!ENTITY url-dmup "http://&www-debian-org;/devel/dmup">
+<!ENTITY url-worldmap "http://&www-debian-org;/devel/developers.loc">
+
+<!ENTITY url-i18n-doc-check "http://cvs.debian.org/boot-floppies/documentation/doc-check?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
+
+<!ENTITY url-eg-desc-upstream-info "http://&packages-host;/unstable/web/wml">
+
+<!ENTITY url-alioth "http://alioth.debian.org/">
+
+<!-- 
+     URLs, non-debian
+  -->
+<!ENTITY url-gnu-manifesto "http://www.gnu.org/gnu/manifesto.html">
+<!ENTITY url-gpl "http://www.gnu.org/copyleft/gpl.html">
+<!ENTITY url-pgp-faq "http://www.cam.ac.uk.pgp.net/pgpnet/pgp-faq/">
+<!ENTITY url-rfc2440 "http://www.rfc-editor.org/rfc/rfc2440.txt">
+<!ENTITY url-u.s.-export "http://www.bxa.doc.gov/Encryption/PubAvailEncSourceCodeNofify.html">
+<!ENTITY url-notification-of-export "http://www.bxa.doc.gov/Encryption/">
+<!ENTITY url-openprojects "http://www.freenode.net/">
+<!ENTITY url-oftc "http://www.oftc.net/oftc/">
+
+<!-- Debian email addresses -->
+<!ENTITY email-listmaster "<email>listmaster@&lists-host;</email>">
+<!ENTITY email-debian-announce "<email>debian-announce@&lists-host;</email>">
+<!ENTITY email-devel-ref "<email>developers-reference@&packages-host;</email>">
+<!ENTITY email-debian-changes "<email>debian-changes@lists.debian.org</email>">
+<!ENTITY email-debian-devel "<email>debian-devel@&lists-host;</email>">
+<!ENTITY email-debian-devel-announce "<email>debian-devel-announce@&lists-host;</email>">
+<!ENTITY email-debian-devel-changes "<email>debian-devel-changes@lists.debian.org</email>">
+<!ENTITY email-debian-devel-req "<email>debian-devel-REQUEST@&lists-host;</email>">
+<!ENTITY email-debian-i18n "<email>debian-i18n@&lists-host;</email>">
+<!ENTITY email-debian-mentors "<email>debian-mentors@&lists-host;</email>">
+<!ENTITY email-debian-private "<email>debian-private@&lists-host;</email>">
+<!ENTITY email-debian-project "<email>debian-project@&lists-host;</email>">
+<!ENTITY email-debian-policy "<email>debian-policy@&lists-host;</email>">
+<!ENTITY email-debian-user "<email>debian-user@&lists-host;</email>">
+<!ENTITY orphan-address "&lt;packages@qa.debian.org&gt;">
+<!ENTITY email-debian-qa "<email>debian-qa@&lists-host;</email>">
+<!ENTITY email-debian-release "<email>debian-release@&lists-host;</email>">
+<!ENTITY email-debian-email "<email>debian-email@&lists-host;</email>">
+<!ENTITY email-debian-vote "<email>debian-vote@&lists-host;</email>">
+<!ENTITY email-debian-security-announce "<email>debian-security-announce@&lists-host;</email>">
+<!ENTITY email-debian-l10n-english "<email>debian-l10n-english@&lists-host;</email>">
+<!ENTITY email-mia "<email>mia@qa.debian.org</email>">
+
+<!ENTITY email-new-maintainer "<email>new-maintainer@debian.org</email>">
+<!ENTITY email-debian-keyring "<email>keyring-maint@debian.org</email>">
+<!ENTITY email-debian-admin "<email>debian-admin@debian.org</email>">
+<!ENTITY email-ftpmaster "<email>ftpmaster@debian.org</email>">
+<!ENTITY email-override "<email>override-change@debian.org</email>">
+<!ENTITY email-wnpp "<email>wnpp@debian.org</email>">
+<!ENTITY email-bts-control "<email>control@&bugs-host;</email>">
+<!ENTITY email-security-team "<email>team@security.debian.org</email>">
+
+<!-- misc Debian info -->
+<!ENTITY file-mail-lists "<filename>/usr/share/doc/debian/mailing-lists.txt</filename>">
+<!ENTITY file-bts-docs "<filename>/usr/share/doc/debian/bug-*</filename>">
+<!ENTITY file-python-policy "<filename>/usr/share/doc/python/python-policy.txt.gz</filename>">
+<!ENTITY file-ocaml-policy "<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename>">
+<!ENTITY file-lisp-controller "<filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>">
+<!ENTITY file-debian-private-archive "~debian/archive/debian-private/">
+<!ENTITY file-bpp-autotools "<filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename>">
+
+<!ENTITY cron-bug-report '0 17 * * fri   echo "index maint <replaceable>address</replaceable>" | mail request@&bugs-host;'>
+
+<!--
+     misc, non-debian
+  -->
+<!ENTITY pgp-keyserv "<literal>subkeys.pgp.net</literal>">
+
+<!ENTITY sample-dist-dirtree "<screen>dists/stable/main/
+dists/stable/main/binary-i386/
+dists/stable/main/binary-m68k/
+dists/stable/main/binary-alpha/
+     ...
+dists/stable/main/source/
+     ...
+dists/stable/main/disks-i386/
+dists/stable/main/disks-m68k/
+dists/stable/main/disks-alpha/
+     ...
+
+dists/stable/contrib/
+dists/stable/contrib/binary-i386/
+dists/stable/contrib/binary-m68k/
+dists/stable/contrib/binary-alpha/
+     ...
+dists/stable/contrib/source/
+
+dists/stable/non-free/
+dists/stable/non-free/binary-i386/
+dists/stable/non-free/binary-m68k/
+dists/stable/non-free/binary-alpha/
+     ...
+dists/stable/non-free/source/
+
+dists/testing/
+dists/testing/main/
+     ...
+dists/testing/contrib/
+     ...
+dists/testing/non-free/
+     ...
+
+dists/unstable
+dists/unstable/main/
+     ...
+dists/unstable/contrib/
+     ...
+dists/unstable/non-free/
+     ...
+
+pool/
+pool/main/a/
+pool/main/a/apt/
+     ...
+pool/main/b/
+pool/main/b/bash/
+     ...
+pool/main/liba/
+pool/main/liba/libalias-perl/
+     ...
+pool/main/m/
+pool/main/m/mailx/
+     ...
+pool/non-free/n/
+pool/non-free/n/netscape/
+     ...</screen>">
+
+<!ENTITY example-uu "<programlisting>uuencode-file:
+    perl -ne 'print(pack &quot;u&quot;, $$_);' $(file) &gt; $(file).uuencoded
+
+uudecode-file:
+    perl -ne 'print(unpack &quot;u&quot;, $$_);' $(file).uuencoded &gt; $(file)</programlisting>">
+
+<!ENTITY example-pathfind '<programlisting>pathfind() {
+    OLDIFS="$IFS"
+    IFS=:
+    for p in $PATH; do
+        if [ -x "$p/$*" ]; then
+            IFS="$OLDIFS"
+            return 0
+        fi
+    done
+    IFS="$OLDIFS"
+    return 1
+}</programlisting>'>
index 899b567..5a444e7 100644 (file)
@@ -1,13 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="developer-duties">
 <title>Debian Developer's Duties</title>
 <section id="user-maint">
 <title>Maintaining your Debian information</title>
 <para>
 There's a LDAP database containing information about Debian developers at
-<ulink url="https://db.debian.org/"></ulink>.  You should enter your
+<ulink url="&url-debian-db;"></ulink>.  You should enter your
 information there and update it as it changes.  Most notably, make sure that
 the address where your debian.org email gets forwarded to is always up to date,
 as well as the address where you get your debian-private subscription if you
@@ -37,7 +39,7 @@ lost.
 <para>
 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
-<literal>keyring.debian.org</literal>.
+<literal>&keyserver-host;</literal>.
 </para>
 <para>
 If you need to add a completely new key or remove an old key, you need to get
@@ -45,7 +47,7 @@ the new key signed by another developer.  If the old key is compromised or
 invalid, you also have to add the revocation certificate.  If there is no real
 reason for a new key, the Keyring Maintainers might reject the new key.
 Details can be found at <ulink
-url="http://keyring.debian.org/replacing_keys.html"></ulink>.
+url="http://&keyserver-host;/replacing_keys.html"></ulink>.
 </para>
 <para>
 The same key extraction routines discussed in <xref linkend="registering"/>
@@ -63,26 +65,26 @@ package.
 <para>
 Even though Debian isn't really a democracy, we use a democratic process to
 elect our leaders and to approve general resolutions.  These procedures are
-defined by the <ulink url="http://www.debian.org/devel/constitution">Debian
+defined by the <ulink url="&url-constitution;">Debian
 Constitution</ulink>.
 </para>
 <para>
 Other than the yearly leader election, votes are not routinely held, and they
 are not undertaken lightly.  Each proposal is first discussed on the
-<email>debian-vote@lists.debian.org</email> mailing list and it requires
+<email>debian-vote@&lists-host;</email> mailing list and it requires
 several endorsements before the project secretary starts the voting procedure.
 </para>
 <para>
 You don't have to track the pre-vote discussions, as the secretary will issue
 several calls for votes on
-<email>debian-devel-announce@lists.debian.org</email> (and all developers are
+<email>debian-devel-announce@&lists-host;</email> (and all developers are
 expected to be subscribed to that list).  Democracy doesn't work well if people
 don't take part in the vote, which is why we encourage all developers to vote.
 Voting is conducted via GPG-signed/encrypted email messages.
 </para>
 <para>
 The list of all proposals (past and current) is available on the <ulink
-url="http://www.debian.org/vote/">Debian Voting Information</ulink> page, along
+url="&url-vote;">Debian Voting Information</ulink> page, along
 with information on how to make, second and vote on proposals.
 </para>
 </section>
@@ -105,7 +107,7 @@ unavailable.
 </para>
 <para>
 In order to inform the other developers, there are two things that you should
-do.  First send a mail to <email>debian-private@lists.debian.org</email> with
+do.  First send a mail to <email>debian-private@&lists-host;</email> with
 [VAC] prepended to the subject of your message<footnote><para> This is so that
 the message can be easily filtered by people who don't want to read vacation
 notices.  </para> </footnote> and state the period of time when you will be on
@@ -120,7 +122,7 @@ the on vacation flag when you come back!
 </para>
 <para>
 Ideally, you should sign up at the <ulink
-url="http://nm.debian.org/gpg.php">GPG coordination site</ulink> when booking a
+url="&url-newmaint-db;gpg.php">GPG coordination site</ulink> when booking a
 holiday and check if anyone there is looking for signing.  This is especially
 important when people go to exotic places where we don't have any developers
 yet but where there are people who are interested in applying.
@@ -166,12 +168,12 @@ the removal of a package at freeze time.  That's why these bugs need to be
 corrected as quickly as possible.
 </para>
 <para>
-Developers who are part of the <ulink url="http://qa.debian.org/">Quality
+Developers who are part of the <ulink url="&url-debian-qa;">Quality
 Assurance</ulink> group are following all such bugs, and trying to help
 whenever possible.  If, for any reason, you aren't able fix an RC bug in a
 package of yours within 2 weeks, you should either ask for help by sending a
 mail to the Quality Assurance (QA) group
-<email>debian-qa@lists.debian.org</email>, or explain your difficulties and
+<email>debian-qa@&lists-host;</email>, or explain your difficulties and
 present a plan to fix them by sending a mail to the bug report.  Otherwise,
 people from the QA group may want to do a Non-Maintainer Upload (see <xref
 linkend="nmu"/> ) after trying to contact you (they might not wait as long as
@@ -195,7 +197,7 @@ Orphan all your packages, as described in <xref linkend="orphaning"/> .
 <listitem>
 <para>
 Send an gpg-signed email about why you are leaving the project to
-<email>debian-private@lists.debian.org</email>.
+<email>debian-private@&lists-host;</email>.
 </para>
 </listitem>
 <listitem>
index bba1fa9..5312fde 100644 (file)
--- a/index.dbk
+++ b/index.dbk
@@ -1,13 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <book lang="en">
 
 <title>Debian Developer's Reference</title>
 <bookinfo>
 <author>
 <othername>Developer's Reference Team</othername>
-<email>developers-reference@packages.debian.org</email> 
+<email>developers-reference@&packages-host;</email> 
 </author>
 <author>
 <firstname>Andreas</firstname> <surname>Barth</surname>
@@ -66,11 +68,10 @@ more details.
 </para>
 <para>
 A copy of the GNU General Public License is available as
-<filename>/usr/share/common-licenses/GPL</filename> in the Debian GNU/Linux
+&file-GPL; in the &debian-formal;
 distribution or on the World Wide Web at <ulink
 url="http://www.gnu.org/copyleft/gpl.html">the GNU web site</ulink>.  You can
-also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin
-Street, Fifth Floor, Boston, MA 02110-1301, USA.
+also obtain it by writing to the &fsf-addr;.
 </para>
 <para>
 If you want to print this reference, you should use the <ulink
index dec77c4..dd55586 100644 (file)
--- a/l10n.dbk
+++ b/l10n.dbk
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="l10n">
 <title>Internationalizing, translating, being internationalized and being translated</title>
 <para>
@@ -13,7 +15,7 @@ programs, you should read most of this chapter.
 </para>
 <para>
 According to <ulink
-url="http://www.debian.org/doc/manuals/intro-i18n/">Introduction to
+url="http://&www-debian-org;/doc/manuals/intro-i18n/">Introduction to
 i18n</ulink> from Tomohiro KUBOTA, I18N (internationalization) means
 modification of a software or related technologies so that a software can
 potentially handle multiple languages, customs, and so on in the world.  while
@@ -48,7 +50,7 @@ Project</ulink>, the <ulink
 url="http://developer.gnome.org/projects/gtp/">Gnome translation
 Project</ulink> or the <ulink url="http://i18n.kde.org/">KDE one</ulink>.  The
 only centralized resource within Debian is the <ulink
-url="http://www.debian.org/intl/l10n/">Central Debian translation
+url="http://&www-debian-org;/intl/l10n/">Central Debian translation
 statistics</ulink>, where you can find some statistics about the translation
 files found in the actual packages, but no real infrastructure to ease the
 translation process.
@@ -65,7 +67,7 @@ For debconf templates, maintainers should use the po-debconf package to ease
 the work of translators, who could use the DDTP to do their work (but the
 French and Brazilian teams don't).  Some statistics can be found both on the
 DDTP site (about what is actually translated), and on the <ulink
-url="http://www.debian.org/intl/l10n/">Central Debian translation
+url="http://&www-debian-org;/intl/l10n/">Central Debian translation
 statistics</ulink> site (about what is integrated in the packages).
 </para>
 <para>
@@ -87,7 +89,7 @@ same way as its program messages.
 </para>
 <para>
 There is an effort to handle Debian-specific man pages within a <ulink
-url="http://cvs.debian.org/manpages/?cvsroot=debian-doc">specific CVS
+url="&url-cvsweb;manpages/?cvsroot=debian-doc">specific CVS
 repository</ulink>.
 </para>
 </section>
index c52583a..615d85e 100644 (file)
@@ -1,27 +1,29 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="new-maintainer">
 <title>Applying to Become a Maintainer</title>
 <section id="getting-started">
 <title>Getting started</title>
 <para>
 So, you've read all the documentation, you've gone through the <ulink
-url="http://www.debian.org/doc/maint-guide/">Debian New Maintainers'
+url="http://&www-debian-org;/doc/maint-guide/">Debian New Maintainers'
 Guide</ulink>, understand what everything in the <systemitem
 role="package">hello</systemitem> example package is for, and you're about to
 Debianize your favorite piece of software.  How do you actually become a Debian
 developer so that your work can be incorporated into the Project?
 </para>
 <para>
-Firstly, subscribe to <email>debian-devel@lists.debian.org</email> if you
+Firstly, subscribe to <email>debian-devel@&lists-host;</email> if you
 haven't already.  Send the word <literal>subscribe</literal> in the
 <emphasis>Subject</emphasis> of an email to
-<email>debian-devel-REQUEST@lists.debian.org</email>.  In case of problems,
-contact the list administrator at <email>listmaster@lists.debian.org</email>.
+<email>debian-devel-REQUEST@&lists-host;</email>.  In case of problems,
+contact the list administrator at <email>listmaster@&lists-host;</email>.
 More information on available mailing lists can be found in <xref
 linkend="mailing-lists"/> .
-<email>debian-devel-announce@lists.debian.org</email> is another list which is
+<email>debian-devel-announce@&lists-host;</email> is another list which is
 mandatory for anyone who wishes to follow Debian's development.
 </para>
 <para>
@@ -31,19 +33,19 @@ something to avoid duplicated effort.
 </para>
 <para>
 Another good list to subscribe to is
-<email>debian-mentors@lists.debian.org</email>.  See <xref linkend="mentors"/>
+<email>debian-mentors@&lists-host;</email>.  See <xref linkend="mentors"/>
 for details.  The IRC channel <literal>#debian</literal> can also be helpful;
 see <xref linkend="irc-channels"/> .
 </para>
 <para>
-When you know how you want to contribute to Debian GNU/Linux, you should get in
+When you know how you want to contribute to &debian-formal;, you 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 they are happy with the packaging work you have
 done.  You can find a sponsor by mailing the
-<email>debian-mentors@lists.debian.org</email> mailing list, describing your
+<email>debian-mentors@&lists-host;</email> mailing list, describing your
 package and yourself and asking for a sponsor (see <xref linkend="sponsoring"/>
 and <ulink
 url="http://people.debian.org/~mpalmer/debian-mentors_FAQ.html"></ulink> for
@@ -56,14 +58,14 @@ maintainers already working on these tasks and submit patches and improvements.
 <para>
 One pitfall could be a too-generic local part in your mailadress: Terms like
 mail, admin, root, master should be avoided, please see <ulink
-url="http://www.debian.org/MailingLists/"></ulink> for details.
+url="&url-debian-lists;"></ulink> for details.
 </para>
 </section>
 
 <section id="mentors">
 <title>Debian mentors and sponsors</title>
 <para>
-The mailing list <email>debian-mentors@lists.debian.org</email> has been set up
+The mailing list <email>debian-mentors@&lists-host;</email> has been set up
 for novice maintainers who seek help with initial packaging and other
 developer-related issues.  Every new developer is invited to subscribe to that
 list (see <xref linkend="mailing-lists"/> for details).
@@ -94,22 +96,22 @@ If you wish to be a mentor and/or sponsor, more information is available in
 <section id="registering">
 <title>Registering as a Debian developer</title>
 <para>
-Before you decide to register with Debian GNU/Linux, you will need to read all
+Before you decide to register with &debian-formal;, you will need to read all
 the information available at the <ulink
-url="http://www.debian.org/devel/join/newmaint">New Maintainer's
+url="&url-newmaint;">New Maintainer's
 Corner</ulink>.  It describes in detail the preparations you have to do before
 you can register to become a Debian developer.  For example, before you apply,
-you have to read the <ulink url="http://www.debian.org/social_contract">Debian
+you have to read the <ulink url="&url-social-contract;">Debian
 Social Contract</ulink>.  Registering as a developer means that you agree with
 and pledge to uphold the Debian Social Contract; it is very important that
-maintainers are in accord with the essential ideas behind Debian GNU/Linux.
+maintainers are in accord with the essential ideas behind &debian-formal;.
 Reading the <ulink url="http://www.gnu.org/gnu/manifesto.html">GNU
 Manifesto</ulink> would also be a good idea.
 </para>
 <para>
 The process of registering as a developer is a process of verifying your
 identity and intentions, and checking your technical skills.  As the number of
-people working on Debian GNU/Linux has grown to over 900 and our systems are
+people working on &debian-formal; has grown to over &number-of-maintainers; and our systems are
 used in several very important places, we have to be careful about being
 compromised.  Therefore, we need to verify new maintainers before we can give
 them accounts on our servers and let them upload packages.
@@ -128,12 +130,12 @@ Registration requires that you are familiar with Debian's philosophy and
 technical documentation.  Furthermore, you need a GnuPG key which has been
 signed by an existing Debian maintainer.  If your GnuPG key is not signed yet,
 you should try to meet a Debian Developer in person to get your key signed.
-There's a <ulink url="http://nm.debian.org/gpg.php">GnuPG Key Signing
+There's a <ulink url="&url-newmaint-db;gpg.php">GnuPG Key Signing
 Coordination page</ulink> which should help you find a Debian Developer close
 to you.  (If there is no Debian Developer close to you, alternative ways to
 pass the ID check may be permitted as an absolute exception on a
 case-by-case-basis.  See the <ulink
-url="http://www.debian.org/devel/join/nm-step2">identification page</ulink> for
+url="&url-devel-docs;join/nm-step2">identification page</ulink> for
 more information.)
 </para>
 <para>
@@ -178,8 +180,8 @@ have to manually add those signatures.  </para> </footnote>
 </para>
 <para>
 If your public key isn't on a public key server such as
-<literal>subkeys.pgp.net</literal>, please read the documentation available at
-<ulink url="http://www.debian.org/devel/join/nm-step2">NM Step 2:
+&pgp-keyserv;, please read the documentation available at
+<ulink url="&url-devel-docs;join/nm-step2">NM Step 2:
 Identification</ulink>.  That document contains instructions on how to put your
 key on the public key servers.  The New Maintainer Group will put your public
 key on the servers if it isn't already there.
@@ -202,16 +204,16 @@ has to express their belief that you can contribute to Debian successfully.
 <para>
 When you have found an advocate, have your GnuPG key signed and have already
 contributed to Debian for a while, you're ready to apply.  You can simply
-register on our <ulink url="http://nm.debian.org/newnm.php">application
+register on our <ulink url="&url-newmaint-db;newnm.php">application
 page</ulink>.  After you have signed up, your advocate has to confirm your
 application.  When your advocate has completed this step you will be assigned
 an Application Manager who will go with you through the necessary steps of the
 New Maintainer process.  You can always check your status on the <ulink
-url="http://nm.debian.org/">applications status board</ulink>.
+url="&url-newmaint-db;">applications status board</ulink>.
 </para>
 <para>
 For more details, please consult <ulink
-url="http://www.debian.org/devel/join/newmaint">New Maintainer's Corner</ulink>
+url="&url-newmaint;">New Maintainer's Corner</ulink>
 at the Debian web site.  Make sure that you are familiar with the necessary
 steps of the New Maintainer process before actually applying.  If you are well
 prepared, you can save a lot of time later on.
index 5004933..fdf7a0f 100644 (file)
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="pkgs">
 <title>Managing Packages</title>
 <para>
@@ -11,10 +13,10 @@ and porting packages.
 <title>New packages</title>
 <para>
 If you want to create a new package for the Debian distribution, you should
-first check the <ulink url="http://www.debian.org/devel/wnpp/">Work-Needing and
+first check the <ulink url="&url-wnpp;">Work-Needing and
 Prospective Packages (WNPP)</ulink> list.  Checking the WNPP list ensures that
 no one is already working on packaging that software, and that effort is not
-duplicated.  Read the <ulink url="http://www.debian.org/devel/wnpp/">WNPP web
+duplicated.  Read the <ulink url="&url-wnpp;">WNPP web
 pages</ulink> for more information.
 </para>
 <para>
@@ -30,7 +32,7 @@ You should set the subject of the bug to ``ITP: <replaceable>foo</replaceable>
 -- <replaceable>short description</replaceable>'', substituting the name of the
 new package for <replaceable>foo</replaceable>.  The severity of the bug report
 must be set to <emphasis>wishlist</emphasis>.  If you feel it's necessary, send
-a copy to <email>debian-devel@lists.debian.org</email> by putting the address
+a copy to <email>debian-devel@&lists-host;</email> by putting the address
 in the <literal>X-Debbugs-CC:</literal> header of the message (no, don't use
 <literal>CC:</literal>, because that way the message's subject won't indicate
 the bug number).
@@ -87,7 +89,7 @@ of what is going on, and what is new, in the project.
 </listitem>
 </itemizedlist>
 <para>
-Please see <ulink url="http://ftp-master.debian.org/REJECT-FAQ.html"></ulink>
+Please see <ulink url="http://&ftp-master-host;/REJECT-FAQ.html"></ulink>
 for common rejection reasons for a new package.
 </para>
 </section>
@@ -336,7 +338,7 @@ packages uninstallable, is strongly discouraged.
 </para>
 <para>
 The Release Team (which can be reached at
-<email>debian-release@lists.debian.org</email>) will regularly evaluate the
+<email>debian-release@&lists-host;</email>) will regularly evaluate the
 uploads To <emphasis>stable-proposed-updates</emphasis> and decide if your
 package can be included in <emphasis>stable</emphasis>.  Please be clear (and
 verbose, if necessary) in your changelog entries for uploads to
@@ -367,9 +369,9 @@ section</link> for details.
 <title>Uploading to <literal>ftp-master</literal></title>
 <para>
 To upload a package, you should upload the files (including the signed changes
-and dsc-file) with anonymous ftp to <literal>ftp-master.debian.org</literal> in
+and dsc-file) with anonymous ftp to <literal>&ftp-master-host;</literal> in
 the directory <ulink
-url="ftp://ftp-master.debian.org/pub/UploadQueue/">/pub/UploadQueue/</ulink>.
+url="ftp://&ftp-master-host;&upload-queue;">&upload-queue;</ulink>.
 To get the files processed there, they need to be signed with a key in the
 debian keyring.
 </para>
@@ -511,7 +513,7 @@ file</emphasis>.
 To alter the actual section that a package is put in, you need to first make
 sure that the <filename>debian/control</filename> file in your package is
 accurate.  Next, send an email <email>override-change@debian.org</email> or
-submit a bug against <systemitem role="package">ftp.debian.org</systemitem>
+submit a bug against <systemitem role="package">&ftp-debian-org;</systemitem>
 requesting that the section or priority for your package be changed from the
 old section or priority to the new one.  Be sure to explain your reasoning.
 </para>
@@ -519,14 +521,14 @@ old section or priority to the new one.  Be sure to explain your reasoning.
 For more information about <emphasis>override files</emphasis>, see
 <citerefentry> <refentrytitle>dpkg-scanpackages</refentrytitle>
 <manvolnum>1</manvolnum> </citerefentry> and <ulink
-url="http://www.debian.org/Bugs/Developer#maintincorrect"></ulink>.
+url="&url-bts-devel;#maintincorrect"></ulink>.
 </para>
 <para>
 Note that the <literal>Section</literal> field describes both the section as
 well as the subsection, which are described in <xref
 linkend="archive-sections"/> .  If the section is main, it should be omitted.
 The list of allowable subsections can be found in <ulink
-url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections"></ulink>.
+url="&url-debian-policy;ch-archive.html#s-subsections"></ulink>.
 </para>
 </section>
 
@@ -534,13 +536,13 @@ url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections"></ul
 <title>Handling bugs</title>
 <para>
 Every developer has to be able to work with the Debian <ulink
-url="http://www.debian.org/Bugs/">bug tracking system</ulink>.  This includes
+url="&url-bts;">bug tracking system</ulink>.  This includes
 knowing how to file bug reports properly (see <xref linkend="submit-bug"/> ),
 how to update them and reorder them, and how to process and close them.
 </para>
 <para>
 The bug tracking system's features are described in the <ulink
-url="http://www.debian.org/Bugs/Developer">BTS documentation for
+url="&url-bts-devel;">BTS documentation for
 developers</ulink>.  This includes closing bugs, sending followup messages,
 assigning severities and tags, marking bugs as forwarded, and other issues.
 </para>
@@ -549,22 +551,22 @@ Operations such as reassigning bugs to other packages, merging separate bug
 reports about the same issue, or reopening bugs when they are prematurely
 closed, are handled using the so-called control mail server.  All of the
 commands available on this server are described in the <ulink
-url="http://www.debian.org/Bugs/server-control">BTS control server
+url="&url-bts-control;">BTS control server
 documentation</ulink>.
 </para>
 <section id="bug-monitoring">
 <title>Monitoring bugs</title>
 <para>
 If you want to be a good maintainer, you should periodically check the <ulink
-url="http://www.debian.org/Bugs/">Debian bug tracking system (BTS)</ulink> for
+url="&url-bts;">Debian bug tracking system (BTS)</ulink> for
 your packages.  The BTS contains all the open bugs against your packages.  You
 can check them by browsing this page:
-<literal>http://bugs.debian.org/<replaceable>yourlogin</replaceable>@debian.org</literal>.
+<literal>http://&bugs-host;/<replaceable>yourlogin</replaceable>@debian.org</literal>.
 </para>
 <para>
 Maintainers interact with the BTS via email addresses at
-<literal>bugs.debian.org</literal>.  Documentation on available commands can be
-found at <ulink url="http://www.debian.org/Bugs/"></ulink>, or, if you have
+<literal>&bugs-host;</literal>.  Documentation on available commands can be
+found at <ulink url="&url-bts;"></ulink>, or, if you have
 installed the <systemitem role="package">doc-debian</systemitem> package, you
 can look at the local files <filename>/usr/share/doc/debian/bug-*</filename>.
 </para>
@@ -575,7 +577,7 @@ open bugs against your packages:
 </para>
 <screen>
 # ask for weekly reports of bugs in my packages
-0 17 * * fri   echo index maint <replaceable>address</replaceable> | mail request@bugs.debian.org
+&cron-bug-report;
 </screen>
 <para>
 Replace <replaceable>address</replaceable> with your official Debian maintainer
@@ -588,11 +590,11 @@ address.
 <para>
 When responding to bugs, make sure that any discussion you have about bugs is
 sent both to the original submitter of the bug, and to the bug itself (e.g.,
-<email>123@bugs.debian.org</email>).  If you're writing a new mail and you
+<email>123@&bugs-host;</email>).  If you're writing a new mail and you
 don't remember the submitter email address, you can use the
-<email>123-submitter@bugs.debian.org</email> email to contact the submitter
+<email>123-submitter@&bugs-host;</email> email to contact the submitter
 <emphasis>and</emphasis> to record your mail within the bug log (that means you
-don't need to send a copy of the mail to <email>123@bugs.debian.org</email>).
+don't need to send a copy of the mail to <email>123@&bugs-host;</email>).
 </para>
 <para>
 If you get a bug which mentions FTBFS, this means Fails to build from source.
@@ -601,14 +603,14 @@ Porters frequently use this acronym.
 <para>
 Once you've dealt with a bug report (e.g.  fixed it), mark it as
 <emphasis>done</emphasis> (close it) by sending an explanation message to
-<email>123-done@bugs.debian.org</email>.  If you're fixing a bug by changing
+<email>123-done@&bugs-host;</email>.  If you're fixing a bug by changing
 and uploading the package, you can automate bug closing as described in <xref
 linkend="upload-bugfix"/> .
 </para>
 <para>
 You should <emphasis>never</emphasis> close bugs via the bug server
 <literal>close</literal> command sent to
-<email>control@bugs.debian.org</email>.  If you do so, the original submitter
+<email>control@&bugs-host;</email>.  If you do so, the original submitter
 will not receive any information about why the bug was closed.
 </para>
 </section>
@@ -619,10 +621,10 @@ will not receive any information about why the bug was closed.
 As a package maintainer, you will often find bugs in other packages or have
 bugs reported against your packages which are actually bugs in other packages.
 The bug tracking system's features are described in the <ulink
-url="http://www.debian.org/Bugs/Developer">BTS documentation for Debian
+url="&url-bts-devel;">BTS documentation for Debian
 developers</ulink>.  Operations such as reassigning, merging, and tagging bug
 reports are described in the <ulink
-url="http://www.debian.org/Bugs/server-control">BTS control server
+url="&url-bts-control;">BTS control server
 documentation</ulink>.  This section contains some guidelines for managing your
 own bugs, based on the collective Debian developer experience.
 </para>
@@ -655,7 +657,7 @@ unacceptable, you (or the submitter) may want to require a decision of the
 technical committee by reassigning the bug to <systemitem
 role="package">tech-ctte</systemitem> (you may use the clone command of the BTS
 if you wish to keep it reported against your package).  Before doing so, please
-read the <ulink url="http://www.debian.org/devel/tech-ctte">recommended
+read the <ulink url="&url-devel-docs;tech-ctte">recommended
 procedure</ulink>.
 </para>
 </listitem>
@@ -664,7 +666,7 @@ procedure</ulink>.
 If the bug is real but it's caused by another package, just reassign the bug to
 the right package.  If you don't know which package it should be reassigned to,
 you should ask for help on <link linkend="irc-channels">IRC</link> or
-on <email>debian-devel@lists.debian.org</email>.  Please make sure that the
+on <email>debian-devel@&lists-host;</email>.  Please make sure that the
 maintainer(s) of the package the bug is reassigned to know why you reassigned
 it.
 </para>
@@ -701,8 +703,8 @@ someone, the bug may be closed.
 <para>
 If the bug is related to the packaging, you just fix it.  If you are not able
 to fix it yourself, then tag the bug as <literal>help</literal>.  You can also
-ask for help on <email>debian-devel@lists.debian.org</email> or
-<email>debian-qa@lists.debian.org</email>.  If it's an upstream problem, you
+ask for help on <email>debian-devel@&lists-host;</email> or
+<email>debian-qa@&lists-host;</email>.  If it's an upstream problem, you
 have to forward it to the upstream author.  Forwarding a bug is not enough, you
 have to check at each release if the bug has been fixed or not.  If it has, you
 just close it, otherwise you have to remind the author about it.  If you have
@@ -748,7 +750,7 @@ file, following a certain syntax, and the archive maintenance software will
 close the bugs for you.  For example:
 </para>
 <screen>
--cannon (3.1415) unstable; urgency=low
+acme-cannon (3.1415) unstable; urgency=low
 
   * Frobbed with options (closes: Bug#98339)
   * Added safety to prevent operator dismemberment, closes: bug#98765,
@@ -782,9 +784,9 @@ If you happen to mistype a bug number or forget a bug in the changelog entries,
 don't hesitate to undo any damage the error caused.  To reopen wrongly closed
 bugs, send a <literal>reopen <replaceable>XXX</replaceable></literal> command
 to the bug tracking system's control address,
-<email>control@bugs.debian.org</email>.  To close any remaining bugs that were
+<email>control@&bugs-host;</email>.  To close any remaining bugs that were
 fixed by your upload, email the <filename>.changes</filename> file to
-<email>XXX-done@bugs.debian.org</email>, where <replaceable>XXX</replaceable>
+<email>XXX-done@&bugs-host;</email>, where <replaceable>XXX</replaceable>
 is the bug number, and put Version: YYY and an empty line as the first two
 lines of the body of the email, where <replaceable>YYY</replaceable> is the
 first version where the bug has been fixed.
@@ -793,7 +795,7 @@ first version where the bug has been fixed.
 Bear in mind that it is not obligatory to close bugs using the changelog as
 described above.  If you simply want to close bugs that don't have anything to
 do with an upload you made, do it by emailing an explanation to
-<email>XXX-done@bugs.debian.org</email>.  Do <emphasis
+<email>XXX-done@&bugs-host;</email>.  Do <emphasis
 role="strong">not</emphasis> close bugs in the changelog entry of a version if
 the changes in that version of the package don't have any bearing on the bug.
 </para>
@@ -931,8 +933,8 @@ has become public.
 Security advisories are only issued for the current, released stable
 distribution, and <emphasis>not</emphasis> for testing or unstable.  When
 released, advisories are sent to the
-<email>debian-security-announce@lists.debian.org</email> mailing list and
-posted on <ulink url="http://www.debian.org/security/">the security web
+<email>debian-security-announce@&lists-host;</email> mailing list and
+posted on <ulink url="http://&www-debian-org;/security/">the security web
 page</ulink>.  Security advisories are written and posted by the security team.
 However they certainly do not mind if a maintainer can supply some of the
 information for them, or write part of the text.  Information that should be in
@@ -1191,14 +1193,14 @@ chapter gives guidelines on what to do in these cases.
 Sometimes a package will change its section.  For instance, a package from the
 `non-free' section might be GPL'd in a later version, in which case the package
 should be moved to `main' or `contrib'.<footnote><para> See the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for
+url="&url-debian-policy;">Debian Policy Manual</ulink> for
 guidelines on what section a package belongs in.  </para> </footnote>
 </para>
 <para>
 If you need to change the section for one of your packages, change the package
 control information to place the package in the desired section, and re-upload
 the package (see the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for
+url="&url-debian-policy;">Debian Policy Manual</ulink> for
 details).  You must ensure that you include the
 <filename>.orig.tar.gz</filename> in your upload (even if you are not uploading
 a new upstream version), or it will not appear in the new section together with
@@ -1220,7 +1222,7 @@ described in <xref linkend="override-file"/> .
 <para>
 If for some reason you want to completely remove a package (say, if it is an
 old compatibility library which is no longer required), you need to file a bug
-against <literal>ftp.debian.org</literal> asking that the package be removed;
+against <literal>&ftp-debian-org;</literal> asking that the package be removed;
 as all bugs, this bug should normally have normal severity.  Make sure you
 indicate which distribution the package should be removed from.  Normally, you
 can only have packages removed from <emphasis>unstable</emphasis> and
@@ -1253,18 +1255,18 @@ maintainer.
 <para>
 Further information relating to these and other package removal related topics
 may be found at <ulink url="http://wiki.debian.org/ftpmaster_Removals"></ulink>
-and <ulink url="http://qa.debian.org/howto-remove.html"></ulink>.
+and <ulink url="&url-debian-qa;howto-remove.html"></ulink>.
 </para>
 <para>
 If in doubt concerning whether a package is disposable, email
-<email>debian-devel@lists.debian.org</email> asking for opinions.  Also of
+<email>debian-devel@&lists-host;</email> asking for opinions.  Also of
 interest is the <command>apt-cache</command> program from the <systemitem
 role="package">apt</systemitem> package.  When invoked as <literal>apt-cache
 showpkg <replaceable>package</replaceable></literal>, the program will show
 details for <replaceable>package</replaceable>, including reverse depends.
 Other useful programs include <literal>apt-cache rdepends</literal>,
 <command>apt-rdepends</command> and <command>grep-dctrl</command>.  Removal of
-orphaned packages is discussed on <email>debian-qa@lists.debian.org</email>.
+orphaned packages is discussed on <email>debian-qa@&lists-host;</email>.
 </para>
 <para>
 Once the package has been removed, the package's bugs should be handled.  They
@@ -1296,9 +1298,9 @@ occur too often anyway.
 When you make a mistake naming your package, you should follow a two-step
 process to rename it.  First, set your <filename>debian/control</filename> file
 to replace and conflict with the obsolete name of the package (see the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for
+url="&url-debian-policy;">Debian Policy Manual</ulink> for
 details).  Once you've uploaded the package and the package has moved into the
-archive, file a bug against <literal>ftp.debian.org</literal> asking to remove
+archive, file a bug against <literal>&ftp-debian-org;</literal> asking to remove
 the package with the obsolete name.  Do not forget to properly reassign the
 package's bugs at the same time.
 </para>
@@ -1321,7 +1323,7 @@ mirror network.
 <para>
 If you can no longer maintain a package, you need to inform others, and see
 that the package is marked as orphaned.  You should set the package maintainer
-to <literal>Debian QA Group &lt;packages@qa.debian.org&gt;</literal> and submit
+to <literal>Debian QA Group &lt;&pts-host;&gt;</literal> and submit
 a bug report against the pseudo package <systemitem
 role="package">wnpp</systemitem>.  The bug report should be titled <literal>O:
 <replaceable>package</replaceable> -- <replaceable>short
@@ -1329,7 +1331,7 @@ description</replaceable></literal> indicating that the package is now
 orphaned.  The severity of the bug should be set to
 <emphasis>normal</emphasis>; if the package has a priority of standard or
 higher, it should be set to important.  If you feel it's necessary, send a copy
-to <email>debian-devel@lists.debian.org</email> by putting the address in the
+to <email>debian-devel@&lists-host;</email> by putting the address in the
 X-Debbugs-CC: header of the message (no, don't use CC:, because that way the
 message's subject won't indicate the bug number).
 </para>
@@ -1342,7 +1344,7 @@ description</replaceable></literal>.  <literal>RFA</literal> stands for
 <emphasis>Request For Adoption</emphasis>.
 </para>
 <para>
-More information is on the <ulink url="http://www.debian.org/devel/wnpp/">WNPP
+More information is on the <ulink url="&url-wnpp;">WNPP
 web pages</ulink>.
 </para>
 </section>
@@ -1351,7 +1353,7 @@ web pages</ulink>.
 <title>Adopting a package</title>
 <para>
 A list of packages in need of a new maintainer is available in the <ulink
-url="http://www.debian.org/devel/wnpp/">Work-Needing and Prospective Packages
+url="&url-wnpp;">Work-Needing and Prospective Packages
 list (WNPP)</ulink>.  If you wish to take over maintenance of any of the
 packages listed in the WNPP, please take a look at the aforementioned page for
 information and procedures.
@@ -1369,7 +1371,7 @@ package.  Complaints about maintainers should be brought up on the developers'
 mailing list.  If the discussion doesn't end with a positive conclusion, and
 the issue is of a technical nature, consider bringing it to the attention of
 the technical committee (see the <ulink
-url="http://www.debian.org/devel/tech-ctte">technical committee web
+url="&url-devel-docs;tech-ctte">technical committee web
 page</ulink> for more information).
 </para>
 <para>
@@ -1400,7 +1402,7 @@ different from the original architecture of the package maintainer's binary
 package.  It is a unique and essential activity.  In fact, porters do most of
 the actual compiling of Debian packages.  For instance, for a single
 <emphasis>i386</emphasis> binary package, there must be a recompile for each
-architecture, which amounts to 12 more builds.
+architecture, which amounts to &number-of-arches; more builds.
 </para>
 <section id="kind-to-porters">
 <title>Being kind to porters</title>
@@ -1445,7 +1447,7 @@ If you can't set up a proper chroot, <command>dpkg-depcheck</command> may be of
 assistance (see <xref linkend="dpkg-depcheck"/> ).
 </para>
 <para>
-See the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+See the <ulink url="&url-debian-policy;">Debian Policy
 Manual</ulink> for instructions on setting build dependencies.
 </para>
 </listitem>
@@ -1453,7 +1455,7 @@ Manual</ulink> for instructions on setting build dependencies.
 <para>
 Don't set architecture to a value other than ``all'' or ``any'' unless you
 really mean it.  In too many cases, maintainers don't follow the instructions
-in the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+in the <ulink url="&url-debian-policy;">Debian Policy
 Manual</ulink>.  Setting your architecture to ``i386'' is usually incorrect.
 </para>
 </listitem>
@@ -1646,11 +1648,11 @@ tools; see the package documentation or references for full information.
 <title>Mailing lists and web pages</title>
 <para>
 Web pages containing the status of each port can be found at <ulink
-url="http://www.debian.org/ports/"></ulink>.
+url="&url-debian-ports;"></ulink>.
 </para>
 <para>
 Each port of Debian has a mailing list.  The list of porting mailing lists can
-be found at <ulink url="http://lists.debian.org/ports.html"></ulink>.  These
+be found at <ulink url="&url-debian-port-lists;"></ulink>.  These
 lists are used to coordinate porters, and to connect the users of a given port
 with the porters.
 </para>
@@ -1688,7 +1690,7 @@ such as <command>andrea</command> and <command>wanna-build</command>.
 <para>
 Some of the data produced by <systemitem role="package">buildd</systemitem>
 which is generally useful to porters is available on the web at <ulink
-url="http://buildd.debian.org/"></ulink>.  This data includes nightly updated
+url="&url-buildd;"></ulink>.  This data includes nightly updated
 information from <command>andrea</command> (source dependencies) and
 <systemitem role="package">quinn-diff</systemitem> (packages needing
 recompilation).
@@ -1744,7 +1746,7 @@ In order to prevent autobuilders from needlessly trying to build your package,
 it must be included in <filename>packages-arch-specific</filename>, a list used
 by the <command>wanna-build</command> script.  The current version is available
 as <ulink
-url="http://cvs.debian.org/srcdep/Packages-arch-specific?cvsroot=dak"></ulink>;
+url="&url-cvsweb;srcdep/Packages-arch-specific?cvsroot=dak"></ulink>;
 please see the top of the file for whom to contact for changes.
 </para>
 </listitem>
@@ -1756,7 +1758,7 @@ architectures: A porter or any other person trying to build your package might
 accidently upload it without noticing it doesn't work.  If in the past some
 binary packages were uploaded on unsupported architectures, request their
 removal by filing a bug against <systemitem
-role="package">ftp.debian.org</systemitem>
+role="package">&ftp-debian-org;</systemitem>
 </para>
 </section>
 
@@ -2029,9 +2031,9 @@ linkend="collaborative-maint"/> ).
 Unless you know the maintainer is still active, it is wise to check the package
 to see if it has been orphaned.  The current list of orphaned packages which
 haven't had their maintainer set correctly is available at <ulink
-url="http://qa.debian.org/orphaned.html"></ulink>.  If you perform an NMU on an
+url="&url-debian-qa-orphaned;"></ulink>.  If you perform an NMU on an
 improperly orphaned package, please set the maintainer to ``Debian QA Group
-&lt;packages@qa.debian.org&gt;''.
+&lt;&pts-host;&gt;''.
 </para>
 </section>
 
@@ -2122,7 +2124,7 @@ Add the co-maintainer's correct maintainer name and address to the
 <filename>debian/control</filename> file.
 </para>
 <screen>
-: John Buzz &lt;jbuzz@debian.org&gt;, Adam Rex &lt;arex@debian.org&gt;
+Uploaders: John Buzz &lt;jbuzz@debian.org&gt;, Adam Rex &lt;arex@debian.org&gt;
 </screen>
 </listitem>
 <listitem>
@@ -2236,7 +2238,7 @@ all the necessary criteria);
 <para>
 To find out whether a package is progressing into testing or not, see the
 testing script output on the <ulink
-url="http://www.debian.org/devel/testing">web page of the testing
+url="&url-devel-docs;testing">web page of the testing
 distribution</ulink>, or use the program <command>grep-excuses</command> which
 is in the <systemitem role="package">devscripts</systemitem> package.  This
 utility can easily be used in a <citerefentry>
@@ -2248,7 +2250,7 @@ to keep yourself informed of the progression of your packages into
 The <filename>update_excuses</filename> file does not always give the precise
 reason why the package is refused; you may have to find it on your own by
 looking for what would break with the inclusion of the package.  The <ulink
-url="http://www.debian.org/devel/testing">testing web page</ulink> gives some
+url="&url-devel-docs;testing">testing web page</ulink> gives some
 more information about the usual problems which may be causing such troubles.
 </para>
 <para>
@@ -2401,7 +2403,7 @@ considered for update.
 </para>
 <para>
 Currently, this requires some manual hinting from the release team.  Please
-contact them by sending mail to <email>debian-release@lists.debian.org</email>
+contact them by sending mail to <email>debian-release@&lists-host;</email>
 if this happens to one of your packages.
 </para>
 </section>
@@ -2449,14 +2451,14 @@ so important for you.)
 </para>
 <para>
 If you want to see more details, you can look it up on
-merkel:/org/ftp.debian.org/testing/update_out/ (or there in
+merkel:/org/&ftp-debian-org;/testing/update_out/ (or there in
 ~aba/testing/update_out to see a setup with a smaller packages file).  Via web,
 it's at <ulink
-url="http://ftp-master.debian.org/testing/update_out_code/"></ulink>
+url="http://&ftp-master-host;/testing/update_out_code/"></ulink>
 </para>
 <para>
 The hints are available via <ulink
-url="http://ftp-master.debian.org/testing/hints/"></ulink>.
+url="http://&ftp-master-host;/testing/hints/"></ulink>.
 </para>
 </section>
 
@@ -2475,7 +2477,7 @@ Keep in mind that packages uploaded there are not automatically processed, they
 have to go through the hands of the release manager.  So you'd better have a
 good reason to upload there.  In order to know what a good reason is in the
 release managers' eyes, you should read the instructions that they regularly
-give on <email>debian-devel-announce@lists.debian.org</email>.
+give on <email>debian-devel-announce@&lists-host;</email>.
 </para>
 <para>
 You should not upload to <emphasis>testing-proposed-updates</emphasis> when you
@@ -2533,7 +2535,7 @@ and lower than in <emphasis>unstable</emphasis>;
 <listitem>
 <para>
 After uploading and successful build on all platforms, contact the release team
-at <email>debian-release@lists.debian.org</email> and ask them to approve your
+at <email>debian-release@&lists-host;</email> and ask them to approve your
 upload.
 </para>
 </listitem>
index cc04f3d..373bc55 100644 (file)
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="resources">
 <title>Resources for Debian Developers</title>
 <para>
@@ -13,11 +15,11 @@ all the other resources that are available to help you in your maintainer work.
 <para>
 Much of the conversation between Debian developers (and users) is managed
 through a wide array of mailing lists we host at <literal><ulink
-url="http://lists.debian.org/">lists.debian.org</ulink></literal>.  To find out
+url="http://&lists-host;/">&lists-host;</ulink></literal>.  To find out
 more on how to subscribe or unsubscribe, how to post and how not to post, where
 to find old posts and how to search them, how to contact the list maintainers
 and see various other information about the mailing lists, please read <ulink
-url="http://www.debian.org/MailingLists/"></ulink>.  This section will only
+url="&url-debian-lists;"></ulink>.  This section will only
 cover aspects of mailing lists that are of particular interest to developers.
 </para>
 <section id="mailing-lists-rules">
@@ -35,7 +37,7 @@ In general, please adhere to the usual conventions for posting messages.
 </para>
 <para>
 Please read the <ulink
-url="http://www.debian.org/MailingLists/#codeofconduct">code of conduct</ulink>
+url="&url-debian-lists;#codeofconduct">code of conduct</ulink>
 for more information.
 </para>
 </section>
@@ -48,52 +50,52 @@ The core Debian mailing lists that developers should use are:
 <itemizedlist>
 <listitem>
 <para>
-<email>debian-devel-announce@lists.debian.org</email>, used to announce
+<email>debian-devel-announce@&lists-host;</email>, used to announce
 important things to developers.  All developers are expected to be subscribed
 to this list.
 </para>
 </listitem>
 <listitem>
 <para>
-<email>debian-devel@lists.debian.org</email>, used to discuss various
+<email>debian-devel@&lists-host;</email>, used to discuss various
 development related technical issues.
 </para>
 </listitem>
 <listitem>
 <para>
-<email>debian-policy@lists.debian.org</email>, where the Debian Policy is
+<email>debian-policy@&lists-host;</email>, where the Debian Policy is
 discussed and voted on.
 </para>
 </listitem>
 <listitem>
 <para>
-<email>debian-project@lists.debian.org</email>, used to discuss various
+<email>debian-project@&lists-host;</email>, used to discuss various
 non-technical issues related to the project.
 </para>
 </listitem>
 </itemizedlist>
 <para>
 There are other mailing lists available for a variety of special topics; see
-<ulink url="http://lists.debian.org/"></ulink> for a list.
+<ulink url="http://&lists-host;/"></ulink> for a list.
 </para>
 </section>
 
 <section id="mailing-lists-special">
 <title>Special lists</title>
 <para>
-<email>debian-private@lists.debian.org</email> is a special mailing list for
+<email>debian-private@&lists-host;</email> 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 publicly.  As such, it
 is a low volume list, and users are urged not to use
-<email>debian-private@lists.debian.org</email> unless it is really necessary.
+<email>debian-private@&lists-host;</email> unless it is really necessary.
 Moreover, do <emphasis>not</emphasis> 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 <literal>lists.debian.org</literal>
-and looking in the <filename>~debian/archive/debian-private</filename>
+can see them using your shell account on <literal>&lists-host;</literal>
+and looking in the <filename>&file-debian-private-archive;</filename>
 directory.
 </para>
 <para>
-<email>debian-email@lists.debian.org</email> is a special mailing list used as
+<email>debian-email@&lists-host;</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.
@@ -111,9 +113,9 @@ a self-managed mailing list on <link linkend="alioth">Alioth</link> is
 more appropriate.
 </para>
 <para>
-If you decide that a regular mailing list on lists.debian.org is really what
+If you decide that a regular mailing list on &lists-host; is really what
 you want, go ahead and fill in a request, following <ulink
-url="http://www.debian.org/MailingLists/HOWTO_start_list">the HOWTO</ulink>.
+url="&url-debian-lists-new;">the HOWTO</ulink>.
 </para>
 </section>
 
@@ -146,10 +148,10 @@ information for developers.
 <para>
 Since <emphasis>#debian-devel</emphasis> is an open channel, you should not
 speak there of issues that are discussed in
-<email>debian-private@lists.debian.org</email>.  There's another channel for
+<email>debian-private@&lists-host;</email>.  There's another channel for
 this purpose, it's called <emphasis>#debian-private</emphasis> and it's
 protected by a key.  This key is available in the archives of debian-private in
-<filename>master.debian.org:~debian/archive/debian-private/</filename>, just
+<filename>master.debian.org:&file-debian-private-archive;</filename>, just
 <command>zgrep</command> for <emphasis>#debian-private</emphasis> in all the
 files.
 </para>
@@ -191,7 +193,7 @@ documentation</ulink> for more information about cloaks.
 <para>
 This document contains a lot of information which is useful to Debian
 developers, but it cannot contain everything.  Most of the other interesting
-documents are linked from <ulink url="http://www.debian.org/devel/">The
+documents are linked from <ulink url="&url-devel-docs;">The
 Developers' Corner</ulink>.  Take the time to browse all the links, you will
 learn many more things.
 </para>
@@ -207,7 +209,7 @@ activities, and they all have a permanent connection to the Internet.
 <para>
 Most of the machines are available for individual developers to use, as long as
 the developers follow the rules set forth in the <ulink
-url="http://www.debian.org/devel/dmup">Debian Machine Usage Policies</ulink>.
+url="&url-devel-docs;dmup">Debian Machine Usage Policies</ulink>.
 </para>
 <para>
 Generally speaking, you can use these machines for Debian-related purposes as
@@ -227,7 +229,7 @@ servers, unless you have prior permission.
 </para>
 <para>
 The current list of Debian machines is available at <ulink
-url="http://db.debian.org/machines.cgi"></ulink>.  That web page contains
+url="&url-devel-machines;"></ulink>.  That web page contains
 machine names, contact information, information about who can log in, SSH keys
 etc.
 </para>
@@ -235,7 +237,7 @@ etc.
 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, the Debian system
 administrator team is reachable at
-<email>debian-admin@lists.debian.org</email>.
+<email>debian-admin@&lists-host;</email>.
 </para>
 <para>
 If you have a problem with a certain service, not related to the system
@@ -251,7 +253,7 @@ mirrored to another server.
 <section id="servers-bugs">
 <title>The bugs server</title>
 <para>
-<literal>bugs.debian.org</literal> is the canonical location for the Bug
+<literal>&bugs-host;</literal> is the canonical location for the Bug
 Tracking System (BTS).
 </para>
 <para>
@@ -260,7 +262,7 @@ It is restricted; a mirror is available on <literal>merkel</literal>.
 <para>
 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@lists.debian.org</email> before implementing anything,
+<email>debian-devel@&lists-host;</email> before implementing anything,
 however, to reduce unnecessary duplication of effort or wasted processing time.
 </para>
 </section>
@@ -268,7 +270,7 @@ however, to reduce unnecessary duplication of effort or wasted processing time.
 <section id="servers-ftp-master">
 <title>The ftp-master server</title>
 <para>
-The <literal>ftp-master.debian.org</literal> server holds the canonical copy of
+The <literal>&ftp-master-host;</literal> server holds the canonical copy of
 the Debian archive (excluding the non-US packages).  Generally, package uploads
 go to this server; see <xref linkend="upload"/> .
 </para>
@@ -277,7 +279,7 @@ It is restricted; a mirror is available on <literal>merkel</literal>.
 </para>
 <para>
 Problems with the Debian FTP archive generally need to be reported as bugs
-against the <systemitem role="package">ftp.debian.org</systemitem>
+against the <systemitem role="package">&ftp-debian-org;</systemitem>
 pseudo-package or an email to <email>ftpmaster@debian.org</email>, but also see
 the procedures in <xref linkend="archive-manip"/> .
 </para>
@@ -286,7 +288,7 @@ the procedures in <xref linkend="archive-manip"/> .
 <section id="servers-non-us">
 <title>The non-US server</title>
 <para>
-The non-US server <literal>non-us.debian.org</literal> was discontinued with
+The non-US server <literal>&non-us-host;</literal> was discontinued with
 the release of sarge.  The pseudo-package <systemitem
 role="package">nonus.debian.org</systemitem> still exists for now.
 </para>
@@ -301,9 +303,9 @@ official web pages, the face of Debian for most newbies.
 <para>
 If you find a problem with the Debian web server, you should generally submit a
 bug against the pseudo-package, <systemitem
-role="package">www.debian.org</systemitem>.  Remember to check whether or not
+role="package">&www-debian-org;</systemitem>.  Remember to check whether or not
 someone else has already reported the problem to the <ulink
-url="http://bugs.debian.org/www.debian.org">Bug Tracking System</ulink>.
+url="http://&bugs-host;/&www-debian-org;">Bug Tracking System</ulink>.
 </para>
 </section>
 
@@ -330,7 +332,7 @@ materials subject to the U.S.  export restrictions, in which case you can use
 one of the other servers located outside the United States.
 </para>
 <para>
-Send mail to <email>debian-devel@lists.debian.org</email> if you have any
+Send mail to <email>debian-devel@&lists-host;</email> if you have any
 questions.
 </para>
 </section>
@@ -350,7 +352,7 @@ a CVS area on the server.
 Generally, <literal>cvs.debian.org</literal> offers a combination of local CVS
 access, anonymous client-server read-only access, and full client-server access
 through <command>ssh</command>.  Also, the CVS area can be accessed read-only
-via the Web at <ulink url="http://cvs.debian.org/"></ulink>.
+via the Web at <ulink url="&url-cvsweb;"></ulink>.
 </para>
 <para>
 To request a CVS area, send a request via email to
@@ -367,13 +369,13 @@ On some machines, there are chroots to different distributions available.  You
 can use them like this:
 </para>
 <screen>
-% dchroot unstable
+vore$ dchroot unstable
 Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable
 </screen>
 <para>
 In all chroots, the normal user home directories are available.  You can find
 out which chroots are available via
-<literal>http://db.debian.org/machines.cgi</literal>.
+<literal>&url-devel-machines;</literal>.
 </para>
 </section>
 
@@ -382,14 +384,14 @@ out which chroots are available via
 <section id="devel-db">
 <title>The Developers Database</title>
 <para>
-The Developers Database, at <ulink url="https://db.debian.org/"></ulink>, is an
+The Developers Database, at <ulink url="&url-debian-db;"></ulink>, is an
 LDAP directory for managing Debian developer attributes.  You can use this
 resource to search the list of Debian developers.  Part of this information is
 also available through the finger service on Debian servers, try
 <command>finger yourlogin@db.debian.org</command> to see what it reports.
 </para>
 <para>
-Developers can <ulink url="https://db.debian.org/login.html">log into the
+Developers can <ulink url="&url-debian-db-login;">log into the
 database</ulink> to change various information about themselves, such as:
 </para>
 <itemizedlist>
@@ -412,7 +414,7 @@ whether you are on vacation
 <para>
 personal information such as your address, country, the latitude and longitude
 of the place where you live for use in <ulink
-url="http://www.debian.org/devel/developers.loc">the world map of Debian
+url="&url-devel-docs;developers.loc">the world map of Debian
 developers</ulink>, phone and fax numbers, IRC nickname and web page
 </para>
 </listitem>
@@ -425,86 +427,27 @@ password and preferred shell on Debian Project machines
 <para>
 Most of the information is not accessible to the public, naturally.  For more
 information please read the online documentation that you can find at <ulink
-url="http://db.debian.org/doc-general.html"></ulink>.
+url="&url-debian-db-doc;"></ulink>.
 </para>
 <para>
 Developers can also submit their SSH keys to be used for authorization on the
 official Debian machines, and even add new *.debian.net DNS entries.  Those
 features are documented at <ulink
-url="http://db.debian.org/doc-mail.html"></ulink>.
+url="&url-debian-db-mail-gw;"></ulink>.
 </para>
 </section>
 
 <section id="archive">
 <title>The Debian archive</title>
 <para>
-The Debian GNU/Linux distribution consists of a lot of packages
-(<filename>.deb</filename>'s, currently around 9000) and a few additional files
+The &debian-formal; distribution consists of a lot of packages
+(<filename>.deb</filename>'s, currently around &number-of-pkgs;) and a few additional files
 (such as documentation and installation disk images).
 </para>
 <para>
 Here is an example directory tree of a complete Debian archive:
 </para>
-<screen>
-/stable/main/
-dists/stable/main/binary-i386/
-dists/stable/main/binary-m68k/
-dists/stable/main/binary-alpha/
-     ...
-dists/stable/main/source/
-     ...
-dists/stable/main/disks-i386/
-dists/stable/main/disks-m68k/
-dists/stable/main/disks-alpha/
-     ...
-
-dists/stable/contrib/
-dists/stable/contrib/binary-i386/
-dists/stable/contrib/binary-m68k/
-dists/stable/contrib/binary-alpha/
-     ...
-dists/stable/contrib/source/
-
-dists/stable/non-free/
-dists/stable/non-free/binary-i386/
-dists/stable/non-free/binary-m68k/
-dists/stable/non-free/binary-alpha/
-     ...
-dists/stable/non-free/source/
-
-dists/testing/
-dists/testing/main/
-     ...
-dists/testing/contrib/
-     ...
-dists/testing/non-free/
-     ...
-
-dists/unstable
-dists/unstable/main/
-     ...
-dists/unstable/contrib/
-     ...
-dists/unstable/non-free/
-     ...
-
-pool/
-pool/main/a/
-pool/main/a/apt/
-     ...
-pool/main/b/
-pool/main/b/bash/
-     ...
-pool/main/liba/
-pool/main/liba/libalias-perl/
-     ...
-pool/main/m/
-pool/main/m/mailx/
-     ...
-pool/non-free/n/
-pool/non-free/n/netscape/
-     ...
-</screen>
+&sample-dist-dirtree;
 <para>
 As you can see, the top-level directory contains two directories,
 <filename>dists/</filename> and <filename>pool/</filename>.  The latter is a
@@ -539,17 +482,17 @@ installing the Debian distribution on a specific architecture
 <title>Sections</title>
 <para>
 The <emphasis>main</emphasis> section of the Debian archive is what makes up
-the <emphasis role="strong">official Debian GNU/Linux distribution</emphasis>.
+the <emphasis role="strong">official &debian-formal; distribution</emphasis>.
 The <emphasis>main</emphasis> section is official because it fully complies
 with all our guidelines.  The other two sections do not, to different degrees;
 as such, they are <emphasis role="strong">not</emphasis> officially part of
-Debian GNU/Linux.
+&debian-formal;.
 </para>
 <para>
 Every package in the main section must fully comply with the <ulink
-url="http://www.debian.org/social_contract#guidelines">Debian Free Software
+url="&url-dfsg;">Debian Free Software
 Guidelines</ulink> (DFSG) and with all other policy requirements as described
-in the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+in the <ulink url="&url-debian-policy;">Debian Policy
 Manual</ulink>.  The DFSG is our definition of “free software.” Check out
 the Debian Policy Manual for details.
 </para>
@@ -566,7 +509,7 @@ infrastructure (such as our bug-tracking system and mailing lists) for non-free
 software packages.
 </para>
 <para>
-The <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+The <ulink url="&url-debian-policy;">Debian Policy
 Manual</ulink> contains a more exact definition of the three sections.  The
 above discussion is just an introduction.
 </para>
@@ -616,7 +559,7 @@ is <emphasis>m68k</emphasis>, <emphasis>alpha</emphasis>,
 <emphasis>mipsel</emphasis> and <emphasis>sh</emphasis> as of this writing.
 </para>
 <para>
-Debian GNU/Linux 1.3 is only available as <emphasis>i386</emphasis>.  Debian
+&debian-formal; 1.3 is only available as <emphasis>i386</emphasis>.  Debian
 2.0 shipped for <emphasis>i386</emphasis> and <emphasis>m68k</emphasis>
 architectures.  Debian 2.1 ships for the <emphasis>i386</emphasis>,
 <emphasis>m68k</emphasis>, <emphasis>alpha</emphasis>, and
@@ -628,7 +571,7 @@ and <emphasis>mipsel</emphasis>.
 </para>
 <para>
 Information for developers and users about the specific ports are available at
-the <ulink url="http://www.debian.org/ports/">Debian Ports web pages</ulink>.
+the <ulink url="&url-debian-ports;">Debian Ports web pages</ulink>.
 </para>
 </section>
 
@@ -724,7 +667,7 @@ the Release Team, the distribution is released.  Releasing means that
 new copy is created for the new <emphasis>testing</emphasis>, and the previous
 <emphasis>stable</emphasis> is renamed to <emphasis>oldstable</emphasis> and
 stays there until it is finally archived.  On archiving, the contents are moved
-to <literal>archive.debian.org</literal>).
+to <literal>&archive-host;</literal>).
 </para>
 <para>
 This development cycle is based on the assumption that the
@@ -780,10 +723,10 @@ These are the <citerefentry> <refentrytitle>sources.list</refentrytitle>
 <manvolnum>5</manvolnum> </citerefentry> lines for
 <emphasis>experimental</emphasis>:
 </para>
-<screen>
- http://ftp.<replaceable>xy</replaceable>.debian.org/debian/ experimental main
+<programlisting>
+deb http://ftp.<replaceable>xy</replaceable>.debian.org/debian/ experimental main
 deb-src http://ftp.<replaceable>xy</replaceable>.debian.org/debian/ experimental main
-</screen>
+</programlisting>
 <para>
 If there is a chance that the software could do grave damage to a system, it is
 likely to be better to put it into <emphasis>experimental</emphasis>.  For
@@ -888,7 +831,7 @@ push mirroring).
 <para>
 All the information on Debian mirrors, including a list of the available public
 FTP/HTTP servers, can be found at <ulink
-url="http://www.debian.org/mirror/"></ulink>.  This useful page also includes
+url="url-debian-mirroring"></ulink>.  This useful page also includes
 information and tools which can be helpful if you are interested in setting up
 your own mirror, either for internal or public access.
 </para>
@@ -904,7 +847,7 @@ machines.
 <para>
 The Incoming system is responsible for collecting updated packages and
 installing them in the Debian archive.  It consists of a set of directories and
-scripts that are installed on <literal>ftp-master.debian.org</literal>.
+scripts that are installed on <literal>&ftp-master-host;</literal>.
 </para>
 <para>
 Packages are uploaded by all the maintainers into a directory called
@@ -942,14 +885,14 @@ The archive maintenance software will also send the OpenPGP/GnuPG signed
 <filename>.changes</filename> file that you uploaded to the appropriate mailing
 lists.  If a package is released with the <literal>Distribution:</literal> set
 to `stable', the announcement is sent to
-<email>debian-changes@lists.debian.org</email>.  If a package is released with
+<email>debian-changes@&lists-host;</email>.  If a package is released with
 <literal>Distribution:</literal> set to `unstable' or `experimental', the
 announcement will be posted to
-<email>debian-devel-changes@lists.debian.org</email> instead.
+<email>debian-devel-changes@&lists-host;</email> instead.
 </para>
 <para>
 Though ftp-master is restricted, a copy of the installation is available to all
-developers on <literal>merkel.debian.org</literal>.
+developers on <literal>&ftp-master-mirror;</literal>.
 </para>
 <!-- FIXME: delete it or keep it for historical purposes?
 <para>
@@ -992,16 +935,16 @@ The use of that delayed feature can be simplified with a bit
 of integration with your upload tool.  For instance, if you use 
 <command>dupload</command> (see <xref linkend="dupload"/>), you can add this
 snippet to your configuration file:
-<screen>
+<programlisting>
 $delay = ($ENV{DELAY} || 7);
 $cfg{'delayed'} = {
          fqdn => "&ftp-master-host;",
          login => "yourdebianlogin",
-         incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
+         incoming => "/org/&ftp-debian-org;/incoming/DELAYED/$delay-day/",
          dinstall_runs => 1,
          method => "scpb"
 };
-</screen>
+</programlisting>
 Once you've made that change, <command>dupload</command> can be used to
 easily upload a package in one of the delayed directories:
 <literal>DELAY=5 dupload -X-to delayed &lt;changes-file&gt;</literal>
@@ -1016,7 +959,7 @@ easily upload a package in one of the delayed directories:
 <title>On the web</title>
 <para>
 Each package has several dedicated web pages.
-<literal>http://packages.debian.org/<replaceable>package-name</replaceable></literal>
+<literal>http://&packages-host;/<replaceable>package-name</replaceable></literal>
 displays each version of the package available in the various distributions.
 Each version links to a page which provides information, including the package
 description, the dependencies, and package download links.
@@ -1024,7 +967,7 @@ description, the dependencies, and package download links.
 <para>
 The bug tracking system tracks bugs for each package.  You can view the bugs of
 a given package at the URL
-<literal>http://bugs.debian.org/<replaceable>package-name</replaceable></literal>.
+<literal>http://&bugs-host;/<replaceable>package-name</replaceable></literal>.
 </para>
 </section>
 
@@ -1032,8 +975,8 @@ a given package at the URL
 <title>The <command>madison</command> utility</title>
 <para>
 <command>madison</command> is a command-line utility that is available on
-<literal>ftp-master.debian.org</literal>, and on the mirror on
-<literal>merkel.debian.org</literal>.  It uses a single argument corresponding
+<literal>&ftp-master-host;</literal>, and on the mirror on
+<literal>&ftp-master-mirror;</literal>.  It uses a single argument corresponding
 to a package name.  In result it displays which version of the package is
 available for each architecture and distribution combination.  An example will
 explain it better.
@@ -1082,7 +1025,7 @@ All the bug reports and following discussions.
 <term><literal>bts-control</literal></term>
 <listitem>
 <para>
-The email notifications from <email>control@bugs.debian.org</email> about bug
+The email notifications from <email>control@&bugs-host;</email> about bug
 report status changes.
 </para>
 </listitem>
@@ -1111,7 +1054,7 @@ override disparity for the section and/or the priority field).
 <para>
 Any non-automatic email sent to the PTS by people who wanted to contact the
 subscribers of the package.  This can be done by sending mail to
-<literal><replaceable>sourcepackage</replaceable>@packages.qa.debian.org</literal>.
+<literal><replaceable>sourcepackage</replaceable>@&pts-host;</literal>.
 In order to prevent spam, all messages sent to these addresses must contain the
 <literal>X-PTS-Approved</literal> header with a non-empty value.
 </para>
@@ -1235,7 +1178,7 @@ summary:
 <listitem>
 <para>
 <literal>bts-control</literal>: reply to mails sent to
-<email>control@bugs.debian.org</email>
+<email>control@&bugs-host;</email>
 </para>
 </listitem>
 <listitem>
@@ -1345,7 +1288,7 @@ upload.
 <title>Filtering PTS mails</title>
 <para>
 Once you are subscribed to a package, you will get the mails sent to
-<literal><replaceable>sourcepackage</replaceable>@packages.qa.debian.org</literal>.
+<literal><replaceable>sourcepackage</replaceable>@&pts-host;</literal>.
 Those mails have special headers appended to let you filter them in a special
 mailbox (e.g.  with <command>procmail</command>).  The added headers are
 <literal>X-Loop</literal>, <literal>X-PTS-Package</literal>,
@@ -1356,7 +1299,7 @@ Here is an example of added headers for a source upload notification on the
 <systemitem role="package">dpkg</systemitem> package:
 </para>
 <screen>
--Loop: dpkg@packages.qa.debian.org
+X-Loop: dpkg@&pts-host;
 X-PTS-Package: dpkg
 X-PTS-Keyword: upload-source
 X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
@@ -1374,7 +1317,7 @@ evolution.
 <para>
 Once you set up the CVS repository to generate commit notifications, you just
 have to make sure it sends a copy of those mails to
-<literal><replaceable>sourcepackage</replaceable>_cvs@packages.qa.debian.org</literal>.
+<literal><replaceable>sourcepackage</replaceable>_cvs@&pts-host;</literal>.
 Only the people who accept the <emphasis>cvs</emphasis> keyword will receive
 these notifications.
 </para>
@@ -1384,7 +1327,7 @@ these notifications.
 <title>The PTS web interface</title>
 <para>
 The PTS has a web interface at <ulink
-url="http://packages.qa.debian.org/"></ulink> that puts together a lot of
+url="http://&pts-host;/"></ulink> that puts together a lot of
 information about each source package.  It features many useful links (BTS, QA
 stats, contact information, DDTP translation status, buildd logs) and gathers
 much more information from various places (30 latest changelog entries, testing
@@ -1395,7 +1338,7 @@ subscription to the PTS via email.
 <para>
 You can jump directly to the web page concerning a specific source package with
 a URL like
-<literal>http://packages.qa.debian.org/<replaceable>sourcepackage</replaceable></literal>.
+<literal>http://&pts-host;/<replaceable>sourcepackage</replaceable></literal>.
 </para>
 <para>
 This web interface has been designed like a portal for the development of
@@ -1492,12 +1435,12 @@ The first one adds a link to the cvsweb interface of debian-cd in the Static
 information section:
 </para>
 <screen>
-: Raphael Hertzog &lt;hertzog@debian.org&gt;
+From: Raphael Hertzog &lt;hertzog@debian.org&gt;
 To: pts-static-news@qa.debian.org
 Subject: Browse debian-cd CVS repository with cvsweb
 
 Package: debian-cd
-Url: http://cvs.debian.org/debian-cd/
+Url: &url-cvsweb;debian-cd/
 </screen>
 <para>
 The second one is an announcement sent to a mailing list which is also sent to
@@ -1506,7 +1449,7 @@ use of the BCC field to avoid answers sent to the PTS by mistake.
 </para>
 <screen>
 : Raphael Hertzog &lt;hertzog@debian.org&gt;
-To: debian-gtk-gnome@lists.debian.org
+To: debian-gtk-gnome@&lists-host;
 Bcc: pts-news@qa.debian.org
 Subject: Galeon 2.0 backported for woody
 X-PTS-Package: galeon
@@ -1531,7 +1474,7 @@ contained in the previous one.
 <title>Developer's packages overview</title>
 <para>
 A QA (quality assurance) web portal is available at <ulink
-url="http://qa.debian.org/developer.php"></ulink> which displays a table
+url="&url-debian-qa;developer.php"></ulink> which displays a table
 listing all the packages of a single developer (including those where the party
 is listed as a co-maintainer).  The table gives a good summary about the
 developer's packages: number of bugs by severity, list of available versions in
@@ -1579,7 +1522,7 @@ url="http://alioth.debian.org/"></ulink>.
 Since October of 2002, HP has sponsored a subscription to LWN for all
 interested Debian developers.  Details on how to get access to this benefit are
 in <ulink
-url="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html"></ulink>.
+url="http://&lists-host;/debian-devel-announce/2002/10/msg00018.html"></ulink>.
 </para>
 </section>
 
index d4788a6..ea7b71a 100644 (file)
--- a/scope.dbk
+++ b/scope.dbk
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <chapter id="scope">
 <title>Scope of This Document</title>
 <para>
@@ -30,7 +32,7 @@ It should be clear that this reference does not discuss the technical details
 of Debian packages nor how to generate them.  Nor does this reference detail
 the standards to which Debian software must comply.  All of such information
 can be found in the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink>.
+url="&url-debian-policy;">Debian Policy Manual</ulink>.
 </para>
 <para>
 Furthermore, this document is <emphasis>not an expression of formal
index de5cfd4..25d61a0 100644 (file)
--- a/tools.dbk
+++ b/tools.dbk
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+  <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
+]>
 <appendix id="tools">
 <title>Overview of Debian Maintainer Tools</title>
 <para>
@@ -104,7 +106,7 @@ use Lintian.
 </para>
 <para>
 You can also see a summary of all problems reported by Lintian on your packages
-at <ulink url="http://lintian.debian.org/"></ulink>.  These reports contain the
+at <ulink url="&url-lintian;"></ulink>.  These reports contain the
 latest <command>lintian</command> output for the whole development distribution
 (unstable).
 </para>
@@ -134,13 +136,13 @@ help you prevent various accidents.
 You can run it over a pair of binary packages:
 </para>
 <screen>
- package_1-1_arch.deb package_2-1_arch.deb
+debdiff package_1-1_arch.deb package_2-1_arch.deb
 </screen>
 <para>
 Or even a pair of changes files:
 </para>
 <screen>
- package_1-1_arch.changes package_2-1_arch.changes
+debdiff package_1-1_arch.changes package_2-1_arch.changes
 </screen>
 <para>
 For more information please see <citerefentry>
@@ -314,7 +316,7 @@ It can use chrooted environments as well.  It can be used stand-alone, or as
 part of a networked, distributed build environment.  As the latter, it is part
 of the system used by porters to build binary packages for all the available
 architectures.  See <xref linkend="buildd"/> for more information, and <ulink
-url="http://buildd.debian.org/"></ulink> to see the system in action.
+url="&url-buildd;"></ulink> to see the system in action.
 </para>
 </section>
 
@@ -457,7 +459,7 @@ process through <command>dpkg-depcheck</command> will provide you with a good
 first approximation of the build-dependencies.  For example:
 </para>
 <screen>
--depcheck -b debian/rules build
+dpkg-depcheck -b debian/rules build
 </screen>
 <para>
 <command>dpkg-depcheck</command> can also be used to check for run-time