On 08/02 17:33, Ingo Schwarze wrote: I have no idea what your target audience is and what (if any) your mission staement is. Assumptions are being made pertaining to the end user skill set and this is already a slippery slope.
> 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 >
