Hi, i think i said it before: i hate /etc/examples/ and think that the directory ought to be mostly empty. With the exception of rare cases like bgpd(8), where you have to provide a lot of information before you can start it in any meaningful way, i consider a deamon ill-designed if the configuration is so complicated that a file in /etc/examples/ serves any purpose. Daemons should have a reasonable default configuration, such that a configuration file is not needed for typical usage, and if people add a configuration file, they ought to get away with very few lines. By the way, acme-client(1) is an example where i was happy to recently see people work into just that direction.
Providing example configuration files is an idiotic concept because if you copy them into /etc/, you no longer easily see what the defaults are, what generic recommendations are, and what was changed locally. It should be made easy to write short configuration files from scratch such that they contain absolutely nothing except local changes. For daemons designed as described, if they have some complicated configuration commands for special purposes, a few typical examples of these commands can be shown in the EXAMPLES section of the manual page. Note that in the past, there was no consensus about the above, so i'm not suggesting that we move all the examples into the manual pages. I'm only saying *trivial* files in /etc/examples/ should be deleted and the content, if any, moved to the manual pages. Some files will no doubt remain, and there is nothing wrong with that. Jason McIntyre wrote on Sat, Feb 08, 2020 at 07:22:06AM +0000: > if we do reference these config files from the man pages, i guess that > should be correctly done from a FILES section, since EXAMPLES is really > showing how to use the tool, rather than how to configure it. it is a > fine line though. > > i wouldn;t be against adding to FILES - it'd be very brief, make sense, > and provide the reminder being asked for. I like that very much, yes. In general, if there is a file closely related to the content of the manual page, mention it below FILES. That also seems like a good idea for files below /etc/examples/. Yours, Ingo
