Hi, Theo de Raadt wrote on Sat, Feb 08, 2020 at 04:39:42PM -0700:
> For complicated configurations, the text could explain the reason the > example is valuable -- for instance > > .It Pa /etc/examples/bgpd.conf > Example configuration file demonstrating IBGP mesh, multiple transits, > RPKI filtering, and other best practices. I like that. It gives the reader an idea of how interesting the file might be without even opening it. We have to be careful to not make the comment too long, or FILES might look bad, but your text still looks reasonable to me. I think it's sufficient to have this wording in bgpd.conf(5); in bgpd(8), mentioning the existence of the example seems fair, but the exact contents seem more tangential there. I guess network admins running that beast will have to look at bgpd.conf(5) anyway. I applied Jason's recommendation to remove the "do not edit"; probably he is right that it isn't required. Regarding benno@'s comment: /etc/exanmples/ is already mentioned in hier(7) and yet some people missed it. I wouldn't blame them. Also, you don't really need to look into /etc/examples/ for all programs; if we point to it from where it matters, that's even better usability. Still, i think it would *also* make sense to mention the directory in a FILES section in help(1), and optionally also in afterboot(8), though the latter seems less relevant. I'm not feeling strongly about that, and one doesn't exclude the other. Pointers are cheap and can be added whereever they help, only not in such an amount that they would become a distraction. Updated patch: still OK? Ingo Index: bgpd.8 =================================================================== RCS file: /cvs/src/usr.sbin/bgpd/bgpd.8,v retrieving revision 1.62 diff -u -p -r1.62 bgpd.8 --- bgpd.8 10 Nov 2019 20:51:53 -0000 1.62 +++ bgpd.8 8 Feb 2020 23:52:00 -0000 @@ -205,11 +205,13 @@ Only check the configuration file for va Produce more verbose output. .El .Sh FILES -.Bl -tag -width "/var/run/bgpd.sockXXX" -compact +.Bl -tag -width "/etc/examples/bgpd.conf" -compact .It Pa /etc/bgpd.conf default .Nm configuration file +.It Pa /etc/examples/bgpd.conf +example configuration file .It Pa /var/run/bgpd.sock default .Nm Index: bgpd.conf.5 =================================================================== RCS file: /cvs/src/usr.sbin/bgpd/bgpd.conf.5,v retrieving revision 1.199 diff -u -p -r1.199 bgpd.conf.5 --- bgpd.conf.5 25 Jan 2020 12:07:28 -0000 1.199 +++ bgpd.conf.5 8 Feb 2020 23:52:00 -0000 @@ -1883,10 +1883,13 @@ For prefixes with equally long paths, th is selected. .El .Sh FILES -.Bl -tag -width "/etc/bgpd.conf" -compact +.Bl -tag -width "/etc/examples/bgpd.conf" -compact .It Pa /etc/bgpd.conf .Xr bgpd 8 configuration file +.It Pa /etc/examples/bgpd.conf +example configuration file demonstrating IBGP mesh, multiple transits, +RPKI filtering, and other best practices .El .Sh SEE ALSO .Xr strftime 3 ,
