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

Thanks to Charles Plessy and the debian-mentors list for the idea and the
patch. Closes: #557298

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@7030 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 1800e063165ff10b88f6b347fec337e6593d3c92..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>
 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">
 </section>
 
 <section id="bpp-other">

diff --git a/debian/changelog b/debian/changelog
index 9f8395471b098c310a33c8de1d23cb671956f6fc..d9c172ffb4ffcd2cd116e75e132f9508a400089c 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -23,6 +23,9 @@ developers-reference (3.4.4) UNRELEASED; urgency=low
     <smcv@debian.org> for the patches:
     - point to official names {ftp,ssh}.upload.debian.org. Closes: #554054
     - drop references to non-working queues. Closes: #554077
     <smcv@debian.org> for the patches:
     - point to official names {ftp,ssh}.upload.debian.org. Closes: #554054
     - drop references to non-working queues. Closes: #554077

+  * Mention docbook, POD and reST as convenient formats to write new manual
+    pages. Thanks to Charles Plessy and the debian-mentors list
+    for the idea and the patch. Closes: #557298

 
  -- Lucas Nussbaum <lucas@lucas-nussbaum.net>  Tue, 22 Dec 2009 22:49:40 +0900
 
 
  -- Lucas Nussbaum <lucas@lucas-nussbaum.net>  Tue, 22 Dec 2009 22:49:40 +0900