Re: Mention /etc/examples/ in those config files manpages + FILES short description
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:
>
hi.
i've gotten round to committing something which lists the example file
in FILES, along with a standard wording (Example configuration file.) i
did not attempt to describe the contents - that is not the point of
FILES.
feel free to cvs up and make sure i didn;t miss anything, or otherwise
mess up.
thanks for your mail!
jmc
> 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=15878367111=1=2
> [2] https://marc.info/?t=15812050392=1=2
> [3]
> https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21=1.22=h
>
> Thanks,
>
> --
> clematis (0xA2C87EDB507B4C53)
> Index: dhcpd.conf.5
> ===
> RCS file: /cvs/src/usr.sbin/dhcpd/dhcpd.conf.5,v
> retrieving revision 1.25
> diff -u -p -r1.25 dhcpd.conf.5
> --- dhcpd.conf.5 17 Apr 2020 06:24:28 - 1.25
> +++ dhcpd.conf.5 30 Apr 2020 16:13:27 -
> @@ -885,6 +885,15 @@ the DHCP ACK or NAK reply sent to the cl
> DHCP option statements are documented in the
> .Xr dhcp-options 5
> manual page.
> +.Sh FILES
> +.Bl -tag -width /etc/examples/dhcpd.conf -compact
> +.It Pa /etc/dhcpd.conf
> +Default
> +.Xr dhcpd 8
> +configuration file.
> +.It Pa /etc/examples/dhcpd.conf
> +Example configuration file.
> +.El
> .Sh SEE ALSO
> .Xr dhcp-options 5 ,
> .Xr dhcpd.leases 5 ,
> Index: httpd.conf.5
> ===
> RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> retrieving revision 1.110
> diff -u -p -r1.110 httpd.conf.5
> --- httpd.conf.5 23 Apr 2020 21:10:53 - 1.110
> +++ httpd.conf.5 30 Apr 2020 16:16:57 -
> @@ -796,6 +796,15 @@ server "example.com" {
> }
> }
> .Ed
> +.Sh FILES
> +.Bl -tag -width /etc/examples/httpd.conf -compact
> +.It Pa /etc/httpd.conf
> +Default
> +.Xr httpd 8
> +configuration file.
> +.It Pa /etc/examples/httpd.conf
> +Example configuration file.
> +.El
> .Sh SEE ALSO
> .Xr htpasswd 1 ,
> .Xr patterns 7 ,
> Index: iked.conf.5
> ===
> RCS file: /cvs/src/sbin/iked/iked.conf.5,v
> retrieving revision 1.67
> diff -u -p -r1.67 iked.conf.5
> --- iked.conf.5 28 Apr 2020 15:18:52 - 1.67
> +++ iked.conf.5 30 Apr 2020 16:14:17 -
> @@ -937,7 +937,11 @@ backwards compatibility.
> .Sh FILES
> .Bl -tag -width /etc/examples/iked.conf -compact
> .It Pa /etc/iked.conf
> +Default
> +.Xr iked 8
> +configuration file.
> .It Pa /etc/examples/iked.conf
> +Example configuration file for EAP or pre-shared key authentification.
> .El
> .Sh EXAMPLES
> The first example is intended for a server with clients connecting to
> Index: inetd.8
> ===
> RCS file: /cvs/src/usr.sbin/inetd/inetd.8,v
> retrieving revision 1.42
> diff -u -p -r1.42 inetd.8
> --- inetd.8 10 Feb 2020 13:18:21 - 1.42
> +++ inetd.8 30 Apr 2020 16:19:39 -
> @@ -361,7 +361,11 @@ only IPv6 traffic will be routed to the
> .Sh FILES
> .Bl -tag -width /etc/examples/inetd.conf -compact
> .It Pa /etc/inetd.conf
> +Default
> +.Xr inetd 8
> +configuration file.
> .It Pa /etc/examples/inetd.conf
> +Example configuration file.
> .El
> .Sh SEE ALSO
> .Xr comsat 8 ,
> Index: ipsec.conf.5
> ===
> RCS file: /cvs/src/sbin/ipsecctl/ipsec.conf.5,v
> retrieving revision 1.159
> diff -u -p -r1.159 ipsec.conf.5
> --- ipsec.conf.5 16 Feb 2020 11:28:28 - 1.159
> +++ ipsec.conf.5 30 Apr 2020 16:15:24 -
> @@ -994,7 +994,13 @@ and
> .Sh FILES
> .Bl -tag -width /etc/examples/ipsec.conf -compact
> .It Pa
Re: Mention /etc/examples/ in those config files manpages + FILES short description
gwes wrote: > On 5/1/20 9:13 AM, Theo de Raadt wrote: > > 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. > > > > > [snip] > Perhaps something like: > Index: root.mail > === > RCS file: /cvs/src/etc/root/root.mail,v > retrieving revision 1.137 > diff -u -p -u -r1.137 root.mail > --- root.mail 5 Apr 2020 16:15:39 - 1.137 > +++ root.mail 3 May 2020 01:37:20 - > @@ -40,6 +40,8 @@ has been centralized in the file /etc/rc > edit the file /etc/rc. The files /etc/rc.securelevel and > /etc/rc.local exist > for this purpose; the first is run before the system has gone into secure > mode; the second is run afterwards (if in doubt, add your tools to > rc.local). > +The directory /etc/examples contains some sample configuration files > +which you can modify to suit your configuration. Is it really that important?? Aren't there 100 other details which could be described at this point, and ... then people get tired, and don't read anything? I think this is chasing a fad.
Re: Mention /etc/examples/ in those config files manpages + FILES short description
On 5/1/20 9:13 AM, Theo de Raadt wrote: 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. [snip] Perhaps something like: Index: root.mail === RCS file: /cvs/src/etc/root/root.mail,v retrieving revision 1.137 diff -u -p -u -r1.137 root.mail --- root.mail 5 Apr 2020 16:15:39 - 1.137 +++ root.mail 3 May 2020 01:37:20 - @@ -40,6 +40,8 @@ has been centralized in the file /etc/rc edit the file /etc/rc. The files /etc/rc.securelevel and /etc/rc.local exist for this purpose; the first is run before the system has gone into secure mode; the second is run afterwards (if in doubt, add your tools to rc.local). +The directory /etc/examples contains some sample configuration files +which you can modify to suit your configuration. Please refer to our web pages for any other questions you might have. https://www.OpenBSD.org Geoff Steckel
Re: Mention /etc/examples/ in those config files manpages + FILES short description
Jason McIntyre wrote: > On Fri, May 01, 2020 at 07:13:53AM -0600, Theo de Raadt wrote: > > 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. > > > > yes, that's perfectly true. but it's also a bit about consistency - why > would we add entries to some pages and not others? i suppose we do it or > not. Well there is one reason to not add it to every page: trying to control verbosity, and avoiding pages all becoming the same without individual personal touches.
Re: Mention /etc/examples/ in those config files manpages + FILES short description
On Fri, May 01, 2020 at 07:13:53AM -0600, Theo de Raadt wrote: > 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. > yes, that's perfectly true. but it's also a bit about consistency - why would we add entries to some pages and not others? i suppose we do it or not. jmc
Re: Mention /etc/examples/ in those config files manpages + FILES short description
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 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=15878367111=1=2 > > > [2] https://marc.info/?t=15812050392=1=2 > > > [3] > > > https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21=1.22=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=158125647814751=2 > (at least it was my understanding) > A lot was previously discussed in the dhclient.conf thread: > https://marc.info/?t=15811267801=1=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=158121091805006=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) >
Re: Mention /etc/examples/ in those config files manpages + FILES short description
Hi, clematis wrote on Fri, May 01, 2020 at 11:37:51AM +0200: > On Fri, May 01, 2020 at 06:52:27AM +0100, Jason McIntyre wrote: >> i don;t understand your reference to 28 out of 41 files. i cannot see >> where we added any expanded FILES entries. can you provide a summary of >> these inconsistencies, please? > There's 41 example files in /etc/examples/. 28 of them are listed in the > FILES section of their respective manpage with a short description. > The patches I've sent were to do the same for the remaining 13 files. > Either adding them when there were missing and/or adding the short > description. I think there is value in having complete FILES sections, listing all the files (with full paths if possible) directly related to the topic of a manual page because it both allows to see at first glance with files are used by the command and where exactly they located (as a non-trivial example, consider /etc/mail/smtpd.conf), because it potentially support "apropos Pa=" searches, and because it costs almost nothing: exactly one line per file when it's obvious what the file is all about. Whether the file needs an explanation of more than one line should be decided on a case by case basis. Very often, it does not. In conclusion, i do support adding the missing FILES sections dhcpd.conf(5) and httpd.conf(5). I don't care about changes like these either way: .It Pa /etc/man.conf +Default +.Xr man 1 +configuration file. .It Pa /etc/examples/man.conf +Example configuration file. I think both contain exactly the same information. If jmc@ thinks either having or not having the trivial one-line explanation is better for some reason, or that there is value in doing this aspect consistently, i'm happy to have this made consistent. If jmc@ thinks both forms are equally legitimate and there is no value in consistency in this respect, that's fine with me, too. There is certainly ample historical precedent for both forms. I don't really like this particular change: .It Pa /etc/examples/man.conf +Example configuration file illustrating possible search path ordering and +output options. The paramount design goal of the new man.conf(5) file format was to keep it as simple as possible and i think that goal was reached: there are now exactly two directives, both with an extremely simple syntax, and the complete formatted manual page fits into 80 lines. I consider it detrimental to restate what the file is for in the FILES section because it is obvious and already concisely said right above, so it just adds gratuitious verbiage. Explanations longer than one line should be reserved for special, non-trivial cases where they really matter. Such cases do occasionally exist, in particular when a config file format is exceptionally complicated, the file can do many different things, among them quite unusual ones, it is not obvious which aspects are those that it is most commonly used for, and/or the examples file deliberately focusses on a specific aspect for specific reasons and it is non-trivial which aspect that is or why. I think Jason should just go ahead with whatever parts of the diff he likes and discard the rest. He is usually very good at deciding issues of style and consistency. Yours, Ingo
Re: Mention /etc/examples/ in those config files manpages + FILES short description
On Fri, May 01, 2020 at 06:52:27AM +0100, Jason McIntyre wrote: > i don;t understand your reference to 28 out of 41 files. i cannot see > where we added any expanded FILES entries. can you provide a summary of > these inconsistencies, please? There's 41 example files in /etc/examples/. 28 of them are listed in the FILES section of their respective manpage with a short description. The patches I've sent were to do the same for the remaining 13 files. Either adding them when there were missing and/or adding the short description. -- clematis (0xA2C87EDB507B4C53)
Re: Mention /etc/examples/ in those config files manpages + FILES short description
I do think newcomers will tend to miss examples, even if /etc/examples is somewhat documented elsewhere. Also, queries to mandocdb will probably benefit... say "what commands do have an example configuration file ?" kind of what you should be able to ask with advanced queries.
Re: Mention /etc/examples/ in those config files manpages + FILES short description
Jason McIntyre wrote: > > Just so this now applies to all /etc/examples/ files' manpages > > "consistently". > > > > Cheers, > > -- > > clematis (0xA2C87EDB507B4C53) > > > > ok, so i see from those threads that i was against expanding FILES, but > happy for entries for the corresponding files. > > so i'm broadly against your diff. ingo seems to have more or less > completely updated our FILES. the only question is about whether we need > FILES section in dhcpd.conf and httpd.conf. > > i don;t understand your reference to 28 out of 41 files. i cannot see > where we added any expanded FILES entries. can you provide a summary of > these inconsistencies, please? I've never been sure if examples needs to always be documented. And something about a hobgoblin.
Re: Mention /etc/examples/ in those config files manpages + FILES short description
On Fri, May 01, 2020 at 12:22:26AM +0200, clematis 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=15878367111=1=2 > > > [2] https://marc.info/?t=15812050392=1=2 > > > [3] > > > https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21=1.22=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=158125647814751=2 > (at least it was my understanding) > A lot was previously discussed in the dhclient.conf thread: > https://marc.info/?t=15811267801=1=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=158121091805006=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) > ok, so i see from those threads that i was against expanding FILES, but happy for entries for the corresponding files. so i'm broadly against your diff. ingo seems to have more or less completely updated our FILES. the only question is about whether we need FILES section in dhcpd.conf and httpd.conf. i don;t understand your reference to 28 out of 41 files. i cannot see where we added any expanded FILES entries. can you provide a summary of these inconsistencies, please? jmc
Re: Mention /etc/examples/ in those config files manpages + FILES short description
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=15878367111=1=2 > > [2] https://marc.info/?t=15812050392=1=2 > > [3] > > https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21=1.22=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=158125647814751=2 (at least it was my understanding) A lot was previously discussed in the dhclient.conf thread: https://marc.info/?t=15811267801=1=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=158121091805006=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)
Re: Mention /etc/examples/ in those config files manpages + FILES short description
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=15878367111=1=2
> [2] https://marc.info/?t=15812050392=1=2
> [3]
> https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.sbin/acme-client/acme-client.conf.5.diff?r1=1.21=1.22=h
>
> Thanks,
>
> --
> clematis (0xA2C87EDB507B4C53)
hi.
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.
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.
jmc
> Index: dhcpd.conf.5
> ===
> RCS file: /cvs/src/usr.sbin/dhcpd/dhcpd.conf.5,v
> retrieving revision 1.25
> diff -u -p -r1.25 dhcpd.conf.5
> --- dhcpd.conf.5 17 Apr 2020 06:24:28 - 1.25
> +++ dhcpd.conf.5 30 Apr 2020 16:13:27 -
> @@ -885,6 +885,15 @@ the DHCP ACK or NAK reply sent to the cl
> DHCP option statements are documented in the
> .Xr dhcp-options 5
> manual page.
> +.Sh FILES
> +.Bl -tag -width /etc/examples/dhcpd.conf -compact
> +.It Pa /etc/dhcpd.conf
> +Default
> +.Xr dhcpd 8
> +configuration file.
> +.It Pa /etc/examples/dhcpd.conf
> +Example configuration file.
> +.El
> .Sh SEE ALSO
> .Xr dhcp-options 5 ,
> .Xr dhcpd.leases 5 ,
> Index: httpd.conf.5
> ===
> RCS file: /cvs/src/usr.sbin/httpd/httpd.conf.5,v
> retrieving revision 1.110
> diff -u -p -r1.110 httpd.conf.5
> --- httpd.conf.5 23 Apr 2020 21:10:53 - 1.110
> +++ httpd.conf.5 30 Apr 2020 16:16:57 -
> @@ -796,6 +796,15 @@ server "example.com" {
> }
> }
> .Ed
> +.Sh FILES
> +.Bl -tag -width /etc/examples/httpd.conf -compact
> +.It Pa /etc/httpd.conf
> +Default
> +.Xr httpd 8
> +configuration file.
> +.It Pa /etc/examples/httpd.conf
> +Example configuration file.
> +.El
> .Sh SEE ALSO
> .Xr htpasswd 1 ,
> .Xr patterns 7 ,
> Index: iked.conf.5
> ===
> RCS file: /cvs/src/sbin/iked/iked.conf.5,v
> retrieving revision 1.67
> diff -u -p -r1.67 iked.conf.5
> --- iked.conf.5 28 Apr 2020 15:18:52 - 1.67
> +++ iked.conf.5 30 Apr 2020 16:14:17 -
> @@ -937,7 +937,11 @@ backwards compatibility.
> .Sh FILES
> .Bl -tag -width /etc/examples/iked.conf -compact
> .It Pa /etc/iked.conf
> +Default
> +.Xr iked 8
> +configuration file.
> .It Pa /etc/examples/iked.conf
> +Example configuration file for EAP or pre-shared key authentification.
> .El
> .Sh EXAMPLES
> The first example is intended for a server with clients connecting to
> Index: inetd.8
> ===
> RCS file: /cvs/src/usr.sbin/inetd/inetd.8,v
> retrieving revision 1.42
> diff -u -p -r1.42 inetd.8
> --- inetd.8 10 Feb 2020 13:18:21 - 1.42
> +++ inetd.8 30 Apr 2020 16:19:39 -
> @@ -361,7 +361,11 @@ only IPv6 traffic will be routed to the
> .Sh FILES
> .Bl -tag -width /etc/examples/inetd.conf -compact
> .It Pa /etc/inetd.conf
> +Default
> +.Xr inetd 8
> +configuration file.
> .It Pa /etc/examples/inetd.conf
> +Example configuration file.
> .El
> .Sh SEE ALSO
> .Xr comsat 8 ,
> Index: ipsec.conf.5
> ===
> RCS file: /cvs/src/sbin/ipsecctl/ipsec.conf.5,v
> retrieving revision 1.159
> diff -u -p -r1.159 ipsec.conf.5
> --- ipsec.conf.5 16 Feb 2020 11:28:28 -
