I think there's a bit of drama going on here. Once a person uses one example in the examples directory, they will become aware of the directory and see it has other files. And possibly use them in the future.
It is not clear to me that example discovery has to come via each and every manual page. clematis <clema...@insiberia.net> wrote: > On Thu, Apr 30, 2020 at 07:20:04PM +0100, Jason McIntyre wrote: > > On Thu, Apr 30, 2020 at 07:13:16PM +0200, clematis wrote: > > > Hello, > > > > > > Following the previous thread about /etc/examples/doas.conf [1] , > > > I've noticed those example files aren't always listed in their > > > respective manpage or without a description. > > > This has been discussed here recently for bgpd.conf [2]. > > > Also noticed updates for some of them like acme-client.conf [3]. > > > > > > Taking into account those email threads I would suggest the changes > > > below: > > > > > > Adding FILES section with description for: > > > - /usr.sbin/dhcpd/dhcpd.conf.5 > > > - /usr.sbin/httpd/httpd.conf.5 > > > > > > Adding short description for: > > > - /sbin/iked/iked.conf.5 > > > - /usr.sbin/inetd/inetd.8 > > > - /sbin/ipsecctl/ipsec.conf.5 > > > - /usr.bin/mandoc/man.conf.5 > > > - /usr.sbin/sasyncd/sasyncd.conf.5 > > > - /share/man/man5/sysctl.conf.5 > > > - /usr.sbin/vmd/vm.conf.5 > > > - /share/man/man5/wsconsctl.conf.5 > > > > > > Other changes: > > > - /usr.sbin/mrouted/mrouted.8 > > > +.Nm mrouted.conf + short description > > > - /usr.sbin/rbootd/rbootd.8 > > > +.Nm rbootd.conf + minor description update > > > - /share/man/man8/rc.shutdown.8 > > > adding example file + description > > > > > > The others examples file' man pages looked OK and consistent with > > > this approach. > > > > > > Diff attached to this email. Please let me know if adjustments have to > > > be made. > > > > > > [1] https://marc.info/?t=158783671100001&r=1&w=2 > > > [2] https://marc.info/?t=158120503900002&r=1&w=2 > > > [3] > > > https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21&r2=1.22&f=h > > > > > > Thanks, > > > > > > -- > > > clematis (0xA2C87EDB507B4C53) > > > > hi. > > Hi Jason, > > > i'm broadly in favour. having said that, i have a horrible feeling this > > has come up before and there was some reason not to. > > This might be the thread I was also referring to, in regards to > bgpd.conf. In the end, there was kind of an agreement to move into that > direction: https://marc.info/?l=openbsd-tech&m=158125647814751&w=2 > (at least it was my understanding) > A lot was previously discussed in the dhclient.conf thread: > https://marc.info/?t=158112678000001&r=1&w=2 > > > supposing that no one has such a reason, i'd be happy to fix this. > > however one thing bugs me - i don;t think the description in FILES > > should attempt to outline the contents. it will just go out of date and > > even if it doesn't, it's not the place. too wordy. i'd prefer to just > > use a single, consistent, description. like "Example configuration > > file." or somesuch. > > Well, I see value doing it for the complex ones. I tend to agree that it > might not be so valuable for the basic ones. Hence why only a few were > providing more than a basic: "Example configuration file." > That's also based on how "good" is the example file itself. > It was my understanding that this was a direction some already have > considered: https://marc.info/?l=openbsd-tech&m=158121091805006&w=2 > > I understand there's different opinions on that matter. And ultimately > it's your call. But because this was done for 28 out of 41 files it felt > right to carry on with the same approach for the remaining 13 files. > Just so this now applies to all /etc/examples/ files' manpages > "consistently". > > Cheers, > -- > clematis (0xA2C87EDB507B4C53) >
