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/[email protected] 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">
