Hi, i strongly dislike what you are doing here. Not just because of one particular line, but in general.
clematis wrote on Sat, Apr 25, 2020 at 07:41:40PM +0200: > Looking arround in /etc/examples/ I felt like some of those files > aren't as "verbose" as others. 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. The program doas(1) is very well-designed. It is very simple and very easy to use yet quite powerful (even though it intentionally does not have all bells and whistles that some might need in special situations). Let's not obscure that good design by making the /etc/examples/ file excessively large and cumbersome. > Please let me know if there is a prefered way. Keep it as short as possible, that's the most important point IMHO. For a program as well designed as doas(1), the primary benefit of the file is to signal to somebody who looks into the directory: Look, this is a program you can configure with a file in /etc/. In addition to that, maybe it could also demonstrate: this is how a cmment looks like, and this is how the basic syntactic patterns look like. Repeating the content of the manual page would be detrimental. > And there's probably a middle ground that could be find as well. > I don't know if anyone has a strong opinion or recommandations. I dislike the idea of a middle ground in this context. > So if that makes sense for you, please find attached a patch for > examples/doas.conf adding the main examples from doas.conf(5) and > bsd.port.mk(5). Please, no. Yours, Ingo
