Re: Changing manpages (was Re: hwclock and time gazworks...)

[Thierry Laronde <thierry.laronde@polynum.com>]

On Mon, Jan 31, 2000 at 10:12:54PM +0000, Oliver Elphick wrote:
> Thierry Laronde wrote:
>   >So, indeed, we can rework, for woody, hwclock manpage, if we, IMHO, keep
>   >in mind the following :
>   >
>   >- a man (1) page must *NOT* be Debian specific, nor any distribution
>   >specific; it must be an "objective" description of what the program is
>   >supposed to do, and how it can perform its task. A "SEE ALSO" pointer
>   >has to be put for an eventual man page in section 8, describing how
>   >the program is handle in the system/distribution specific environment;
>   >
>   >- in section 8, we could creat a kind of meta-section, namely `time'
>   >describing the Debian policy about these issues;
>   >
>   >Any comments welcome.
> 
> I don't at all see why a manpage for a Debian package shouldn't document
> Debian-specific information.  If I run man on a Sun or an HP, I expect
> to read about how the program works on Sun or HP.  Similarly, if I do
> man on Debian, I expect to read how it works on Debian.
> 
> It is a constant source of annoyance to me when manpages give incorrect
> information, that was correct for the original author's Sun.
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
That's a part of what I'd like to change. A *same* program has the very
same options. The way it is integrated in a whole --- and that's what a
distribution does : create a whole with heterogeneous parts --- should
be kept away from the body of the man page, and only reflected in the
`files' and `see also'.

What is bothering you is precisely a Sun dependant part in a man page. I
think that these man pages could be of some help for all the systems, if
the system specific stuff is kept in specific places.

Say that this is a "philosophical" point of vue. A bad man page is not
acceptable. So a debian correct man page is better than an incorrect one.
But a distribution independant one is, IMHO, the best one.

Cheers,
-- 
Thierry LARONDE
thierry.laronde@polynum.com
website : http://www.polynum.com