supervision - discussion about system services, daemon supervision, init, runlevel management, and tools such as s6 and runit
 help / color / mirror / Atom feed
* [request for review] Port of s6 documentation to mdoc(7)
@ 2020-08-30  8:30 Alexis
  2020-08-30  9:10 ` eric vidal
  2020-08-30 10:01 ` Laurent Bercot
  0 siblings, 2 replies; 30+ messages in thread
From: Alexis @ 2020-08-30  8:30 UTC (permalink / raw)
  To: supervision


Hi all,

i recently started using 66 instead of runit on Void - thanks to 
@Obarun, @mobinmob and @teldra for their work and help!

Consequently, and further to 
https://www.mail-archive.com/supervision@list.skarnet.org/msg02278.html 
:

> if people like man pages, they should have man pages, so it's 
> been a
> few years that I have appealed to the community for this ... I 
> want
> s6 to be accessible, but I figure that if people really wanted 
> man
> pages, they'd write man pages

i've spent the last couple of weeks porting the s6 documentation 
to mdoc(7) format:

  https://github.com/flexibeast/s6-man-pages

since i really want man pages, and much prefer them to HTML for 
system-level software. :-)

i don't consider the current state of the repo to be 'ready' in a 
general sense, but i do feel it's mostly done, and certainly 
amenable to review. i think this might be a good time to give 
myself a short break from working on it, so i can then come back 
and do a review pass with fresher eyes.

The porting has been done manually, with no automation involved; 
this has allowed me to use semantic markup as much as possible, 
which of course also facilitates searching for content with 
`apropos(1)`.

Several things to note:

* i've changed page layouts to fit mdoc(7) conventions.

* During the porting process, i developed ideas about what might 
  be the best way to do things, so documentation ported earlier 
  might not follow the same style as the documentation ported more 
  recently. This is something i hope to check in my review pass.

* There are currently no cross-references to the execline suite or 
  skalibs. However, i'm willing to port that documentation as 
  well, together with the s6-rc documentation.

* Inline links to things such as djb's software are not yet 
  included. The `Lk` macro allows one to supply link text as well 
  as the URL, but the resulting output would require changes to 
  the text to make it read satisfactorily. Regardless, i can add 
  the relevant links in "SEE ALSO" sections.

* i've corrected a number of typos and grammatical issues, and 
  discovered what i believe might be couple of errors:

  * s6-softlimit: The "Options" section refers to "-r allmem" 
  rather than "-r res".

  * s6-ftrig-listen: The "Options" section says: "By default, 
  s6-ftrig-listen1 waits indefinitely for a matching series of 
  events." Given the context, i presume this should be 
  "s6-ftrig-listen"?

That said, although i've tried to be careful, i might have 
introduced new errors, or made mistakes in my choice of macros, so 
proofreading would be appreciated. :-)


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-30  8:30 [request for review] Port of s6 documentation to mdoc(7) Alexis
@ 2020-08-30  9:10 ` eric vidal
  2020-08-31  6:56   ` Alexis
  2020-08-30 10:01 ` Laurent Bercot
  1 sibling, 1 reply; 30+ messages in thread
From: eric vidal @ 2020-08-30  9:10 UTC (permalink / raw)
  To: supervision

On Sun, 30 Aug 2020 18:30:16 +1000
Alexis <flexibeast@gmail.com> wrote:

> 
> Hi all,
> 
> i recently started using 66 instead of runit on Void - thanks to 
> @Obarun, @mobinmob and @teldra for their work and help!

You're welcome. Thank at you to use 66.

> Consequently, and further to 
> https://www.mail-archive.com/supervision@list.skarnet.org/msg02278.html 
> :
> 
> > if people like man pages, they should have man pages, so it's 
> > been a
> > few years that I have appealed to the community for this ... I 
> > want
> > s6 to be accessible, but I figure that if people really wanted 
> > man
> > pages, they'd write man pages
> 
> i've spent the last couple of weeks porting the s6 documentation 
> to mdoc(7) format:
> 
>   https://github.com/flexibeast/s6-man-pages
> 
> since i really want man pages, and much prefer them to HTML for 
> system-level software. :-)
> 
> i don't consider the current state of the repo to be 'ready' in a 
> general sense, but i do feel it's mostly done, and certainly 
> amenable to review. i think this might be a good time to give 
> myself a short break from working on it, so i can then come back 
> and do a review pass with fresher eyes.
> 
> The porting has been done manually, with no automation involved; 
> this has allowed me to use semantic markup as much as possible, 
> which of course also facilitates searching for content with 
> `apropos(1)`.
> 
> Several things to note:
> 
> * i've changed page layouts to fit mdoc(7) conventions.
> 
> * During the porting process, i developed ideas about what might 
>   be the best way to do things, so documentation ported earlier 
>   might not follow the same style as the documentation ported more 
>   recently. This is something i hope to check in my review pass.
> 
> * There are currently no cross-references to the execline suite or 
>   skalibs. However, i'm willing to port that documentation as 
>   well, together with the s6-rc documentation.
> 
> * Inline links to things such as djb's software are not yet 
>   included. The `Lk` macro allows one to supply link text as well 
>   as the URL, but the resulting output would require changes to 
>   the text to make it read satisfactorily. Regardless, i can add 
>   the relevant links in "SEE ALSO" sections.
> 
> * i've corrected a number of typos and grammatical issues, and 
>   discovered what i believe might be couple of errors:
> 
>   * s6-softlimit: The "Options" section refers to "-r allmem" 
>   rather than "-r res".
> 
>   * s6-ftrig-listen: The "Options" section says: "By default, 
>   s6-ftrig-listen1 waits indefinitely for a matching series of 
>   events." Given the context, i presume this should be 
>   "s6-ftrig-listen"?
> 
> That said, although i've tried to be careful, i might have 
> introduced new errors, or made mistakes in my choice of macros, so 
> proofreading would be appreciated. :-)
> 
> 
> Alexis.

This is really a hard job to do. Many thanks to make it. A lot of user will appreciate it.
Well, i'm not really good at English, so my help will not be usefull about grammatical issues. But i will do some publicizes about your work that be visible by user.

-- 
eric vidal <eric@obarun.org>

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-30  8:30 [request for review] Port of s6 documentation to mdoc(7) Alexis
  2020-08-30  9:10 ` eric vidal
@ 2020-08-30 10:01 ` Laurent Bercot
  2020-08-31  7:01   ` Alexis
                     ` (2 more replies)
  1 sibling, 3 replies; 30+ messages in thread
From: Laurent Bercot @ 2020-08-30 10:01 UTC (permalink / raw)
  To: supervision

>i've spent the last couple of weeks porting the s6 documentation to mdoc(7) format:
>
>https://github.com/flexibeast/s6-man-pages

  Excellent, thank you. There is a lot of talk (especially on the #s6
IRC channel, but occasionally on the mailing-list too) about people
wanting to have s6 man pages, but very rarely people wanting to actually
do the *work*. This is clearly the most advanced conversion ever
performed, well done!

  Would you be willing to add a small Makefile that by default invokes
the mandoc commands to produce the formatted man pages, and with an
install target that installs the source to $(MANDIR), by default
/usr/share/man ? I would then be able to review them. Thanks :)
(AS you're aware if you've been here a while, I don't read mdoc source,
and I will. not. learn. it.)

  Related question: would you be willing to maintain that repository
for when I make changes to the s6 documentation? Changes should be few
and far between, except for fixes and new feature additions (which I
don't think there will be much of). If so, I would gladly add a link to
that repository in the official s6 home page, for people who, like you,
prefer man pages.


>* There are currently no cross-references to the execline suite or  skalibs. However, i'm willing to port that documentation as  well, together with the s6-rc documentation.

  That would be totally awesome. However, I'd hold off on s6-rc for now,
because I'm in the process of exploring a possible redesign (for better
integration of features that distributions want before packaging and
using s6-rc), so it's not improbable that all the documentation gets
rewritten in a not-too-distant future.


>* Inline links to things such as djb's software are not yet  included. The `Lk` macro allows one to supply link text as well  as the URL, but the resulting output would require changes to  the text to make it read satisfactorily. Regardless, i can add  the relevant links in "SEE ALSO" sections.

  What kind of changes to the text? if it's just the text of the link,
such as changing the name of a package to the full URL of the package,
then please go ahead and do what is needed. But relevant links in
SEE ALSO works too.


>* i've corrected a number of typos and grammatical issues, and  discovered what i believe might be couple of errors:

  If there are other typos or grammatical errors you've noticed, please
send them to me (maybe privately in order not to spam the list) and I'll
fix them. If the fixes need more explanation and interactive dialogue,
hop on #s6 some time during the week to discuss them. :)


>  * s6-softlimit: The "Options" section refers to "-r allmem"  rather than "-r res".
>
>  * s6-ftrig-listen: The "Options" section says: "By default,  s6-ftrig-listen1 waits indefinitely for a matching series of  events." Given the context, i presume this should be  "s6-ftrig-listen"?

  Fixed in the latest git head, thanks!

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-30  9:10 ` eric vidal
@ 2020-08-31  6:56   ` Alexis
  0 siblings, 0 replies; 30+ messages in thread
From: Alexis @ 2020-08-31  6:56 UTC (permalink / raw)
  To: supervision


eric vidal <eric@obarun.org> writes:

> You're welcome. Thank at you to use 66.

i enjoy using it - trees are excellent. :-)

> This is really a hard job to do. Many thanks to make it.

You're welcome!

> But i will do some publicizes about your work that be visible by 
> user.

Thank you, much appreciated. :-)


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-30 10:01 ` Laurent Bercot
@ 2020-08-31  7:01   ` Alexis
  2020-08-31 11:04     ` Laurent Bercot
  2020-08-31 14:29   ` Guillermo
  2020-08-31 16:08   ` [request for review] Port of s6 documentation to mdoc(7) J. Lewis Muir
  2 siblings, 1 reply; 30+ messages in thread
From: Alexis @ 2020-08-31  7:01 UTC (permalink / raw)
  To: supervision


Laurent Bercot <ska-supervision@skarnet.org> writes:

> This is clearly the most advanced conversion ever
> performed, well done!

Thank you!

> Would you be willing to add a small Makefile that by default 
> invokes
> the mandoc commands to produce the formatted man pages, and with 
> an
> install target that installs the source to $(MANDIR), by default
> /usr/share/man ? I would then be able to review them. Thanks :)

Certainly. i'll do that once i've completed a linting pass.

> (AS you're aware if you've been here a while, I don't read mdoc 
> source,
> and I will. not. learn. it.)

Heh, fair enough. :-)

> Would you be willing to maintain that repository
> for when I make changes to the s6 documentation? Changes should 
> be few
> and far between, except for fixes and new feature additions 
> (which I
> don't think there will be much of). If so, I would gladly add a 
> link to
> that repository in the official s6 home page, for people who, 
> like you,
> prefer man pages.

Sure, i'd be happy to reflect any changes.

> I'd hold off on s6-rc for now,
> because I'm in the process of exploring a possible redesign (for 
> better
> integration of features that distributions want before packaging 
> and
> using s6-rc), so it's not improbable that all the documentation 
> gets
> rewritten in a not-too-distant future.

Ah, okay - thanks for the heads-up.

> What kind of changes to the text? if it's just the text of the 
> link,
> such as changing the name of a package to the full URL of the 
> package,
> then please go ahead and do what is needed. But relevant links 
> in
> SEE ALSO works too.

Now that i think about it some more, maybe i could simply put the 
link in parentheses? For example, with:

    a CDB file cdbfile then exits 0.

where "CDB file" is a link to the relevant Wikipedia page, the 
mdoc would produce output like:

    a CDB file (http://en.wikipedia.org/wiki/Cdb_(software)) 
    cdbfile then exits 0.

Similarly,

    lines with a TAI64N timestamp and a space.

would become:

    lines with a TAI64N timestamp 
    (http://skarnet.org/software/skalibs/libstddjb/tai.html#timestamp) 
    and a space.

At any rate, i think it might be a good idea for such links to be 
mentioned in "SEE ALSO" regardless.

> If there are other typos or grammatical errors you've noticed, 
> please
> send them to me (maybe privately in order not to spam the list) 
> and I'll
> fix them. If the fixes need more explanation and interactive 
> dialogue,
> hop on #s6 some time during the week to discuss them. :)

*nod* i'll try to put together an email with the relevant 
 information, and start hanging out on #s6. :-) i'm usually on 
 Freenode,  in #voidlinux in particular, but not necessarily 
 active at the same time as others - i'm in Melbourne.au.

>  Fixed in the latest git head, thanks!

:-D


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31  7:01   ` Alexis
@ 2020-08-31 11:04     ` Laurent Bercot
  0 siblings, 0 replies; 30+ messages in thread
From: Laurent Bercot @ 2020-08-31 11:04 UTC (permalink / raw)
  To: supervision

>Certainly. i'll do that once i've completed a linting pass.

  Excellent.


>Sure, i'd be happy to reflect any changes.

  And the people rejoiced and celebrated, because they would soon,
finally, have s6 man pages.


>Ah, okay - thanks for the heads-up.

  Also a heads-up for people who are currently using s6-rc, including
in elaborate distribution-integrated setups: don't worry, no matter
how things shape up, the current version of s6-rc is going to be
supported for a looooong time.


>Now that i think about it some more, maybe i could simply put the link in parentheses? For example, with:
>
>    a CDB file cdbfile then exits 0.
>
>where "CDB file" is a link to the relevant Wikipedia page, the mdoc would produce output like:
>
>    a CDB file (http://en.wikipedia.org/wiki/Cdb_(software))    cdbfile then exits 0.

  I think that solely depends on the number of such links. If there are
just a few, it's fine. If there are a lot of links in a page, it would
make reading pretty unwieldy. Because I think there are a few pages with
too many links, maybe it would be best, for consistency, to just use
footnotes?

< a CDB file[1] cdbfile then exits 0.
<
< (...)
<
< SEE ALSO
<
< [1]: http://en.wikipedia.org/wiki/Cdb_(software)

  Maybe mdoc even has a mechanism for footnotes? I don't know.


>*nod* i'll try to put together an email with the relevant information, and start hanging out on #s6. :-) i'm usually on Freenode,  in #voidlinux in particular, but not necessarily active at the same time as others - i'm in Melbourne.au.

  We don't care much about timezones. You can find people to interact 
with
at almost any time of the day, and if not, we generally answer as soon 
as
we're online. ;)

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-30 10:01 ` Laurent Bercot
  2020-08-31  7:01   ` Alexis
@ 2020-08-31 14:29   ` Guillermo
  2020-09-01 10:00     ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Laurent Bercot
  2020-08-31 16:08   ` [request for review] Port of s6 documentation to mdoc(7) J. Lewis Muir
  2 siblings, 1 reply; 30+ messages in thread
From: Guillermo @ 2020-08-31 14:29 UTC (permalink / raw)
  To: Supervision

Hello,

El dom., 30 ago. 2020 a las 7:01, Laurent Bercot escribió:
>
>   That would be totally awesome. However, I'd hold off on s6-rc for now,
> because I'm in the process of exploring a possible redesign (for better
> integration of features that distributions want before packaging and
> using s6-rc), so it's not improbable that all the documentation gets
> rewritten in a not-too-distant future.

I have only seen one new feature committed to the Git repository so
far. Is it too early to ask what are you planning to change?

Thanks,
G.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-30 10:01 ` Laurent Bercot
  2020-08-31  7:01   ` Alexis
  2020-08-31 14:29   ` Guillermo
@ 2020-08-31 16:08   ` J. Lewis Muir
  2020-08-31 17:45     ` Jason Lenz
  2020-08-31 19:36     ` Laurent Bercot
  2 siblings, 2 replies; 30+ messages in thread
From: J. Lewis Muir @ 2020-08-31 16:08 UTC (permalink / raw)
  To: Laurent Bercot; +Cc: supervision

On 08/30, Laurent Bercot wrote:
> > i've spent the last couple of weeks porting the s6 documentation to mdoc(7) format:
> > 
> > https://github.com/flexibeast/s6-man-pages
> 
>  Excellent, thank you. There is a lot of talk (especially on the #s6
> IRC channel, but occasionally on the mailing-list too) about people
> wanting to have s6 man pages, but very rarely people wanting to actually
> do the *work*. This is clearly the most advanced conversion ever
> performed, well done!
> 
>  Would you be willing to add a small Makefile that by default invokes
> the mandoc commands to produce the formatted man pages, and with an
> install target that installs the source to $(MANDIR), by default
> /usr/share/man ? I would then be able to review them. Thanks :)
> (AS you're aware if you've been here a while, I don't read mdoc source,
> and I will. not. learn. it.)
> 
>  Related question: would you be willing to maintain that repository
> for when I make changes to the s6 documentation? Changes should be few
> and far between, except for fixes and new feature additions (which I
> don't think there will be much of). If so, I would gladly add a link to
> that repository in the official s6 home page, for people who, like you,
> prefer man pages.

I don't want to rain on anyone's parade, and I certainly would like to
see s6 man pages, but it seems like such a waste of effort to maintain
two sets of documentation.  Laurent, isn't there a source format that
you'd be OK with that could be used to generate mdoc?

Have you considered docbook2mdoc?

  https://mandoc.bsd.lv/docbook2mdoc/

(I haven't used it myself; I'm just aware of its existence.)  I think
the existing s6 documentation is HTML, right?  So, DocBook is not too
far from that, and docbook2mdoc is a stand-alone ISO C utility with no
external dependencies that, barring any significant missing features,
would be able to generate the man pages from DocBook source.

Of course, you'd also have to convert the existing HTML documentation
into DocBook and then generate the mdoc and HTML from that.  I would
understand concern over adding a dependency on a potentially heavy
DocBook toolchain in order to generate the HTML.  One possible way
around this, though, would be to generate the mdoc from the DocBook
using docbook2mdoc, and then generate the HTML from the mdoc using
mandoc.  With this scheme, there would be no dependency on a heavy
DocBook toolchain.

I know the documentation has come up on the list before, so I don't want
to rehash that.  If I'm saying nothing new, then no need to discuss
further.

Lewis

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31 16:08   ` [request for review] Port of s6 documentation to mdoc(7) J. Lewis Muir
@ 2020-08-31 17:45     ` Jason Lenz
  2020-08-31 19:14       ` J. Lewis Muir
  2020-08-31 19:36     ` Laurent Bercot
  1 sibling, 1 reply; 30+ messages in thread
From: Jason Lenz @ 2020-08-31 17:45 UTC (permalink / raw)
  To: J. Lewis Muir, Laurent Bercot; +Cc: supervision

On 8/31/20 11:08 AM, J. Lewis Muir wrote:
> On 08/30, Laurent Bercot wrote:
>>> i've spent the last couple of weeks porting the s6 documentation to mdoc(7) format:
>>>
>>> https://github.com/flexibeast/s6-man-pages
>>   Excellent, thank you. There is a lot of talk (especially on the #s6
>> IRC channel, but occasionally on the mailing-list too) about people
>> wanting to have s6 man pages, but very rarely people wanting to actually
>> do the *work*. This is clearly the most advanced conversion ever
>> performed, well done!
>>
>>   Would you be willing to add a small Makefile that by default invokes
>> the mandoc commands to produce the formatted man pages, and with an
>> install target that installs the source to $(MANDIR), by default
>> /usr/share/man ? I would then be able to review them. Thanks :)
>> (AS you're aware if you've been here a while, I don't read mdoc source,
>> and I will. not. learn. it.)
>>
>>   Related question: would you be willing to maintain that repository
>> for when I make changes to the s6 documentation? Changes should be few
>> and far between, except for fixes and new feature additions (which I
>> don't think there will be much of). If so, I would gladly add a link to
>> that repository in the official s6 home page, for people who, like you,
>> prefer man pages.
> I don't want to rain on anyone's parade, and I certainly would like to
> see s6 man pages, but it seems like such a waste of effort to maintain
> two sets of documentation.  Laurent, isn't there a source format that
> you'd be OK with that could be used to generate mdoc?
>
> Have you considered docbook2mdoc?
>
>    https://mandoc.bsd.lv/docbook2mdoc/
>
> (I haven't used it myself; I'm just aware of its existence.)  I think
> the existing s6 documentation is HTML, right?  So, DocBook is not too
> far from that, and docbook2mdoc is a stand-alone ISO C utility with no
> external dependencies that, barring any significant missing features,
> would be able to generate the man pages from DocBook source.
>
> Of course, you'd also have to convert the existing HTML documentation
> into DocBook and then generate the mdoc and HTML from that.  I would
> understand concern over adding a dependency on a potentially heavy
> DocBook toolchain in order to generate the HTML.  One possible way
> around this, though, would be to generate the mdoc from the DocBook
> using docbook2mdoc, and then generate the HTML from the mdoc using
> mandoc.  With this scheme, there would be no dependency on a heavy
> DocBook toolchain.
>
> I know the documentation has come up on the list before, so I don't want
> to rehash that.  If I'm saying nothing new, then no need to discuss
> further.
>
> Lewis
I'm just happy someone is creating manual pages, so I'm not going to 
"look a gift horse in the mouth". ;-)

With that said I believe Laurent mentioned in the past that he 
considered a suggestion from someone to use the scdoc utility (links 
below), as long as someone else did the initial work to port to that 
format?  It's a simplified markup format, so although much easier to 
read probably not as powerful as mdoc.

https://drewdevault.com/2018/05/13/scdoc.html

https://git.sr.ht/~sircmpwn/scdoc



^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31 17:45     ` Jason Lenz
@ 2020-08-31 19:14       ` J. Lewis Muir
  2020-08-31 20:51         ` Laurent Bercot
  0 siblings, 1 reply; 30+ messages in thread
From: J. Lewis Muir @ 2020-08-31 19:14 UTC (permalink / raw)
  To: Jason Lenz; +Cc: Laurent Bercot, supervision

On 08/31, Jason Lenz wrote:
> On 8/31/20 11:08 AM, J. Lewis Muir wrote:
> > On 08/30, Laurent Bercot wrote:
> > > > i've spent the last couple of weeks porting the s6 documentation to mdoc(7) format:
> > > > 
> > > > https://github.com/flexibeast/s6-man-pages
> > >   Excellent, thank you. There is a lot of talk (especially on the #s6
> > > IRC channel, but occasionally on the mailing-list too) about people
> > > wanting to have s6 man pages, but very rarely people wanting to actually
> > > do the *work*. This is clearly the most advanced conversion ever
> > > performed, well done!
> > > 
> > I don't want to rain on anyone's parade, and I certainly would like to
> > see s6 man pages, but it seems like such a waste of effort to maintain
> > two sets of documentation.  Laurent, isn't there a source format that
> > you'd be OK with that could be used to generate mdoc?
> > 
> > Have you considered docbook2mdoc?
> > 
> >    https://mandoc.bsd.lv/docbook2mdoc/
> 
> I'm just happy someone is creating manual pages, so I'm not going to "look a
> gift horse in the mouth". ;-)

Yes, and I certainly didn't intend to do that if you're suggesting that
I have, and that's what I was trying to communicate when I said

> > I don't want to rain on anyone's parade, and I certainly would like to
> > see s6 man pages

but at the same time, I thought I'd make one last plea, if you will,
before too much time is invested since, like I said, it felt like such
a waste.  I mean, if there were a source format that everyone could be
happy with, then Alexis could spend time on getting that working instead
of spending time on something that will require indefinite maintenance.
But if there is no such solution, and having two separately maintained
sets of documentation is the only way to get man pages, then yes, I
still would be very thankful for Alexis's work.

> With that said I believe Laurent mentioned in the past that he considered a
> suggestion from someone to use the scdoc utility (links below), as long as
> someone else did the initial work to port to that format?  It's a simplified
> markup format, so although much easier to read probably not as powerful as
> mdoc.
> 
> https://drewdevault.com/2018/05/13/scdoc.html
> 
> https://git.sr.ht/~sircmpwn/scdoc

I had forgotten about that; thanks for the reminder.  I don't have any
experience with scdoc either, but if Laurent is happy with it and it
could serve as the source documentation format from which HTML and man
pages could be generated, then it seems like a win to me.

Lewis

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31 16:08   ` [request for review] Port of s6 documentation to mdoc(7) J. Lewis Muir
  2020-08-31 17:45     ` Jason Lenz
@ 2020-08-31 19:36     ` Laurent Bercot
  2020-08-31 19:58       ` J. Lewis Muir
  1 sibling, 1 reply; 30+ messages in thread
From: Laurent Bercot @ 2020-08-31 19:36 UTC (permalink / raw)
  To: supervision


>Of course, you'd also have to convert the existing HTML documentation
>into DocBook and then generate the mdoc and HTML from that.  I would
>understand concern over adding a dependency on a potentially heavy
>DocBook toolchain in order to generate the HTML.  One possible way
>around this, though, would be to generate the mdoc from the DocBook
>using docbook2mdoc, and then generate the HTML from the mdoc using
>mandoc.

  Are you volunteering to do that work?

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31 19:36     ` Laurent Bercot
@ 2020-08-31 19:58       ` J. Lewis Muir
  0 siblings, 0 replies; 30+ messages in thread
From: J. Lewis Muir @ 2020-08-31 19:58 UTC (permalink / raw)
  To: Laurent Bercot; +Cc: supervision

On 08/31, Laurent Bercot wrote:
> 
> > Of course, you'd also have to convert the existing HTML documentation
> > into DocBook and then generate the mdoc and HTML from that.  I would
> > understand concern over adding a dependency on a potentially heavy
> > DocBook toolchain in order to generate the HTML.  One possible way
> > around this, though, would be to generate the mdoc from the DocBook
> > using docbook2mdoc, and then generate the HTML from the mdoc using
> > mandoc.
> 
>  Are you volunteering to do that work?

No, unfortunately, I don't have the time.  I was just suggesting the
idea to you and Alexis in case either one of you had not considered it.

Lewis

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31 19:14       ` J. Lewis Muir
@ 2020-08-31 20:51         ` Laurent Bercot
  2020-09-01  6:38           ` Casper Ti. Vector
       [not found]           ` <20200901063801.GA2158@caspervector>
  0 siblings, 2 replies; 30+ messages in thread
From: Laurent Bercot @ 2020-08-31 20:51 UTC (permalink / raw)
  To: supervision


  For the people who are not on #s6 and have missed the countless
resurgences of this discussion, here is my position regarding
documentation formats. I hope that by the end of this mail things are
quite clear for everyone and I won't need to talk about this again, 
ever.

  - Doc formats seem to be the #1 thing that's on people's minds, because
it's a subject that keeps showing up *all the time*. To me, this is
unfortunate; I wish people would spend more time on technical design
discussions and be more curious about the internals of my software, and
a bit less on surrounding things like how the documentation is written.

(Yes, Guillermo, I will answer your mail. You should really join #s6
if possible, because I talked about the plans for s6-rc there; and I
would also very much enjoy your precious willingness to talk software
details.)

  - Everyone always has a lot of ideas on how things should go and what
I should do.

  - Unfortunately, I have *zero* interest in doing those para-software
things. I am interested in writing software that does stuff, not in
spending my time learning a new rich text format and rewriting
documentation. The time I am willing to devote to free software is best
employed actually writing code, not doing things I hate. Writing doc is
enough of a chore as is; it needs to be as easy as possible for me,
without any additional hurdle getting in the way.

  - And that should really be no big deal. There is a whole community
interested in s6 documentation, and making man pages, etc., and who
always sounds very enthusiastic. So, it should be easy to find people
who are willing to invest some time and do the thing the community 
wants,
right?

  - For some reason, it turns out that it's not that easy. Somehow, the
people who always have a lot of ideas are nowhere to be found when I
try to delegate the work.

  - This pattern has been replicating for a long while now, and it has
made me quite jaded, to the point that I now lose patience very quickly
whenever documentation formats are mentioned, and I sometimes cannot 
help
answering with a jab at the end.

  - Alexis' contribution is, literally, one-of-a-kind: someone wanted a
thing to be done *and did it themself*. That is something I respect,
something that has a lot of value to me, and I want to make that work
useful.

  - Yes, it would be better to have One Single Source Of Truth, rather
than duplication of information. I totally agree on the principle.
However, as of now, the limiting factor is *not* the consistency checks
between two sets of documentation. It is the amount of human time that
is voluntarily dedicated to the task of providing said documentation.
Talking about the N+1 ways of getting One Source Of Truth and generating
several backend documentation formats accomplishes nothing. I know
about DocBook; by now, I know about every single freaking documentation
format and toolchain in existence, and about every single possible
workflow I could use. That does not change the fact that it would be
more burden placed on me, that I have no intention of taking.

- scdoc is, in a way, an exception: ddv and I had a long talk, the scdoc
format is simple enough, the toolchain is good quality, I have no
objection to writing new documentation in scdoc. (Emphasis on new;
existing doc will have to be converted by someone else than me. Or I
could be paid to do it.) The problem is that at the moment it does not
produce HTML, and post- processing the roff output produces horrible,
ugly HTML, so it's not an acceptable solution. So, for now, scdoc is not
usable for the purpose of a multi-format s6 documentation. But if it
grows a decent HTML engine, it will be.

  - What we have with Alexis' work is two sources of truth, that will
have to be kept in sync, but that's work they're willing to do - it's
the first thing I asked - and that will make the community happy, that
will improve on the current situation. If maintaining the set of man
pages in sync with the official documentation reveals itself to be
unsustainable, *then* will be the time to do something about it.

  - Unless, of course, someone comes up with the perfect solution (adding
a DocBook dependency is not a perfect solution, and neither is
generating HTML from mandoc), in which case, obviously, they would have
the time and willingness to do all the necessary work themself, and in
doing so, actually meaningfully contribute to the community instead of
only adding their drop to the useless sea of It's Easy You Just Have To
Do This, Just Saying In Case You Had Not Considered.

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-08-31 20:51         ` Laurent Bercot
@ 2020-09-01  6:38           ` Casper Ti. Vector
  2020-09-01  9:03             ` Alexis
       [not found]           ` <20200901063801.GA2158@caspervector>
  1 sibling, 1 reply; 30+ messages in thread
From: Casper Ti. Vector @ 2020-09-01  6:38 UTC (permalink / raw)
  To: supervision

On Mon, Aug 31, 2020 at 08:51:34PM +0000, Laurent Bercot wrote:
>  - Unless, of course, someone comes up with the perfect solution (adding
> a DocBook dependency is not a perfect solution, and neither is
> generating HTML from mandoc), in which case, obviously, they would have
> the time and willingness to do all the necessary work themself, and in
> doing so, actually meaningfully contribute to the community instead of
> only adding their drop to the useless sea of It's Easy You Just Have To
> Do This, Just Saying In Case You Had Not Considered.

Sorry if this adds to your boredom in this subject, but I wonder whether
you find the following acceptable:

* We negotiate a HTML schema your documentation can be written in, which
  is based on current documentation; existing HTML documentation will be
  converted to the schema, with minimised changes.  (The structuredness
  of HTML helps; now you also see why knowing some Lisp is beneficial :)

* I provide a Python script that validates the schema (and also helps
  to convert existing documentation) of your HTML documentation, and
  transforms it into an IR suitable for downstream conversion.  I am
  quite comfortable with writing code transformations, but it may take
  some time -- about 1 months in this case, since I have my daily job.

* Those who are fluent in roff-related formats (I *do* like manpages,
  but I cannot write them, at least for now) write a program that
  transforms the IR into one pre-chosen format (we do not like multiple
  standards differing from each other subtlely, right?).

This way, the changes to the current documentation will be minimised;
the downside is a soft dependency on Python, which is only necessary
when the amount of modification to the HTML is so big that you cannot
manually compute corresponding modification to the manpages.

-- 
My current OpenPGP key:
RSA4096/0x227E8CAAB7AA186C (expires: 2022.09.20)
7077 7781 B859 5166 AE07 0286 227E 8CAA B7AA 186C


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01  6:38           ` Casper Ti. Vector
@ 2020-09-01  9:03             ` Alexis
  2020-09-01  9:20               ` Casper Ti. Vector
  2020-09-01 20:13               ` Steve Litt
  0 siblings, 2 replies; 30+ messages in thread
From: Alexis @ 2020-09-01  9:03 UTC (permalink / raw)
  To: Casper Ti. Vector; +Cc: supervision


Casper Ti. Vector <caspervector@gmail.com> writes:

> * We negotiate a HTML schema your documentation can be written 
> in, which
>   is based on current documentation; existing HTML documentation 
>   will be
>   converted to the schema, with minimised changes.

On the basis of my current experiences, it would be No Small Task 
to convert the current, presentationally-based, HTML documentation 
to markup that's sufficiently semantic to enable it to be 
mechanically converted to mdoc/roff. i estimate i've so far spent 
at least 30 hours over the last couple of weeks adding the 
relevant semantic (and occasionally presentational) macros, as 
well as modifying the page structure to match mdoc conventions; 
and i'm still not finished. Myself, i'm not willing to repeat this 
task again, as i have other volunteer and life commitments.


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01  9:03             ` Alexis
@ 2020-09-01  9:20               ` Casper Ti. Vector
  2020-09-01 10:02                 ` Alexis
  2020-09-01 20:13               ` Steve Litt
  1 sibling, 1 reply; 30+ messages in thread
From: Casper Ti. Vector @ 2020-09-01  9:20 UTC (permalink / raw)
  To: supervision

On Tue, Sep 01, 2020 at 07:03:36PM +1000, Alexis wrote:
> On the basis of my current experiences, it would be No Small Task to convert
> the current, presentationally-based, HTML documentation to markup that's
> sufficiently semantic to enable it to be mechanically converted to
> mdoc/roff. i estimate i've so far spent at least 30 hours over the last
> couple of weeks adding the relevant semantic (and occasionally
> presentational) macros, as well as modifying the page structure to match
> mdoc conventions; and i'm still not finished. Myself, i'm not willing to
> repeat this task again, as i have other volunteer and life commitments.

May I request a diff (via PM) between your attempt and the current HTMLs?

-- 
My current OpenPGP key:
RSA4096/0x227E8CAAB7AA186C (expires: 2022.09.20)
7077 7781 B859 5166 AE07 0286 227E 8CAA B7AA 186C


^ permalink raw reply	[flat|nested] 30+ messages in thread

* possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7))
  2020-08-31 14:29   ` Guillermo
@ 2020-09-01 10:00     ` Laurent Bercot
  2020-09-01 19:24       ` possible s6-rc redesign mobinmob
  2020-09-01 23:14       ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Steve Litt
  0 siblings, 2 replies; 30+ messages in thread
From: Laurent Bercot @ 2020-09-01 10:00 UTC (permalink / raw)
  To: Supervision

>I have only seen one new feature committed to the Git repository so
>far. Is it too early to ask what are you planning to change?

  The new feature is orthogonal - or, rather, it will be used if I end
up *not* redesigning s6-rc.

  The trend with distributions is to make service managers reactive to
external events: typically NetworkManager and systemd-networkd because
the network is the primary source of dynamic events, but even local
events such as the ones produced by a device manager, or basically
anything sent by the kernel on the netlink, are getting integrated
into that model.

  s6-rc is, by essence, static: the set of services is known in advance,
and there is no reacting to external events - there is only the admin
starting and stopping services. This has advantages - a compile-time
analysis is possible, with early cycle detection, etc.; but the model
doesn't integrate well with modern distro needs. So, I've been thinking
about ways to add dynamic event management to s6-rc; and I've found
two options.

  Option 1 is to add dynamic event management *on top of* s6-rc. That
is my natural instinct; that is what I've always done with software,
that's what keeps the various parts of my software as clean and simple
as possible. Here, it would mean:
  - having a classic s6-rc database for "static" services
  - having an additional "dynamic" database for services that can be
triggered by external events. (The database is static in essence, but
I call it "dynamic" because it would host the services that can be
started dynamically.)
  - having a s6-rc-eventd daemon listening to events and executing
s6-rc commands on the dynamic database depending on the events it
receives. Paired with a s6-rc-event program that sends events to
s6-rc-eventd, meant to be invoked in situations such as udevd/mdevd
rules, a netlink listener, etc.

  This model works in my head, the s6-rc-event[d] programs would be quite
simple to write, it would solve the problem in a modular way just like
the skarnet.org usual, so it seems like a no-brainer.
  Except for one thing: I don't think anybody would use this. Only me,
you, and the other 6 hardcore people in the world who actually like
this kind of design.

  If there's one thing that has been made painfully obvious to me these
past few years, it is that most people, and especially most *distro*
people - which are the ones I would like to reach -, perceive the s6
stack as very complex. They're intimidated by it; they find the
abundance of moving parts off-putting and difficult to get into.
With very few exceptions, the people who actually take the plunge and
make the time and energy investment necessary to understand the model,
what the various parts do and how they fit together, those people all
love it, and are very enthusiastic about it, and they're what keeps me
going. But the initial barrier of potential, the ultra-steep learning
curve, is indisputably the limiting factor in the spread of the s6
ecosystem.

  s6 as a supervision suite? okay, people will use it; but it's already
perceived as a bit complex, because there are a lot of binaries.
It's on the high end of the acceptable difficulty range.

  s6 as an init system? "what is this s6-linux-init thing? why do I need
this? runit is simpler, I'll stick to runit." Even though runit has
problems, has less functionality, and is barely maintained. There are,
for instance, several people in Void Linux who are interested in
switching to s6, but despite s6 being an almost drop-in replacement for
runit, the switch has not been made, because it requires learning s6 and
s6-linux-init, and most Void people do not feel the effort is worth it.

  s6-rc? "waah I don't like the source directory format, I want text
files, and why is it so different from 'service foo start'? And why
doesn't it come with integrated policy like OpenRC or systemd?" People
understand the benefit in separating mechanism from policy, in theory,
but in practice nobody wants to write policy. (Can't blame them: I find
it super boring, too.) Having the tool is not enough; it needs to be
gift-wrapped as well, it needs to be nice to use.

  If I add a s6-rc-event family of binaries to s6-rc, the fact that it
is yet another layer of functionality, that you now need *two*
databases, etc., will make a whole additional category of people just
give up. The outreach will be, mark my words, *zero*. If not negative.

  The fact is that a full-featured init system *is* a complex beast, and
the s6 stack does nothing more than is strictly needed, but it exposes
all the tools, all the entrails, all the workings of the system, and
that is a lot for non-specialists to handle. Integrated init systems,
such as systemd, are significantly *more* complex than the s6 stack, but
they do a better job of *hiding* the complexity, and presenting a
relatively simple interface. That is why, despite being technically
inferior (on numerous metrics: bugs, length of code paths, resource
consumption, actual modularity, flexibility, portability, etc.), they
are more easily accepted: they are just less intimidating.

  As a friend told me, and it was an enlightening moment: you are keeping
the individual parts simple, but in doing so, you are moving the
complexity to the *interactions* between the parts, and are burdening
the user with that complexity. You are keeping the code simple, which
has undeniable maintainability benefits, but you are making the
administration more difficult, and the trade-off is not good enough for
a lot of users.

  For a while, my answer to that has been: this is all an interface
problem. I need to work on s6-frontend, in order to provide a unified,
user-friendly interface; then, people who want simplicity can use the
high-level interface, and advanced users can lift the hood and manually
tweak the engine.
  I still believe that is a good model and a good idea. However, having
worked for a couple months on a user-friendly interface for service
management with s6-rc that could be a prototype for a part of
s6-frontend, and having started to think about details of s6-frontend,
I've come to realize that shrinkwrapping the s6 ecosystem as it is
today *will already be pretty hard*, and a lot, and I mean a lot, of
work is going to go into that interface. And adding more moving parts
in the engine will require even more work for the interface to control
those moving parts. We're reaching levels of kitchensinkery I'm not
comfortable with.

  In the end, what risks happening? A neat, slick, thrifty engine, with
a lot of knobs, and a big fat complex interface on top of it - and
unless you're a specialist, you *need* the interface, because there are
so many knobs that you otherwise need a degree to understand what
everything does. And what good is it to have such a satisfying engine
if you can't use it without a thick layer of bloat?

  So, I think my software design needs to be rebalanced, and complexity
needs to be spread more evenly. I'm certainly not going to write
monoprocess behemoths, that's not what I do, but I need to stop yolo
adding small binaries to address some functionality and say "there you
go, here's the mechanism, how to use it is left as an exercise to the
reader." Which is exactly what would happen with s6-rc-eventd.

  So, option 2 is to take a step back and say: a service manager is one
(complex) functionality, and if I want a full-fledged service manager,
I need to design it as such from the beginning, instead of having a
static service manager with a program to handle dynamic stuff added next
to it as an afterthought and the complexity needing to be managed by
users or by s6-frontend.
  And that means a s6-rc redesign.

  I haven't made a decision yet: I'm in the process of *exploring* what
a s6-rc redesign would look like. But so far, this is what I think a
full service manager should do:

  - Be similar in concept to Upstart. The Upstart implementation is bad,
but the fundational ideas are actually quite good.
    * That means: event-based, transitions are triggered by events, and
events can have several sources: a transition finishing, but also
external events such as ones coming from a network manager, or internal
events coming from the daemon itself (this is necessary for Upstart
because it's an init system, I don't think it is necessary for a pure
service manager).
  - Perform as much static analysis and upfront checking as possible, 
just
like the current s6-rc. I would like to keep the same level of 
guarantees
for a fully static set of services, and ideally be able to offer some
guarantees as well for dynamic ones, although it's obviously impossible
to do a full analysis for them.
  - Support disjunctions in service trigger conditions! If I'm going to
rewrite the engine, might as well allow for alternatives without forcing
the user to recompile a database.
  - Support instances. After a lot of brainstorming and several attempts,
I've been unable to find a good way to add instantiation to the current
s6-rc model. If we want instantiation, it definitely needs to be a part
of service manager design from the start, so this would be the
opportunity.

  So here you are. In the weeks to come, I'll keep thinking about the
details of option 2, and build an outline of the various necessary 
parts.
And eventually, if I think I can write this, with all the functionality,
while still sticking to my standards of code simplicity, then it's
what I'll do. If not, and in particular, if I can't get all the static
analysis guarantees that I want, then I'll just go with option 1, which
will do a decent job for a lot less work but will definitely not help
the perception of the s6 ecosystem by normal people.

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01  9:20               ` Casper Ti. Vector
@ 2020-09-01 10:02                 ` Alexis
  2020-09-01 10:15                   ` Casper Ti. Vector
  0 siblings, 1 reply; 30+ messages in thread
From: Alexis @ 2020-09-01 10:02 UTC (permalink / raw)
  To: Casper Ti. Vector; +Cc: supervision


Casper Ti. Vector <caspervector@gmail.com> writes:

> May I request a diff (via PM) between your attempt and the 
> current HTMLs?

That involves ~70 documents. Do you need all of them, or can i 
just provide a diff of a few examples? i don't currently have the 
HTML sources locally; i'd have to download them all.


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
       [not found]           ` <20200901063801.GA2158@caspervector>
@ 2020-09-01 10:11             ` Laurent Bercot
  2020-09-01 11:28               ` Casper Ti. Vector
  2020-09-01 11:55               ` Alexis
  0 siblings, 2 replies; 30+ messages in thread
From: Laurent Bercot @ 2020-09-01 10:11 UTC (permalink / raw)
  To: supervision

>
>* We negotiate a HTML schema your documentation can be written in, which
>   is based on current documentation; existing HTML documentation will be
>   converted to the schema, with minimised changes.  (The structuredness
>   of HTML helps; now you also see why knowing some Lisp is beneficial :)

  I'm totally willing to use a HTML schema we can negotiate, to write
future documentation in. What I don't want to do is:
  - Touch existing documentation, unless I have to rewrite the content of
a page for some reason. Of course, if the conversion work is done by
somebody else, I have no objection to upstreaming the new documents.
  - Add heavy dependencies to the skarnet.org Makefiles.

  But honestly, if I'm going to change the way I write doc, I'd rather
write scdoc, which is simpler than plain HTML especially if we're
adding a lot of semantic tags to that HTML. To me, the best thing
would be if someone would add a HTML backend to scdoc. I may do it
myself if I need a break from interesting service management stuff and
experience an irresistible urge to work on HTML generation instead.
The odds are what they are.

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01 10:02                 ` Alexis
@ 2020-09-01 10:15                   ` Casper Ti. Vector
  0 siblings, 0 replies; 30+ messages in thread
From: Casper Ti. Vector @ 2020-09-01 10:15 UTC (permalink / raw)
  To: supervision

On Tue, Sep 01, 2020 at 08:02:34PM +1000, Alexis wrote:
> That involves ~70 documents. Do you need all of them, or can i just provide
> a diff of a few examples? i don't currently have the HTML sources locally;
> i'd have to download them all.

Preferably some representative samples, thanks.

-- 
My current OpenPGP key:
RSA4096/0x227E8CAAB7AA186C (expires: 2022.09.20)
7077 7781 B859 5166 AE07 0286 227E 8CAA B7AA 186C


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01 10:11             ` Laurent Bercot
@ 2020-09-01 11:28               ` Casper Ti. Vector
  2020-09-01 11:55               ` Alexis
  1 sibling, 0 replies; 30+ messages in thread
From: Casper Ti. Vector @ 2020-09-01 11:28 UTC (permalink / raw)
  To: supervision

On Tue, Sep 01, 2020 at 10:11:14AM +0000, Laurent Bercot wrote:
>  I'm totally willing to use a HTML schema we can negotiate, to write
> future documentation in. What I don't want to do is:
>  - Touch existing documentation, unless I have to rewrite the content of
> a page for some reason. Of course, if the conversion work is done by
> somebody else, I have no objection to upstreaming the new documents.

Of course it will be done by someone else :)

>  - Add heavy dependencies to the skarnet.org Makefiles.

Alternatively, if you find it acceptable, we can have an independent
project that hosts the code transformers.  What you need to care about
then is writing in the specified schema and merging documentation
patches (in case of schema violation).  The first patches will be fairly
large for obvious reasons, but I can separate them into relatively
easily-to-verify (small or generated by sed-like automation)
transformation passes, in the style of [1].

[1] <https://gitea.com/CasperVector/reagent>
    (See the last sentence in the "About" section of README).

-- 
My current OpenPGP key:
RSA4096/0x227E8CAAB7AA186C (expires: 2022.09.20)
7077 7781 B859 5166 AE07 0286 227E 8CAA B7AA 186C


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01 10:11             ` Laurent Bercot
  2020-09-01 11:28               ` Casper Ti. Vector
@ 2020-09-01 11:55               ` Alexis
  1 sibling, 0 replies; 30+ messages in thread
From: Alexis @ 2020-09-01 11:55 UTC (permalink / raw)
  To: supervision


Laurent Bercot <ska-supervision@skarnet.org> writes:

>  I'm totally willing to use a HTML schema we can negotiate, to 
>  write
> future documentation in. What I don't want to do is:
>  - Touch existing documentation, unless I have to rewrite the 
>  content of
> a page for some reason. Of course, if the conversion work is 
> done by
> somebody else, I have no objection to upstreaming the new 
> documents.

In terms of automating such a conversion, here are a few of the 
things the automation would need to do:

* Determine whether some text is an environment 
  variable. Environment variables in the current HTML aren't 
  marked up. You might think that you could say "Well, if it's all 
  caps it's an env var", but that won't work, because will catch 
  things like SIGTERM and SO_REUSEADDR. You could special-case 
  'SIG*', but i'm not sure what could be done about things like 
  SO_REUSEADDR.

* Parse things like "s6-envuidgid [ -u | -g | -B ] [ -n ] [ -i | 
  -D uid:gid:gidlist ] account prog..." appropriately, so that 
  mdoc/roff using Op, Fl and Ar can be produced. The parsing will 
  also need keep track of the fact that further uses of "account" 
  in the mdoc/roff might need to be preceded by an Fl macro. Of 
  course, the word "account" is not necessarily referring to the 
  "account" argument, but also to the notion of an account in 
  general: in "s6-envuidgid looks account up by name in the 
  account database", the first "account" should be preceded by Fl, 
  but the second shouldn't. So this sort of thing would somehow 
  need to be handled as well. 

Note that "-D uid:gid:gidlist" will require special handling, as 
that seems to also need use of Ns to produce the correct output, 
i.e. ".Op Fl i | D Ar uid Ns : Ns Ar gid Ns : Ns Ar 
gidlist". Although, `mandoc -T lint` currently produces a warning 
about the use of Ns there; if mdoc/roff experts have any 
suggestions as to The Correct Way to do this, i'm all ears. :-)

* In accessrules.html, <tt> is used to indicate file paths, 
  function types, variable types and the accessrules library 
  itself; these cases will somehow need to be 
  distinguished. (There are currently places in s6-accessrules.7 
  where, in my first pass, i've used Ql when i should actually be 
  using Vt; that's one of the things i still need to fix.)

So my guess is that trying to automate a conversion will be much 
more work than simply doing a conversion manually.


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: possible s6-rc redesign
  2020-09-01 10:00     ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Laurent Bercot
@ 2020-09-01 19:24       ` mobinmob
  2020-09-01 22:16         ` Dudemanguy
  2020-09-01 22:20         ` Laurent Bercot
  2020-09-01 23:14       ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Steve Litt
  1 sibling, 2 replies; 30+ messages in thread
From: mobinmob @ 2020-09-01 19:24 UTC (permalink / raw)
  To: supervision

Thank you for taking the time to present the options and the technical
arguments for each of them. I cannot offer a comment on the best way
to proceed on technical grounds, but I can offer my two cents as someone
who tries to bring an s6-rc based solution (66) to a distribution.

1. There is one **huge** disadvantage for the second option. It is not a
technical one, so it may carry little weight on your final decision.
There already different implementations of init systems based on s6/s6-rc,
some of them successfully used on distributions. They will almost certainly
have to be abandoned or rewritten to function with the redesigned suite.
The first option will allow these implementations to augment what they 
offer
with minimal or no disruption for their users and developers.

2. Which distributions or groups of distributions will find the redesign 
appealing,
so that they will adopt it ?
IMHO distributions that use systemd are not likely to change in the 
foreseeable
future, so that leaves the distributions that use something else. Some 
of them
already have s6-based solutions (official or not), so adopting the 
redesigned
will be akin to adding another init for them. Distributions that use 
neither
s6/s6-rc nor systemd will be a likely target but they have to be 
persuaded to
use a -almost certainly- more complex solution than what they have and that
is an uphill battle.

3. Yes, the compiled db of services or the many files in the servicedir can
discourage people to use s6-rc. But ANY new format will face similar
criticism and some of the problems can be alleviated with the proper
frontend. I use 66. Ι never touch servicedirs - it uses ini-based "frontend
service files"- and I have dabbled with the compiled once, indirectly.

4.  On the issue of mechanisms vs policy I fully agree that people want
a turnkey solution. However I do not think that is something that should
be done in a cetralised manner. There already at least 3 different working
sets of services created for s6-rc (artix, slew, 66) and someone can 
inspect,
use and modify them to fit their needs or policies.


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01  9:03             ` Alexis
  2020-09-01  9:20               ` Casper Ti. Vector
@ 2020-09-01 20:13               ` Steve Litt
  2020-09-02  0:50                 ` Alexis
  1 sibling, 1 reply; 30+ messages in thread
From: Steve Litt @ 2020-09-01 20:13 UTC (permalink / raw)
  To: supervision

On Tue, 01 Sep 2020 19:03:36 +1000
Alexis <flexibeast@gmail.com> wrote:

> Casper Ti. Vector <caspervector@gmail.com> writes:
> 
> > * We negotiate a HTML schema your documentation can be written 
> > in, which
> >   is based on current documentation; existing HTML documentation 
> >   will be
> >   converted to the schema, with minimised changes.  
> 
> On the basis of my current experiences, it would be No Small Task 
> to convert the current, presentationally-based, HTML documentation 
> to markup that's sufficiently semantic to enable it to be 
> mechanically converted to mdoc/roff. 

Depends on how the HTML is written. You can take any
Troubleshooters.Com web page authored new in the past five years, run
it through an XML parser, and come up with all-styles, no appearance
code. All my appearance is via CSS, none is via tags in the <body/>.

It's my very strong opinion that, in a conversion to a different output
format, the CSS should be just dumped on the floor, and LaTeX or
Docbook or whatever styles should be hand-authored appropriately for
the output format. With no-appearance-in-body HTML, it's very easy
during conversion to make a list of all referenced styles, making
authoring of such style-to-appearance conversion easy.

So it all depends on how the HTML was written. If it was crafted by a
styles-aware person using CSS to translate styles to appearance, and
having no appearance info in <body/>, and if the HTML is well formed
XML (which is just fine for HTML5), then the conversion is trivial. If
it's thrown together, catch as catch can HTML, then Alexis is right,
programmatic conversion would be a mess. If the HTML was made by one of
those GUI WYSIWYG HTML editors, then the HTML is absolute junk and it's
best to start anew.

See http://troubleshooters.com/linux/unbound_nsd/unbound.htm for an
example of no-appearance-in-body HTML5 document.

By the way, if any of you is interesting in helping create an
all-styles, no appearance, quick authoring documentation language,
please contact me offlist. I have the beginnings of one, but was unable
to do the whole thing myself.

In this post I express no opinion whether this should or shouldn't be
done. All I'm saying is don't assume, sight unseen, that the current
HTML can't easily be converted to semantic LaTeX or Docbook or whatever.
 
SteveT

Steve Litt 
Autumn 2020 featured book: Thriving in Tough Times
http://www.troubleshooters.com/thrive

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: possible s6-rc redesign
  2020-09-01 19:24       ` possible s6-rc redesign mobinmob
@ 2020-09-01 22:16         ` Dudemanguy
  2020-09-01 22:20         ` Laurent Bercot
  1 sibling, 0 replies; 30+ messages in thread
From: Dudemanguy @ 2020-09-01 22:16 UTC (permalink / raw)
  To: supervision

On 9/1/20 2:24 PM, mobinmob wrote:
> 2. Which distributions or groups of distributions will find the redesign > appealing, so that they will adopt it ?
I can't speak for everyone of course, but at least in the perspective of 
Artix, this potential redesign idea could be very appealing. If s6-rc 
hypothetically had a more event-based approach, there are definitely a 
lot of potential benefits users could see in terms of managing services.
Artix simply uses s6-rc directly so a migration to a new s6-rc probably 
wouldn't be as painful as it may be for other workflows. So at least for 
me, it's an interesting proposition and not a scary one.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: possible s6-rc redesign
  2020-09-01 19:24       ` possible s6-rc redesign mobinmob
  2020-09-01 22:16         ` Dudemanguy
@ 2020-09-01 22:20         ` Laurent Bercot
  2020-09-02  9:41           ` mobinmob
  1 sibling, 1 reply; 30+ messages in thread
From: Laurent Bercot @ 2020-09-01 22:20 UTC (permalink / raw)
  To: supervision

>1. There is one **huge** disadvantage for the second option. It is not a
>technical one, so it may carry little weight on your final decision.
>There already different implementations of init systems based on s6/s6-rc,
>some of them successfully used on distributions. They will almost certainly
>have to be abandoned or rewritten to function with the redesigned suite.
>The first option will allow these implementations to augment what they offer
>with minimal or no disruption for their users and developers.

  You may have missed the part where I'm saying that the current version
of s6-rc will still be supported for a *long time*. I would also try,
obviously, to make the conversion to the new format as painless as
possible; ideally (but I don't know yet whether it's an attainable 
goal),
the source directories would have the exact same format as long as only
static services are defined - so tools using s6-rc-0.x would still work
with basically no changes.


>2. Which distributions or groups of distributions will find the redesign appealing, so that they will adopt it ?
>IMHO distributions that use systemd are not likely to change in the foreseeable future,

  And they definitely won't, if nothing challenges systemd. But
providing the same level of functionality as systemd (as far as the
init system is concerned, I'm not talking about all the tendrils it 
sends
into various parts of running a Linux machine) with a better design, 
that
is not completely alien to what those distros are used to, is the only
way to - someday - have a chance at challenging systemd.


>  so that leaves the distributions that use something else. Some of them
>already have s6-based solutions (official or not), so adopting the redesigned
>will be akin to adding another init for them.

  No, absolutely not. The idea is to have something similar to s6-rc, but
with more functionality integrated in it. It would not be a different
init by any stretch of the imagination.


>3. Yes, the compiled db of services or the many files in the servicedir can
>discourage people to use s6-rc. But ANY new format will face similar
>criticism and some of the problems can be alleviated with the proper
>frontend. I use 66. Ι never touch servicedirs - it uses ini-based "frontend
>service files"- and I have dabbled with the compiled once, indirectly.

  I agree with that - except that the compiled db is actually a very
small hurdle, that goes away once you explain that OpenRC and systemd
also use a compiled db except that it's hidden and everything is done
dynamically, and s6-rc only makes it cleaner and more upfront.

  Yes, the solution is a user-friendly interface, but that's not
relevant to what I'm talking about. What I'm saying is that 
distributions,
including ones that currently use s6/s6-rc under 66 or any other
interface, *will* need dynamic events integration to the service manager
at some point, and the question is, how to add the functionality to
s6-rc. I think Option 2 is *more* likely to get adopted by
distributions overall. Distros that have already drunk the s6-rc
kool-aid will be fine with either option 1 or option 2 (see above);
normie distros will very probably be repulsed by option 1.


>4.  On the issue of mechanisms vs policy I fully agree that people want
>a turnkey solution. However I do not think that is something that should
>be done in a cetralised manner. There already at least 3 different working
>sets of services created for s6-rc (artix, slew, 66) and someone can inspect,
>use and modify them to fit their needs or policies.

  Yes, people can pick and choose what they want, and as it is now, 
things
are working for power users.
  That is still niche though, and in order to reach more people, a wide
array of distributions is the way to go.
  I'm very happy that distributions such as Obarun and Artix have done
the effort of actually porting services to a new format, be it 66
or raw s6-rc; but it is not something that can be expected from most
distributions, especially the big ones, which I *will* be aiming for at
some point. I don't like the idea of a software author providing policy,
any more than you do, but it is what worked for systemd and OpenRC, and
in case you haven't noticed, I'm trying to be very pragmatic here, and
to make the necessary sacrifices of principles in order to gain wider
adoption.

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7))
  2020-09-01 10:00     ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Laurent Bercot
  2020-09-01 19:24       ` possible s6-rc redesign mobinmob
@ 2020-09-01 23:14       ` Steve Litt
  1 sibling, 0 replies; 30+ messages in thread
From: Steve Litt @ 2020-09-01 23:14 UTC (permalink / raw)
  To: supervision

On Tue, 01 Sep 2020 10:00:22 +0000
"Laurent Bercot" <ska-supervision@skarnet.org> wrote:


>   s6 as a supervision suite? okay, people will use it; but it's
> already perceived as a bit complex, because there are a lot of
> binaries. It's on the high end of the acceptable difficulty range.

I've only used s6 as a supervisor a few times, but my memory tells me
it had pretty much the same binaries (named differently) as runit, and
was no more complicated than runit. I use runit every day.

>   s6 as an init system? "what is this s6-linux-init thing? why do I
> need this? runit is simpler, I'll stick to runit." Even though runit
> has problems, has less functionality, and is barely maintained. There
> are, for instance, several people in Void Linux who are interested in
> switching to s6, but despite s6 being an almost drop-in replacement
> for runit, the switch has not been made, because it requires learning
> s6 and s6-linux-init, and most Void people do not feel the effort is
> worth it.

Perhaps a baby step would be to use sysvinit ONLY to act as PID1, which
if I understand things sysvinit is pretty good at, and have
/etc/inittab or whatever it's called simply respawn the s6 supervisor.
Given that most current distros that aren't blissfully wed to systemd
have an option for sysvinit, this would work. I think the same thing
could be done with OpenRC, but it would be a little more complicated.

Obviously, there would need to be something that temporarily shuts off
sysvinit's daemon runner so that they can install the whole sysvinit
package and not have double-daemons. I recommend a kludge for that: Do
the kludge when installing s6 supervisor, undo the kludge when
uninstalling s6 supervisor.

I'm aware that the preceding baby step doesn't get us to the point of
s6 as PID1, but if it gets us to the point where lots of people are
using the supervisor and those people get used to it, they'll demand s6
as PID1.

I think I'm going to, very slowly, little by little, move my daemons on
my Void Linux Daily Driver Desktop (DDD) to s6. As I move each, I'll
put a down file in the runit directory (or just unlink it). I'll report
back to you in a month.


> 
>   s6-rc? "waah I don't like the source directory format, I want text
> files, and why is it so different from 'service foo start'? And why
> doesn't it come with integrated policy like OpenRC or systemd?" 

What is "integrated policy?"

[snip]

> 
>   So, I think my software design needs to be rebalanced, and
> complexity needs to be spread more evenly. I'm certainly not going to
> write monoprocess behemoths, that's not what I do, but I need to stop
> yolo adding small binaries to address some functionality and say
> "there you go, here's the mechanism, how to use it is left as an
> exercise to the reader." Which is exactly what would happen with
> s6-rc-eventd.
> 
>   So, option 2 is to take a step back and say: a service manager is
> one (complex) functionality, and if I want a full-fledged service
> manager, I need to design it as such from the beginning, instead of
> having a static service manager with a program to handle dynamic
> stuff added next to it as an afterthought and the complexity needing
> to be managed by users or by s6-frontend.
>   And that means a s6-rc redesign.
> 
>   I haven't made a decision yet: I'm in the process of *exploring*
> what a s6-rc redesign would look like. But so far, this is what I
> think a full service manager should do:
> 
>   - Be similar in concept to Upstart. The Upstart implementation is
> bad, but the fundational ideas are actually quite good.

[snip a lot of complicated stuff]

If you get as complicated as you wrote, runit will forever eclipse s6
because of the huge contrast in complexity. It doesn't have to be that
way. 

If I correctly understand your previous writings, the ideal init would
be to have PID1 be a mini-supervisor that supervises only the real s6
supervisor. I think you had that complete years ago. 

Then you needed to, upon bootup, start daemons in a specific order,
hence the first need for s6-rc. However, this could easily be handled
on a numerical sort order basis with a file in the daemon directory
called order1234 or order1235 or order9999 (no doubt for the equivalent
of rc.local). Daemon directories with no order file could default to
order5000. I've never had a problem with the fact that runit has no
bootup ordering and is indeterminate, and the couple times I
constructed systems experimentally with suckless-init as PID1 and s6
supervisor, same thing: Everything worked despite the indeterminance.
So defaulting the majority or even all to order5000 almost certainly
won't cause problems.

Numerical sorting is much easier for everyone, but if dependency based
sorting is needed, it can be done with a provides/requires system.
Given that tests can be done within a run script I think this is
unnecessary, and adds to complexity, but it's doable.

Later, a need to randomly mix supervised and run-once processes was
expressed. In my opinion, this is a grievous omission from daemontools,
and I'm glad it's being done (I think via s6-rc). But wouldn't it be
easier just to have either a runonce or run program in the daemon
directory, depending on whether it should be a one-shot or supervised?
I'm pretty sure this would be easy to implement. I'd imagine runonce
just forks, leaves a marker file to show it's been done, and forgets.
The marker files are deleted on initial startup.

If I'm understanding today's email correctly, and I'm not sure I am,
is that you want s6 or some components thereof to react to requests
from programs like networkmanager and events like plugging in a USB.
For the usb plugins and plugouts, and network ups and down, dmesg -WT --
on Linux and its equivalent on BSD does the job (requires an #ifdef).
As far as NetworkManager, either NetworkManager needs to notify the
proper daemon, (not likely from the FreeDesktop/Redhat/Poettering
coalition), or s6 needs a daemon to play each Freedesktop inspired
program's game, probably by listening in on dbus. I hope to hell such a
daemon will be completely separated from the other s6 components,
because it will doubtlessly need to change as FreeDesktop gets "new and
better" ideas, because dbus adds huge complexity to anything, and
because many people may not wish to deploy dbus-connected software.

To summarize, I think everything desired can be added, modularly, with
little increase in complexity, and I think it can be part of a package
manager package.

SteveT

Steve Litt 
Autumn 2020 featured book: Thriving in Tough Times
http://www.troubleshooters.com/thrive

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: [request for review] Port of s6 documentation to mdoc(7)
  2020-09-01 20:13               ` Steve Litt
@ 2020-09-02  0:50                 ` Alexis
  0 siblings, 0 replies; 30+ messages in thread
From: Alexis @ 2020-09-02  0:50 UTC (permalink / raw)
  To: supervision


Steve Litt <slitt@troubleshooters.com> writes:

> Depends on how the HTML is written ... All I'm saying is don't 
> assume,
> sight unseen, that the current HTML can't easily be converted to
> semantic LaTeX or Docbook or whatever.

This is good advice in general; but in this particular case, 
there's no "sight unseen" involved on my part. i have actually 
looked at the HTML sources of the existing s6 documentation. (For 
some context, i've authored HTML professionally myself.)

As i indicated in the post to which you responded, as well as in 
my last post to this list:

    https://www.mail-archive.com/supervision@list.skarnet.org/msg02560.html

the current HTML markup is basically not semantic, but 
presentationally-based.

(i'm not complaining about this. i'm very grateful that Laurent 
has provided such comprehensive documentation for s6; many 
software authors provide far less, or suggest that the source is 
the end-user documentation. i feel s6 is a sufficiently important 
project that i'm happy to help out with documentation stuff, 
rather than putting further demands on Laurent's already-saturated 
bandwidth.)

To be more specific regarding one of the points in my last post, 
here's an excerpt from s6-envuidgid.html:

    <pre>
         s6-envuidgid [ -u | -g | -B ] [ -n ] [ -i | -D 
         <em>uid</em>:<em>gid</em>:<em>gidlist</em> ] 
         <em>account</em> <em>prog...</em>
    </pre>


Alexis.

^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: possible s6-rc redesign
  2020-09-01 22:20         ` Laurent Bercot
@ 2020-09-02  9:41           ` mobinmob
  2020-09-02 12:14             ` Laurent Bercot
  0 siblings, 1 reply; 30+ messages in thread
From: mobinmob @ 2020-09-02  9:41 UTC (permalink / raw)
  To: supervision


On 2/9/20 1:20 π.μ., Laurent Bercot wrote:
>> 1. There is one **huge** disadvantage for the second option. It is not a
>> technical one, so it may carry little weight on your final decision.
>> There already different implementations of init systems based on 
>> s6/s6-rc,
>> some of them successfully used on distributions. They will almost 
>> certainly
>> have to be abandoned or rewritten to function with the redesigned suite.
>> The first option will allow these implementations to augment what 
>> they offer
>> with minimal or no disruption for their users and developers.
>
>  You may have missed the part where I'm saying that the current version
> of s6-rc will still be supported for a *long time*. I would also try,
> obviously, to make the conversion to the new format as painless as
> possible; ideally (but I don't know yet whether it's an attainable goal),
> the source directories would have the exact same format as long as only
> static services are defined - so tools using s6-rc-0.x would still work
> with basically no changes.
>
If long term support is guaranteed and a smooth transition path is provided
then any concern I have suddenly dissipates :p

>> 2. Which distributions or groups of distributions will find the 
>> redesign appealing, so that they will adopt it ?
>> IMHO distributions that use systemd are not likely to change in the 
>> foreseeable future,
>
>  And they definitely won't, if nothing challenges systemd. But
> providing the same level of functionality as systemd (as far as the
> init system is concerned, I'm not talking about all the tendrils it sends
> into various parts of running a Linux machine) with a better design, that
> is not completely alien to what those distros are used to, is the only
> way to - someday - have a chance at challenging systemd.
>

There are two issues here...

1. In order to provide the -sane- functionality of systemd, a system
needs to use linux-only interfaces. I am absolutely not saying that cgroups,
namespaces etc should be tightly integrated to a service manager/init 
system.
Most of the work can be done on dedicated programs but they are needed
if the goal is feature-parity...
2. Distributions that use systemd are slowly depending more and more on
these tendrils (great analogy btw :P). I do not think they will make the 
effort
to get rid of them or provide alternate mechanisms to facilitate inclusion
of a different init system no matter how much better, cleaner and well-
designed it is. And s6-rc is all three of them IMHO. The only way to create
pressure is a successful set of distributions that use other solutions...


>  I agree with that - except that the compiled db is actually a very
> small hurdle, that goes away once you explain that OpenRC and systemd
> also use a compiled db except that it's hidden and everything is done
> dynamically, and s6-rc only makes it cleaner and more upfront.

Well said :)


>  Yes, the solution is a user-friendly interface, but that's not
> relevant to what I'm talking about. What I'm saying is that 
> distributions,
> including ones that currently use s6/s6-rc under 66 or any other
> interface, *will* need dynamic events integration to the service manager
> at some point, and the question is, how to add the functionality to
> s6-rc. I think Option 2 is *more* likely to get adopted by
> distributions overall. Distros that have already drunk the s6-rc
> kool-aid will be fine with either option 1 or option 2 (see above);
> normie distros will very probably be repulsed by option 1.
>

Yes, dynamic events integration is absolutely needed, no argument there.
If that can be done with minimal disruption on the user/integrator side
I have no problems with either option.


>
>> 4.  On the issue of mechanisms vs policy I fully agree that people want
>> a turnkey solution. However I do not think that is something that should
>> be done in a cetralised manner. There already at least 3 different 
>> working
>> sets of services created for s6-rc (artix, slew, 66) and someone can 
>> inspect,
>> use and modify them to fit their needs or policies.
>
>  Yes, people can pick and choose what they want, and as it is now, things
> are working for power users.
>  That is still niche though, and in order to reach more people, a wide
> array of distributions is the way to go.
>  I'm very happy that distributions such as Obarun and Artix have done
> the effort of actually porting services to a new format, be it 66
> or raw s6-rc; but it is not something that can be expected from most
> distributions, especially the big ones, which I *will* be aiming for at
> some point. I don't like the idea of a software author providing policy,
> any more than you do, but it is what worked for systemd and OpenRC, and
> in case you haven't noticed, I'm trying to be very pragmatic here, and
> to make the necessary sacrifices of principles in order to gain wider
> adoption.
>
> -- 
>  Laurent
>

I am not saying that policy should not be provided at all. I am saying 
that they are
  advantages if it is provided outside of the main project and 
downstreams tailor it
to their specs. Voidlinux runit configuration
is influenced by ignite and artix runit is influenced by voidlinux. Both 
voidlinux and artix
have pretty different policies expressed in the relevant scripts. They 
also share a lot of
scripts. Building 66 frontend service files for voidlinux (unofficially) 
I have checked
obarun 66 frontends, artix s6-rc services and voidlinux runit scripts. 
but the minimal
policies I strive to implement are those of voidlinux.


My point is... runit has found adoption in the post-systemd era despite 
having
obvious issues. It was not a comprehensive upstream policy that helped it. I
think it is a better model for adoption that that of openRC or systemd.


^ permalink raw reply	[flat|nested] 30+ messages in thread

* Re: possible s6-rc redesign
  2020-09-02  9:41           ` mobinmob
@ 2020-09-02 12:14             ` Laurent Bercot
  0 siblings, 0 replies; 30+ messages in thread
From: Laurent Bercot @ 2020-09-02 12:14 UTC (permalink / raw)
  To: supervision

>1. In order to provide the -sane- functionality of systemd, a system
>needs to use linux-only interfaces. I am absolutely not saying that cgroups,
>namespaces etc should be tightly integrated to a service manager/init system.
>Most of the work can be done on dedicated programs but they are needed
>if the goal is feature-parity...

  Yes, that is very true, and a concern I've increasingly had: OSes are
making *zero* coordination efforts for their interfaces, and software
is increasingly relying on OS-specific interfaces. So it's becoming more
and more difficult to write for Unix at large, and market fragmentation
is becoming more obvious by the day.

  For the various engines of an init system, though, I'm not too worried.
  - The early boot is inherently not portable (s6-*linux*-init is called
that way for a reason), but it's not a big or complex piece of code,
and it's easy to adapt it to another OS as soon as one has a working
knowledge of the details of init mechanisms on those OSes.
  - The supervision engine is portable, with a caveat.
  - The service manager is portable, even with dynamic event integration.
What is *not* portable is the various listeners that produce events,
but hooking a s6-rc-event call to them should not be difficult.

  The caveat for the supervision engine is, as you mentioned, cgroups
and namespace management, for the sole reason that the Linux way of
starting a process in a new namespace is contrary to the venerable Unix
pattern of changing your own process state then exec'ing: in some cases
you need involvement from the parent in changing the child's state.
There is a patch that has been submitted to this list that does exactly
that: tell s6-supervise to start the service in a new namespace. I have
not applied this patch because I didn't want to introduce system-
dependent features into s6, but with the way OSes are diverging, I might
soon have to bite the bullet and change my stance on this.

  But apart from that misdesign from the Linux kernel, most OS-specific
stuff can actually be done from inside services, in run scripts for
instance, so engines can be kept portable. If OS-specific tools are
needed to easily write service scripts, then those tools can be provided
as a separate, OS-specific package - like an extension.

  In other words: policy is definitely not portable and needs a lot of
extensions, but mechanism generally is, and I'm always starting with
mechanism - I'll address Linux policy later.


>2. Distributions that use systemd are slowly depending more and more on
>these tendrils (great analogy btw :P). I do not think they will make the effort
>to get rid of them or provide alternate mechanisms to facilitate inclusion
>of a different init system no matter how much better, cleaner and well-
>designed it is. And s6-rc is all three of them IMHO. The only way to create
>pressure is a successful set of distributions that use other solutions...

  Yes, but do not underestimate the general efforts that are being done
to have functionality outside of systemd. We're not the only bastion of
opposition here :) Alternate mechanisms do exist for most of what 
systemd
does; distributions mostly migrate to the systemd way of doing things
because it's more *convenient* to get the functionality from a single
source than it is to piece it together from various bits. systemd is
thriving on distribution laziness.
  But a distribution that is committed to not using systemd is (still)
very much able to offer a lot of functionality, it just requires
somewhat more effort.

  I don't expect to make it into Ubuntu or Red Hat right away. But if
a lot of other distros out there are running a credible alternative with
equivalent functionality, then at least users will have choice, and it
will be impossible for systemd advocates to pretend that their chosen
init system is inevitable. (insert Avengers: Endgame meme here)


>I am not saying that policy should not be provided at all. I am saying that they are
>  advantages if it is provided outside of the main project and downstreams tailor it
>to their specs.

  Possibly; that is honestly a packaging problem. It's a balance to find
between flexibility and convenience. systemd and OpenRC have played the
convenience card to the max and it has worked well for them; s6 has
always played the flexibility card instead, and experts love that, but
most people don't, especially when *no* policy is provided. :)

  If a package provides a set of init scripts, distributions will tailor
it anyway. The RedHat /lib/systemd is not exactly the same as the Ubuntu
one. The Alpine OpenRC scripts are not exactly the same as the Gentoo
ones. It does not really matter where the policy is provided, but
distros have made it very clear to me that they prefer having a working
set to start with and to tailor to their needs, rather than having 
nothing
and needing to come up with everything themselves. If it's better for
s6-frontend to be pure mechanism with a s6-frontend-policy package next
to it, why not; I don't think anybody really cares as long as this 
package
exists.

--
  Laurent


^ permalink raw reply	[flat|nested] 30+ messages in thread

end of thread, other threads:[~2020-09-02 12:14 UTC | newest]

Thread overview: 30+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-30  8:30 [request for review] Port of s6 documentation to mdoc(7) Alexis
2020-08-30  9:10 ` eric vidal
2020-08-31  6:56   ` Alexis
2020-08-30 10:01 ` Laurent Bercot
2020-08-31  7:01   ` Alexis
2020-08-31 11:04     ` Laurent Bercot
2020-08-31 14:29   ` Guillermo
2020-09-01 10:00     ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Laurent Bercot
2020-09-01 19:24       ` possible s6-rc redesign mobinmob
2020-09-01 22:16         ` Dudemanguy
2020-09-01 22:20         ` Laurent Bercot
2020-09-02  9:41           ` mobinmob
2020-09-02 12:14             ` Laurent Bercot
2020-09-01 23:14       ` possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7)) Steve Litt
2020-08-31 16:08   ` [request for review] Port of s6 documentation to mdoc(7) J. Lewis Muir
2020-08-31 17:45     ` Jason Lenz
2020-08-31 19:14       ` J. Lewis Muir
2020-08-31 20:51         ` Laurent Bercot
2020-09-01  6:38           ` Casper Ti. Vector
2020-09-01  9:03             ` Alexis
2020-09-01  9:20               ` Casper Ti. Vector
2020-09-01 10:02                 ` Alexis
2020-09-01 10:15                   ` Casper Ti. Vector
2020-09-01 20:13               ` Steve Litt
2020-09-02  0:50                 ` Alexis
     [not found]           ` <20200901063801.GA2158@caspervector>
2020-09-01 10:11             ` Laurent Bercot
2020-09-01 11:28               ` Casper Ti. Vector
2020-09-01 11:55               ` Alexis
2020-08-31 19:36     ` Laurent Bercot
2020-08-31 19:58       ` J. Lewis Muir

supervision - discussion about system services, daemon supervision, init, runlevel management, and tools such as s6 and runit

This inbox may be cloned and mirrored by anyone:

	git clone --mirror http://inbox.vuxu.org/supervision

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 supervision supervision/ http://inbox.vuxu.org/supervision \
		subscribe@list.skarnet.org
	public-inbox-index supervision

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.vuxu.org/vuxu.archive.supervision.general


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git