Bug#557298: developers-reference: Suggestion for manpage formats easier than troff.
Package: developers-reference
Version: 3.4.3
Severity: normal
Tags: patch
Dear all,
Here is a patch to the Developers Reference, that aims at stimulating manpage
writing by suggesting DocBook, POD and reST as source format to the maintainers
uncomfortable with troff.
It summarises the collective effort of the debian-mentors mailing list
communauty, started at:
lists.debian.org/msgid-search/20091118073033.GB2552@ime.usp.br
Have a nice day,
--
Charles Plessy
Tsurumi, Kanagawa, Japan
Index: best-pkging-practices.dbk
===================================================================
--- best-pkging-practices.dbk (révision 6986)
+++ best-pkging-practices.dbk (copie de travail)
@@ -1484,6 +1484,20 @@
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">
Reply to: