Bug#45406: PROPOSAL] Config files must have manpages

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

> > No I don't think that it's good idea. There's no point adding a bunch of
> > undocumented symlink to all missing man page for configuration file. :-)
> > 
> > I agree that having a man page for the configuration file is good but I
> > don't want to force Debian developers to write man page for each
> > configuration file that is not documented upstream. Furthermore some
> > configuration files are well documented but in a file in /usr/share/doc
> > and so on. There's no need to force the existence of a man page.
> 
>      Many upstream manpages include a section on configuration files.
> In such cases, it would be foolish to require the Debian maintainer to
> produce a stand-alone manpage for the configuration file.  IMO, it
> would be preferable to encourage maintainers to add configure file
> information to the executable's manpage.  The manpages are for
> information about the executables, not for configuration files.
> 
>      Many default configuration files are self documented by their
> comments.  The earlier objections to this that a sysadmin might delete
> the comments are not valid.  The sysadmin could delete all
> documentation, including manpages, if he was foolish enough to do so.
> It is not our business to protect a sysadmin from himself.

 There's a line of what can be "legally" done. If you cross that line and
remove files that came with the packages and which are supposed to be there
then you know that you are on your own. Config files, on the other hand, are
intended to be edited. And a user that replaces one etc/file with some other
someone gave him over IRC shouldn't be left with no docs.

 Self documented config files are a hack. A hack designed for the wild UNIX
world where men are men.. =). In the civilized world of Debian we can do
something better. For instance, one problem with self documented config
files is what happens when the docs are updated? It causes the user to
recheck the file (users of squid know this, e.g.) (I'm not proposing
removing these docs, I'm just saying that they are not the best of the
best).