Re: rc.d.8: fix daemon_* markup
On 2023/03/06 14:16, Klemens Nanni wrote: > 06.03.2023 13:49, Raf Czlonka пишет: > > To quote sthen@[0]: > > > > But that isn't, it is talking about _execdir, > > _flags, etc where you need to replace the > > > > [0] https://marc.info/?l=openbsd-tech=165364961710717=2 > > I find this dance in rc.d.8 not helpful: > .It Ar daemon Ns _flags > > daemon_flags and foo_flags control the same value in the end. > daemon_flags is set in rc.d scripts themselves and foo_flags can > overrule those from rc.conf.local. > > So why not mark them up as daemon_flags in rc.d.8 so that they become > more discoverable via tags? > > rc.d.8 still expains all the fuzz around replaing "daemon" with "foo" > in detail, right in the same ENVIRONMENT section around the list. > > When I read rc.d(8) to write my own script, I am looking for > daemon_flags and not foo_flags, so that makes sense and seems to have > priority over foo_flags wrt. markup since this is rc.d(8). This ENVIRONMENT section of rc.d(8) is *specifically* talking about lines added to rc.conf.local. Most readers are not writing their own scripts, and we have way too many users who say things like "I edited the rc.d(8) script to change the flags" who will run into problems at update time. I'd like to avoid any changes that reduce distinction between "foo_flags" in rc.conf(.local) and "daemon_flags" in rc.d/foo. > rc.conf.local(8) also explains the 'daemon vs. foo' dance, with the > weird markup, but there it is fine and not important, since it is not > the authorative source rc.d variables.
Re: rc.d.8: fix daemon_* markup
06.03.2023 13:49, Raf Czlonka пишет: > To quote sthen@[0]: > > But that isn't, it is talking about _execdir, > _flags, etc where you need to replace the > > [0] https://marc.info/?l=openbsd-tech=165364961710717=2 I find this dance in rc.d.8 not helpful: .It Ar daemon Ns _flags daemon_flags and foo_flags control the same value in the end. daemon_flags is set in rc.d scripts themselves and foo_flags can overrule those from rc.conf.local. So why not mark them up as daemon_flags in rc.d.8 so that they become more discoverable via tags? rc.d.8 still expains all the fuzz around replaing "daemon" with "foo" in detail, right in the same ENVIRONMENT section around the list. When I read rc.d(8) to write my own script, I am looking for daemon_flags and not foo_flags, so that makes sense and seems to have priority over foo_flags wrt. markup since this is rc.d(8). rc.conf.local(8) also explains the 'daemon vs. foo' dance, with the weird markup, but there it is fine and not important, since it is not the authorative source rc.d variables.
Re: rc.d.8: fix daemon_* markup
On Mon, Mar 06, 2023 at 01:28:59PM GMT, Klemens Nanni wrote: > I pointed out how rc.d(8) uses login.conf(5) via `daemon_class', so I linked > to https://man.openbsd.org/rc.d.8#daemon_class expecting it to be marked up. > > Add .Tg to make above link and ":t daemon_class" in `man rc.d' work. > > Mark up all `daemon_*' variables as single .Va so they get an automatic tag. > This also reads better and does not remove information, imho, as the text > right after the list explains everything. > (daemon_flags in rc.d/foo script vs. foo_flags in rc.conf.local) > > Feedback? OK? Hi Klemens, To quote sthen@[0]: But that isn't, it is talking about _execdir, _flags, etc where you need to replace the [0] https://marc.info/?l=openbsd-tech=165364961710717=2 Regards, Raf > Index: rc.d.8 > === > RCS file: /cvs/src/share/man/man8/rc.d.8,v > retrieving revision 1.40 > diff -u -p -r1.40 rc.d.8 > --- rc.d.82 Sep 2022 22:11:57 - 1.40 > +++ rc.d.86 Mar 2023 13:21:41 - > @@ -104,27 +104,27 @@ variables when starting a daemon. > The following can be overridden by site-specific values provided in > .Xr rc.conf.local 8 : > .Bl -tag -width daemon_timeout -offset indent > -.It Ar daemon Ns _execdir > +.It Va daemon_execdir > Run daemon from the specified directory. > -.It Ar daemon Ns _flags > +.It Va daemon_flags > Additional arguments to call the daemon with. > These will be appended to any mandatory arguments already contained in the > .Va daemon > variable defined in the control script. > If > -.Ar daemon Ns _flags > +.Va daemon_flags > is set to > .Dq NO , > it will prevent the daemon from starting even when listed in > .Va pkg_scripts . > -.It Ar daemon Ns _logger > +.It Va daemon_logger > Redirect standard output and error to > .Xr logger 1 > using the configured priority (e.g. "daemon.info"). > -.It Ar daemon Ns _rtable > +.It Va daemon_rtable > Routing table to run the daemon under, using > .Xr route 8 . > -.It Ar daemon Ns _timeout > +.It Va daemon_timeout > Maximum time in seconds to wait for the > .Cm start , > .Cm stop > @@ -137,7 +137,7 @@ This is only guaranteed with the default > and > .Ic rc_reload > functions. > -.It Ar daemon Ns _user > +.It Va daemon_user > User to run the daemon as, using > .Xr su 1 . > .El > @@ -159,6 +159,7 @@ flags), define the following in > Each script may define its own defaults, as explained in > .Xr rc.subr 8 . > .Pp > +.Tg daemon_class > .Va daemon_class > is a special read-only variable. > It is set to >
rc.d.8: fix daemon_* markup
I pointed out how rc.d(8) uses login.conf(5) via `daemon_class', so I linked to https://man.openbsd.org/rc.d.8#daemon_class expecting it to be marked up. Add .Tg to make above link and ":t daemon_class" in `man rc.d' work. Mark up all `daemon_*' variables as single .Va so they get an automatic tag. This also reads better and does not remove information, imho, as the text right after the list explains everything. (daemon_flags in rc.d/foo script vs. foo_flags in rc.conf.local) Feedback? OK? Index: rc.d.8 === RCS file: /cvs/src/share/man/man8/rc.d.8,v retrieving revision 1.40 diff -u -p -r1.40 rc.d.8 --- rc.d.8 2 Sep 2022 22:11:57 - 1.40 +++ rc.d.8 6 Mar 2023 13:21:41 - @@ -104,27 +104,27 @@ variables when starting a daemon. The following can be overridden by site-specific values provided in .Xr rc.conf.local 8 : .Bl -tag -width daemon_timeout -offset indent -.It Ar daemon Ns _execdir +.It Va daemon_execdir Run daemon from the specified directory. -.It Ar daemon Ns _flags +.It Va daemon_flags Additional arguments to call the daemon with. These will be appended to any mandatory arguments already contained in the .Va daemon variable defined in the control script. If -.Ar daemon Ns _flags +.Va daemon_flags is set to .Dq NO , it will prevent the daemon from starting even when listed in .Va pkg_scripts . -.It Ar daemon Ns _logger +.It Va daemon_logger Redirect standard output and error to .Xr logger 1 using the configured priority (e.g. "daemon.info"). -.It Ar daemon Ns _rtable +.It Va daemon_rtable Routing table to run the daemon under, using .Xr route 8 . -.It Ar daemon Ns _timeout +.It Va daemon_timeout Maximum time in seconds to wait for the .Cm start , .Cm stop @@ -137,7 +137,7 @@ This is only guaranteed with the default and .Ic rc_reload functions. -.It Ar daemon Ns _user +.It Va daemon_user User to run the daemon as, using .Xr su 1 . .El @@ -159,6 +159,7 @@ flags), define the following in Each script may define its own defaults, as explained in .Xr rc.subr 8 . .Pp +.Tg daemon_class .Va daemon_class is a special read-only variable. It is set to
