openrc-run.8: Add "Default stop/start" section and table.

[flexibeast]

Obsoletes #771; initial pass.

i've created the table under an Ss ('Subsection') macro, rather than under an Sh macro, which is intended to be used for a higher-level standard manual section headings, as described in mdoc(7)'s "MANUAL STRUCTURE" section (neither groff_man(7) nor groff_man_style(7) provide such a description). In this case, i've added the subsection heading "Default start/stop" within "DESCRIPTION", which has necessitated using another Ss macro to clearly separate it from a following subsection, "Ambient process capabilities".

To test the output with groff, do:

$ groff -mdoc -t -Tutf8 ./openrc-run.8 | less -L

(The -T option specifies the output format; other possible options include ascii and latin1.)

To test the output with mandoc, do:

$ mandoc -a ./openrc-run.8

The contents of the table are based on:

• my original PR;
• the example content provided by @N-R-K, which might not have been intended to be taken as literal content, only as example filler;
• references to supervise-daemon in the existing option list.

i'm not sure what to consult to find all the appropriate content for the supervise-daemon and s6 columns. (For context, i'm the porter of the HTML documentation for various skaware projects to mdoc(7) - s6-man-pages, s6-rc-man-pages, etc. - although i'm currently in the process of transferring maintainership of these ports to someone else.)

In terms of formatting:

• i've simply requested 'centering' of text in data cells, via the third line after the TS macro (i.e. the one ending in a full stop, .). To test out other possibilities, refer to tbl(7)'s "Layout" section.
• i initially tried using the tbl(7) doublebox / doubleframe options to create a more substantial outline for the edges of the table, but the output was clearly unsatisfactory. (Add doubleframe to the start of the first line after the TS macro to see what i mean.)

.... i think that's everything for now!

[N-R-K]

Formatting looks good and renders well using man on my local setup. Some issues with the content tho:

[N-R-K]

I'm fairly certain supervise-daemon supports all the logging vars. You can see them referenced in the default start function too:

openrc/sh/supervise-daemon.sh

Lines 37 to 40 in ef3f90a

	${output_log+--stdout} ${output_log} \
	${error_log+--stderr} $error_log \
	${output_logger:+--stdout-logger \"$output_logger\"} \
	${error_logger:+--stderr-logger \"$error_logger\"} \

I suppose you missed it? Same with some other vars like umask.

[flexibeast]

This is what i meant by "i'm not sure what to consult to find all the appropriate content for the supervise-daemon and s6 columns." :-) Now that i know i should look at the sources for supervise-daemon.sh and (presumably) s6.sh, i'll try to update the PR accordingly. (i'm not actually familiar with any of these three scripts or using them; the only reason i ended up opening #771 was due to the discussion following https://bugs.gentoo.org/948143#c1; that bug came about as a result of me trying to help someone on the gentoo-user list.)

[navi-desu]

i'm not sure what to consult to find all the appropriate content for the supervise-daemon and s6 columns

currently that boils down to looking into sh/{s6,supervise-daemon}.sh and looking at what variables they expand on $supervisor_$function

(oh sorry, i missed the other reply ~w~)

[flexibeast]

Thank you both. :-) PR updated.

i hope that i've got the information in the "start-stop-daemon" and "supervise-daemon" columns correct. i actually found it quite challenging to try to do so methodically, due to the calls to start-stop-daemon (in ssd_start and ssd_stop) and supervise-daemon (in supervise_start and supervise_stop) requiring positional arguments that result in the referenced variables not being listed alphabetically. However, my ongoing health issues significantly impact my ability to focus, so despite my checks, it's possible some errors have crept in.

Re. the s6 column: after scanning the source of s6.sh, i felt unable to make an adequate assessment of the variables available to users without doing a full analysis of the code, which i don't feel i'm in a place to do due to the above-mentioned focus issues. i made a guess about timeout_down, and wondered if name should be included; but at any rate, if i could be provided with a list of what should go in the s6 column, that would be much appreciated. :-)

[N-R-K]

Looks aright. Except _background and _progress, those I'm pretty sure are internal variable and not meant to be used/set by the user.

[N-R-K]

if i could be provided with a list of what should go in the s6 column, that would be much appreciated.

@skarnet might be able to help with this part.

[skarnet]

@N-R-K @flexibeast The list of user-accessible variables is maintained, as it should, in the documentation 😉

It should be accurate. Please keep the page up-to-date if you make changes.

[flexibeast]

@N-R-K, @skarnet: Thank you both. :-)

N-R-K: i've removed those internal variables from the list.

skarnet: i've updated the PR based on the document you pointed to; could you please confirm i've understood it correctly?

[skarnet]

🤬 I had to log into a machine that has groff installed in order to, you know, read the thing. 🤬 You of all people should know better than to make me review an mdoc file 😝

The table looks... good, albeit a little confusing for the uninitiated? But the way s6.sh operates makes it kind of inaccurate to say that stopsig and timeout-kill are "used by the stop function". It is only fully true for timeout-down.

What happens with stopsig and timeout-kill is that at start time, when the service directory is automatically created, these variables are used to fill it, and then at stop time, a command is issued that uses the configuration stored in the service directory. So these variables impact stop time, but they are only read at start time and kinda cached in the service directory, so if the user changes a value in the service file between starting and stopping, the new value won't be taken into account on the next stop.

I don't think that's very important though, people should not modify live service files anyway. I think you can keep the mention of stopsig and timeout-kill as is.

However, reading that man page, I saw a much bigger issue. In the DESCRIPTION section, all the listed s6_* variables are obsolete and should be removed. The current s6.sh does not use them at all, it sticks to strictly OpenRC variables and the goal is ultimately feature parity with supervise-daemon. So that means s6_service_path, s6_svwait_options_start, s6_force_kill and s6_service_timeout_stop all have to go.

Then looking at the table again:

• timeout-down and timeout-kill are listed as s6-specific but ISTR @navi-desu intended to implement them for supervise-daemon, so in the end they will be generic OpenRC variables. The table is correct for now.
• command_args is used by both start-stop-daemon and supervise-daemon, and command_args_foreground is used by start-stop-daemon. I only supported them in s6 for feature parity, but the semantic is unclear and they duplicate command functionality, so I would be glad to see them go. There should be only one command variable, holding a command line, there is no reason to separate the command name from its arguments. But I stuck with historical usage and will follow whatever @navi-desu decides.

[flexibeast]

🤬 I had to log into a machine that has groff installed in order to, you know, read the thing. 🤬 You of all people should know better than to make me review an mdoc file 😝

Sorry, i don't follow .... If your daily driver doesn't have groff installed, doesn't it use mandoc, an invocation for which i provided upthread? i'm guessing you might use Adélie or Alpine, which - to the best of my knowledge - both use mandoc, but if you don't use either of those, which (i presume *n*x-ish) OS are you using that doesn't use groff or mandoc?

More generally, i'm afraid i'm getting overwhelmed by all this. What started out as what i intended to be small drive-by doc improvement by me in #771, with no implied ongoing commitment from me, keeps becoming more and more complicated and requiring more and more work from me. This is particularly problematic for me given that, on top of my pre-existing disabilities (including ME/CFS), plus the severe and continuing chronic pain which started last year (and which has caused me to need to hand over maintenance of all my *-man-pages projects, in order to significantly reduce my ICT commitments), right now i'm also having to deal with a bout of RSV.

So at this point, if this PR can't be simply finalised with only a few small changes in the near future, i'm going to have to abandon it; i simply don't have the bandwidth for all this.

[skarnet]

Sorry, I did not mean to pile on you. Please don't take my comments for more serious than they are.

My daily driver, inasmuch as I have one, is a system built from scratch, and I have neither groff nor mandoc nor anything that can format man pages, because I don't use those. I do have access to plenty of accounts where these tools exist, though, so I could log into one of them and read the formatted text.

I played up my hate for groff/mandoc because it's a meme at this point.

You asked me to proofread the changes, so I did, and since it had taken me some investment, I wanted to do it well while I was at it. That is why, when I noticed other things in the man page that do not accurately document the current behaviour of supervisor=s6, I reported it. This is not a criticism of your efforts or anything of the kind.

If you don't want to keep working on this PR, it's all good. Your changes look good to me; the PR can be merged, and we can modify the man page to better reflect the current state of supervisor=s6 later, without your involvement. You were just unlucky touching something that needs more improvement than you initially signed up for.

Please get all the rest you need and take care of your health first and foremost.

[navi-desu]

timeout-down and timeout-kill are listed as s6-specific but ISTR @navi-desu intended to implement them for supervise-daemon, so in the end they will be generic OpenRC variables. The table is correct for now.

iirc yeah, supervise-daemon has retry which is a weird format that goes $sigterm/$timeout-term/$sigkill/$timeout-kill, in truth it allows N signal/timer combos, but the whole thing is so jank

command_args is used by both start-stop-daemon and supervise-daemon, and command_args_foreground is used by start-stop-daemon. I only supported them in s6 for feature parity, but the semantic is unclear and they duplicate command functionality, so I would be glad to see them go. There should be only one command variable, holding a command line, there is no reason to separate the command name from its arguments. But I stuck with historical usage and will follow whatever @navi-desu decides.

command and command_args are separate with start-stop-daemon because it needed to support --startas, aka, "use this custom argv[0] please!"

supervise-daemon does not support such flag, but it kept the command_args variable for porting reasons

we can push for sunsetting command_args though, specially in the future, if we can manage to get arrays in posix sh

either way, this PR looks good to me asw, so, thanks for the work!