Bug#45406: PROPOSAL] Config files must have manpages

[Nicolás Lichtmaier <nick@debian.org>]

> >   > 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?

 Sounds fine. Thanks!

 Should be add `intended for direct user modification'? Are there
configfiles that are `internal' and should be allowed to remain
undocumented?