Re: Writing manpages
Charles Plessy <email@example.com> writes:
> Le Thu, Nov 19, 2009 at 11:14:10AM +1100, Ben Finney a écrit :
> > Now if only we can convince more package maintainers. Hopefully the
> > ability to use these source formats, with steady evangelisation
> > about the available rendering tools, can lower the resistance to
> > following policy on providing manpages for all commands.
> Dear all,
> how about the followign patch to the developers's reference ?
> (In § 6.7.3)
Thanks for this contribution, it is well written and addresses the need
for package maintainers to take responsibility for the policy
I would pick a couple of nits with this:
> Index: best-pkging-practices.dbk
> --- best-pkging-practices.dbk (revision 6986)
> +++ best-pkging-practices.dbk (working copy)
> @@ -1484,6 +1484,14 @@
> role="package">doc-base</systemitem> package documentation for more
I think it's important to point out that manpages are a “should”
directive not only for programs but other objects as well:
+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.
+The manpages do not need to be written directly in the troff format.
> +Popular intermediate formats are Docbook, POD and reST, which
For those writing a manpage in those formats, the troff format is the
intermediate or destination format; in this context, Docbook, POD, and
reST are source formats. So:
+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.
> <section id="bpp-other">
With the above changes, I approve of that addition. Thanks!
\ “Quidquid latine dictum sit, altum viditur.” (“Whatever is |
`\ said in Latin, sounds profound.”) —anonymous |