On Sat, Sep 18, 1999 at 11:36:06AM +0100, Oliver Elphick wrote:
> Nicol s Lichtmaier wrote:
> > Having a manpage is a nicer and cleaner solution IMO. There's a whole man
> >section (5) for that.
> >
> > A sysadmin could delete the comments; he could choose to not upgrade the
> >file (when asked by dpkg) and have incorrect docs.. but the manpage will be
> >there.
>
> Conceded. I second this proposal.
I'd second it too, but we really ought to see the exact wording or diff
against the Policy document. I suggest adding this to the section 4.7.:
All configuration files created or used by packages need to have a
manual page in the fifth section of the manual, which would contain
usage instructions and description of the exact syntax used within the
configuration file.
If there is an option of adding comments to the configuration file
itself, you should add comments which would describe basic usage, or at
least point user to an appropriate help reference, e.g. a manual page.
If there are several smaller configuration files, you are allowed to
explain their purpose in another related manual page, which comes with
the same or depending package.
This wording would *require* having the manual page, and only *encourage*
adding comments. Am I right?
--
enJoy -*/\*- don't even try to pronounce my first name
