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 56b7c3cab1c073930577983fcbc17fa559a4229f..77ae40dc68a8995ff8831bb8b57a6c7ab37526c4 100644 (file)
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -1484,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">
@@ -1734,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