<?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" [
- <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
+ <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
]>
<chapter id="best-pkging-practices">
<title>Best Packaging Practices</title>
better, since you don't have to learn the intricacies of any helper system.
This decision is completely up to you. Use what works for you. Many examples
of vanilla <filename>debian/rules</filename> files are available at <ulink
-url="http://arch.debian.org/arch/private/srivasta/"></ulink>.
+url="&url-rules-files;"></ulink>.
</para>
</section>
</para>
<para>
If you are having problems writing your description, you may wish to send it
-along to <email>debian-l10n-english@&lists-host;</email> and request
-feedback.
+along to &email-debian-l10n-english; and request feedback.
</para>
</section>
<section id="bpp-upstream-info">
<title>Upstream home page</title>
<para>
-We recommend that you add the URL for the package's home page to the package
-description in <filename>debian/control</filename>. This information should be
-added at the end of description, using the following format:
-</para>
-<screen>
- .
- Homepage: http://some-project.some-place.org/
-</screen>
-<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-host;/unstable/web/wml"></ulink>.
-</para>
-<para>
-If there is no home page for the software, this should naturally be left out.
-</para>
-<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-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-host;</filename> to parse it correctly.
+We recommend that you add the URL for the package's home page in the
+<literal>Homepage</literal> field of the <literal>Source</literal> section
+in <filename>debian/control</filename>. Adding this information in the
+package description itself is considered deprecated.
</para>
</section>
<filename>debian/control</filename>.
</para>
<section id="s6.2.5.1">
-<title>XS-Vcs-Browser</title>
+<title>Vcs-Browser</title>
<para>
Value of this field should be a <literal>http://</literal> URL pointing to a
web-browsable copy of the Version Control System repository used to maintain
</section>
<section id="s6.2.5.2">
-<title>XS-Vcs-*</title>
+<title>Vcs-*</title>
<para>
Value of this field should be a string identifying unequivocally the location
of the Version Control System repository used to maintain the given package, if
the URL is in the <literal>svn://</literal> scheme (instead of
<literal>svn+ssh://</literal>) and how it points to the
<filename>trunk/</filename> branch. The use of the
-<literal>XS-Vcs-Browser</literal> field described above is also shown.
+<literal>Vcs-Browser</literal> and <literal>Homepage</literal> fields
+described above is also shown.
</para>
<screen>
Source: vim
Section: editors
Priority: optional
<snip>
- XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
- XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
+ Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
+ Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
+ Homepage: http://www.vim.org
</screen>
</section>
properly phrased templates may not be easy for them.
</para>
<para>
-Please use (and abuse) <email>debian-l10n-english@&lists-host;</email>
-mailing list. Have your templates proofread.
+Please use (and abuse) &email-debian-l10n-english; mailing
+list. Have your templates proofread.
</para>
<para>
Badly written templates give a poor image of your package, of your work...or
<para>
If in doubt, you may also contact the translation team for a given language
(debian-l10n-xxxxx@&lists-host;), or the
-<email>debian-i18n@&lists-host;</email> mailing list.
+&email-debian-i18n; mailing list.
</para>
<para>
-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
-avoid duplicate work.
+Calls for translations posted to &email-debian-i18n; 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 avoid duplicate
+work.
</para>
</section>
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="&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
-the current revision of the file to be translated and, for a translated file,
-the revision of the original file the translation is based on. You might wish
-to adapt and provide that in your CVS area.
+url="&url-i18n-doc-check;">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 the current revision of the file to be translated and, for a
+translated file, the revision of the original file the translation is based on.
+You might wish to adapt and provide that in your CVS area.
</para>
<para>
If you maintain XML or SGML documentation, we suggest that you isolate any
<listitem>
<para>
Python related packages have their python policy; see
-<filename>/usr/share/doc/python/python-policy.txt.gz</filename> in the
-<systemitem role="package">python</systemitem> package.
+&file-python-policy; in the <systemitem
+role="package">python</systemitem> package.
</para>
</listitem>
<listitem>
<listitem>
<para>
Ocaml related packages have their own policy, found in
-<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename> from the
-<systemitem role="package">ocaml</systemitem> package. A good example is the
-<systemitem role="package">camlzip</systemitem> source package.
+&file-ocaml-policy; from the <systemitem
+role="package">ocaml</systemitem> package. A good example is the <systemitem
+role="package">camlzip</systemitem> source package.
</para>
</listitem>
<listitem>
this trick:
</para>
<para>
-If you set <varname>LOCPATH</varname> to the equivalent of <literal>/usr/lib/locale</literal>, and <varname>LC_ALL</varname> to the name
+If you set <varname>LOCPATH</varname> to the equivalent of <filename>/usr/lib/locale</filename>, 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>
~ianmdlvl / developers-reference.git / blobdiff