Mention docbook, POD and reST as convenient formats to write new manual pages

[developers-reference.git] / best-pkging-practices.dbk

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 435bbba54e2a784f0f8db7115633525835aaf983..77ae40dc68a8995ff8831bb8b57a6c7ab37526c4 100644 (file)
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -101,22 +101,24 @@ separating the patches into several files.  Nevertheless, there are ways to
 separate patches: the patch files are shipped within the Debian patch file
 (<filename>.diff.gz</filename>), usually within the
 <filename>debian/</filename> directory.  The only difference is that they
-aren't applied immediately by dpkg-source, but by the <literal>build</literal>
-rule of <filename>debian/rules</filename>.  Conversely, they are reverted in
-the <literal>clean</literal> rule.
+aren't applied immediately by dpkg-source,
+but by the <literal>build</literal>
+rule of <filename>debian/rules</filename>,
+through a dependency on the <literal>patch</literal> rule.
+Conversely, they are reverted in
+the <literal>clean</literal> rule,
+through a dependency on the <literal>unpatch</literal> rule.
 </para>
 <para>
-<command>dbs</command> is one of the more popular approaches to this.  It does
-all of the above, and provides a facility for creating new and updating old
-patches.  See the package <systemitem role="package">dbs</systemitem> for more
-information and <systemitem role="package">hello-dbs</systemitem> for an
-example.
+<command>quilt</command> is the recommended tool for this.
+It does all of the above, and also allows to manage patch series.
+See the 
+<systemitem role="package">quilt</systemitem> package for more information.
 </para>
 <para>
-<command>dpatch</command> also provides these facilities, but it's intended to
-be even easier to use.  See the package <systemitem
-role="package">dpatch</systemitem> for documentation and examples (in
-<filename>/usr/share/doc/dpatch</filename>).
+There are other tools to manage patches, like <command>dpatch</command>,
+and the patch system integrated with
+<systemitem role="package">cdbs</systemitem>.
 </para>
 </section>
 
@@ -1482,6 +1484,20 @@ role="package">doc-base</systemitem> on installation.  See the <systemitem
 role="package">doc-base</systemitem> package documentation for more
 information.
 </para>
+<para>
+Debian policy (section 12.1) directs that manual pages should accompany every
+program, utility, and function, and suggests them for other objects like
+configuration files. If the work you are packaging does not have such manual
+pages, consider writing them for inclusion in your package, and submitting them
+upstream.
+</para>
+<para>
+The manpages do not need to be written directly in the troff format.  Popular
+source formats are Docbook, POD and reST, which can be converted using
+<command>xsltproc</command>, <command>pod2man</command> and
+<command>rst2man</command> respectively. To a lesser extent, the <command>
+help2man</command>program can also be used to write a stub.
+</para>
 </section>
 
 <section id="bpp-other">
@@ -1732,9 +1748,9 @@ A repackaged <literal>.orig.tar.gz</literal>
 <orderedlist numeration="arabic">
 <listitem>
 <para>
-<emphasis role="strong">must</emphasis> be documented in the resulting source package.
+should be documented in the resulting source package.
 Detailed information on how the repackaged source was obtained,
-and on how this can be reproduced must be provided in
+and on how this can be reproduced should be provided in
 <filename>debian/copyright</filename>.  It is also a good idea to provide a
 <literal>get-orig-source</literal> target in your
 <filename>debian/rules</filename> file that repeats the process, as described
@@ -1750,8 +1766,7 @@ come from the upstream author(s), or whose contents has been changed by you.
 <footnote><para> As a special exception, if the omission of non-free files
 would lead to the source failing to build without assistance from the Debian
 diff, it might be appropriate to instead edit the files, omitting only the
-non-free parts of them, and/or explain the situation in a README.Debian-source
-<!-- or similarly named -->
+non-free parts of them, and/or explain the situation in a README.source
 file in the root of the source tree.  But in that case please also urge the
 upstream author to make the non-free components easier seperable from the rest
 of the source.  </para> </footnote>