Recommendations for man pages in Debian (was: Debian Policy 3.8.3.0 released: localized manpages)

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

Roger Leigh <rleigh@codelibre.net> writes:

> On Mon, Aug 17, 2009 at 01:01:34PM +1000, Ben Finney wrote:
> > I assume we expect man pages to conform to the conventions in
> > ‘man-pages(7)’.

(I've now been disabused of that assumption.)

> I'm not sure we can have that expectation. If you look at
> groff_man(7), it specifies:
>
>   .TH title section [extra1] [extra2] [extra3]
>
> and details how the extra bits are positioned, but no more. While the
> man-pages conventions IIRC are also seen in some GNU and UNIX manual
> pages, things like the date *format* appear to be man-pages-specific.

I guess the question then becomes: since Policy describes supposed best
practice for Debian, *should* we be more specific about the format of a
man page? I think the conventions described in ‘man-pages(7)’ are a good
basis for recommendations for all Debian man pages.

> I, for example, use the date format '+%d %b %Y' (01 Aug 2009). The
> manual pages are human readable documentation. I think that nicely
> readable dates should be preferred here.

This seems to falsely imply a necessary conflict between “nicely
readable dates” and “ISO 8601 date representations”. The fact that
they're simple and unambiguous, and to many readers interpretable
without further explanation, I think makes them a good candidate for
“nicely readable”.

-- 
 \      “Puritanism: The haunting fear that someone, somewhere, may be |
  `\                                         happy.” —Henry L. Mencken |
_o__)                                                                  |
Ben Finney