Re: Changing manpages (was Re: hwclock and time gazworks...)
- To: Oliver Elphick <olly@lfix.co.uk>
- Cc: Henrique M Holschuh <hmh+debianml@rcm.org.br>, debian's developers <debian-devel@lists.debian.org>
- Subject: Re: Changing manpages (was Re: hwclock and time gazworks...)
- From: Thierry Laronde <thierry.laronde@polynum.com>
- Date: Tue, 1 Feb 2000 09:32:46 +0100
- Message-id: <20000201093246.A582@polynum.com>
- In-reply-to: <200001312212.WAA30583@linda.lfix.co.uk>; from Oliver Elphick on Mon, Jan 31, 2000 at 10:12:54PM +0000
- References: <20000129121923.B18128@godzillah.rivendell.sol> <20000129235433.B547@polynum.com> <20000130084127.B513@godzillah.rivendell.sol> <20000130123357.A385@polynum.com> <20000130120709.A15753@godzillah.rivendell.sol> <20000130164026.A1286@polynum.com> <20000130140024.A16092@godzillah.rivendell.sol> <20000131175351.B1613@polynum.com> <thierry.laronde@polynum.com> <200001312212.WAA30583@linda.lfix.co.uk>
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: