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

["Oliver Elphick" <olly@lfix.co.uk>]

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.  Part
of the service we provide as distributors is to fix things for the
Debian distribution and _document_ what has been changed.  That should
include changing the manpages as necessary.  Filenames should be the
correct Debian filenames; any changes in operation should be 
described too.

man is the first place a user goes for information, and he wants it to
be correct.  He doesn't want to scrabble around in the bowels of
/usr/share/doc to find addenda and errata that modify what man (or
info, for that matter) tells him.  If he wants to find what the upstream
author wrote, he can download the source package, which includes the
original source.  

If you feel it is important to retain a description of how the program
used to work before Debian changed it, put that description in 
/usr/share/doc and make sure it is labelled clearly, so that no-one
will think it describes the installed package.


-- 
Oliver Elphick                                Oliver.Elphick@lfix.co.uk
Isle of Wight                              http://www.lfix.co.uk/oliver
               PGP key from public servers; key ID 32B8FAA1
                 ========================================
     "My son, if sinners entice thee, consent thou not."    
                            Proverbs 1:10