-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi Ingo,
On 09/24/14 11:29, Ingo Schwarze wrote: > Hi, > > Harald Dunkel wrote on Wed, Sep 24, 2014 at 07:14:21AM +0200: > >> This is something that could be added to /etc/examples. See the attachment >> suggesting a first version. > > I hate that. Examples should not duplicate manual pages. That merely causes > double maintenance effort for developers. Let's not make documentation > maintenance harder on ourselves. > > It also doesn't make things easier for users, quite to the contrary. Chances > are both copies of the documentation will eventually get out of sync, and > then it's overtly confusing. And even if we manage to prevent explicit > contradictions from creeping in, there will be some stuff documented > only in one of the places, some stuff only in the other place. So now users > have to look at *two* places where formerly it was sufficient to look only at > one. They now have to read the double amount of text for almost the same > information - and they have to stay very attententive because > either copy might contain the bit of information they are searching for, > buried among boring duplication. > I completely agree, but that seems 2b the case for _all_ files in /etc/examples (or for config files in general). 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)) and some explaining words. One file to read and edit. Its a starting point. The man page isn't. Just imagine you had never configured dovecot before, and now you have to create a config file from scratch, using just the man pages. 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. Regards Harri iQEcBAEBCAAGBQJUIptoAAoJEAqeKp5m04HLmDgIAIHW7Mv2LTVD0IW5vyQSwa8n e+7UvKcAqu3VIL28Z1zJMp0GyI4IbnqnnNECuBcyWIRBzHQXddL3r9kykfdjKEvH 723JIN1rlNl1DXd0yNt+2bX+6++9WScIdRmExEhH4w7IUKfOZqnDAHoY/DMUhe1/ g9+CcKh2yz5PtH500Qw6B0nImPvzNPUxZxqxtiLPWtoNnSrDACKPLXV6A/wtjDAQ +RJAByqrCbA+CknbzXLosa/46NyOfOwKBr92CmBYKGNkGQDg8LJgdbqcBhJOxje3 MQGfIxQXWQDMnIOnKFJ6ZcWji2n+s4flG8wZXSa2lHgMHxDLZAnK5nC9USPlrwM= =hr41 -----END PGP SIGNATURE-----
