Recommendations for man pages in Debian (was: Debian Policy 184.108.40.206 released: localized manpages)
Roger Leigh <firstname.lastname@example.org> 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
\ “Puritanism: The haunting fear that someone, somewhere, may be |
`\ happy.” —Henry L. Mencken |