Hi,
Harald Dunkel wrote on Wed, Sep 24, 2014 at 12:22:32PM +0200:
> I completely agree, but that seems 2b the case for _all_ files in
> /etc/examples (or for config files in general).
Not really all. Take dhcpd.conf for example. Here the complexity
comes from the fact that a wide variety of statements is supported,
that most are unneeded for a typical simple configuration, but that
it's all the same easy to forget one of the things that are needed
for a typical simple configuration. Besides, even a simple
configuration usually requires more than one level of nesting.
So the example file can show: This is what you probably don't
want to forget, and how to assemble it all.
Another example that is not useless is the new httpd.conf.
Yet another example that is useful is sysctl.conf, even though
the reasons are different. It lists a selection of variables
more likely to need tweaking than others. No doubt, there are
more that already are useful, and maybe some could be made useful.
> As a user I love to find a config file in /etc briefly showing me
> the most important options, their default value (something that is
> clearly missing in pkg.conf(5))
Not true. If you read the options list in the manual carefully,
the defaults of all five options are obvious:
fullwidth = no
loglevel = 1
installpath (unset)
nochecksum = no
ntogo = no
> and some explaining words. One file to read and edit.
That's exactly why it's such a bad idea. Users don't read the
manual, miss important stuff, and hurt themselves.
> Its a starting point. The man page isn't.
That's not true. The pkg.conf(1) manual is a perfect example of
how to do it, let me cite:
The file /etc/pkg.conf contains system-wide options related to
package handling, as a list of `keyword=value' lines.
[...]
Currently defined options are as follows:
[... list ...]
Concise, crystal clear, the perfect starting point. And it all
fits on one screen (56 lines including headers and footers).
> Just imagine you had never configured dovecot before, and now you
> have to create a config file from scratch, using just the man pages.
Well, dovecot definitely is the prime example of how *NOT* to do
it. It's the ultimate mess. The example file is so long that you
almost certainly don't want to read it completely, at least 95% of
it is completely irrelevant for almost all users. And they
gratuitiouly change large portions of it for each minor release,
so keeping that file in sync is a nightmare. While i update all
daemons as often as i can, dovecot is an exception. I update that
one as rarely as i can, for the very reason of not wasting my time
on that horrible mess of a config file that doesn't even deserve
the name "config file", it should rather be called "misformatted
documentation".
> BTW, when I installed 5.6 for the first time, I thought that I made an
> installation error, since the usual /etc/sysctl.conf and /etc/ntp.conf
> and the others were gone. Its unexpected for openBSD that these files
> are hidden somewhere else. Of course I understand the intention to
> avoid upgrade problems.
Yeah, that's the downside of improvement, it's unavoidable that
it causes surprise at first. But as long as things get simpler,
not more complicated, that's acceptable, i think.
Yours,
Ingo
