Re: Writing manpages

[Ben Finney <ben+debian@benfinney.id.au>]

Charles Plessy <plessy@debian.org> 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
requirements.

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
>  information.
>  </para>
> +<para>

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.
    +</para>
    +<para>
    +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.
> +</para>
>  </section>
>  
>  <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 |
_o__)                                                                  |
Ben Finney