Hi Stuart, Theo, I didn't really though about it from a "potentially risky command" perspective. I understand - that makes sense.
On Sat, Apr 25, 2020 at 08:43:22PM +0200, Ingo Schwarze wrote: > clematis wrote on Sat, Apr 25, 2020 at 07:41:40PM +0200: > > The shorter the better. > > Yes, there are exceptions, when something is really complicated > and configuring it properly requires a lot of legwork, like for > bgpd.conf(5). Or if something is hard to explain in abstract > terms and easy to show with an example, like acme-challenge in > httpd.conf(5). > > > For example doas.conf doas.conf(5) contains more EXAMPLES > > than /etc/examples/doas.conf > > Which is good. The manual page is the ideal place for documentation. Hi Ingo, Agree with manual pages being the ideal place for documentation. And to leverage examples files for those cases, as you said, which are just easier to explain with an example. > > Please let me know if there is a prefered way. > > Keep it as short as possible, that's the most important point IMHO. I agree. But then based on your feedback I wonder if there's even any value of an example file which gives not much more than an already well documented manpage? And again, please don't get me wrong, I don't mean to play devil's advocate but do we even need an /etc/examples/doas.conf? (for all the very valid reasons you've mentioned as well, clarity, existing documentation etc...) I would be tempted to put a few others in the same boat: /etc/examples/exports: just points to the manpage. exports(5) is crystal clear and has examples. Only gives an extra warning that could be in the manpage. /etc/examples/rc.*: Nothing more than rc(8). There's not much example that could be given anyway. rc.shutdown(8) is also crystal clear (doesn't actually list /etc/examples in FILES btw) Plus it's mentioned in the welcome mail.root and afterboot(8). Sounds like plenty already. > I dislike the idea of a middle ground in this context. You're probably right - either it's something complex than can be clarified with examples or people just refer to the manpage... Thanks for the feedback - appreciated. -- clematis (0x7e96fd2400fe7b59)
