Re: Recommendations for man pages in Debian (was: Debian Policy 3.8.3.0 released: localized manpages)
On Tue, Aug 18, 2009 at 08:13:20PM +1000, Ben Finney wrote:
> 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.
Absolutely. I might have a minor quibble over the date formatting, but
the conventions are good.
Relating back to the subject of this thread, localisation of manpages,
I don't think that the page date is a good item for translators to
track to look for changes. It's just not robust enough. Most are
updated by hand (and invariably forgotten), or are automatically
generated (and hence will always look out of date). Wouldn't a better
approach here be to track the entire page content using a hash of the
content, e.g. SHAnSUM á la git? The translator could write the hash
into the translated file, to give a starting point for subsequent
updates.
Don't we have translation infrastructure to deal with this sort of
scenario yet? I confess, I'm only familiar with gettext localisation
of program code, not document translation, so an explanation of the
requirements/tools would be most helpful.
> > 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”.
It's only unambiguous if you know the convention being adopted /is/
ISO-8601. In an ideal world, we could have a standardised date format
which the man program can transform into the date representation of
the user's locale thus satisfying all requirements.
Regards,
Roger
--
.''`. Roger Leigh
: :' : Debian GNU/Linux http://people.debian.org/~rleigh/
`. `' Printing on GNU/Linux? http://gutenprint.sourceforge.net/
`- GPG Public Key: 0x25BFB848 Please GPG sign your mail.
Reply to: