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