Re: Changing manpages (was Re: hwclock and time gazworks...)
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
Reply to: