Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis]

Steve Litt  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:


   
s6-envuidgid [ -u | -g | -B ] [ -n ] [ -i | -D 
uid:gid:gidlist ] 
account prog...

   


Alexis.

Re: possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7))

[Steve Litt]

On Tue, 01 Sep 2020 10:00:22 +
"Laurent Bercot"  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 order (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 

Re: [request for review] Port of s6 documentation to mdoc(7)

[Steve Litt]

On Tue, 01 Sep 2020 19:03:36 +1000
Alexis  wrote:

> Casper Ti. Vector  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 .

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 , 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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis]

Laurent Bercot  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,  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.

Re: [request for review] Port of s6 documentation to mdoc(7)

[Casper Ti. Vector]

On Tue, Sep 01, 2020 at 10:11:14AM +, 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] 
(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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Casper Ti. Vector]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Laurent Bercot]

* 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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis]

Casper Ti. Vector  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.

possible s6-rc redesign (was: [request for review] Port of s6 documentation to mdoc(7))

[Laurent Bercot]

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 

Re: [request for review] Port of s6 documentation to mdoc(7)

[Casper Ti. Vector]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis]

Casper Ti. Vector  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.

Re: [request for review] Port of s6 documentation to mdoc(7)

[Casper Ti. Vector]

On Mon, Aug 31, 2020 at 08:51:34PM +, 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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Laurent Bercot]

 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

Re: [request for review] Port of s6 documentation to mdoc(7)

[J. Lewis Muir]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Laurent Bercot]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[J. Lewis Muir]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Jason Lenz]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[J. Lewis Muir]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Guillermo]

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.

Re: [request for review] Port of s6 documentation to mdoc(7)

[Laurent Bercot]

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 long 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

Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis]

Laurent Bercot  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.

Re: [request for review] Port of s6 documentation to mdoc(7)

[Alexis]

eric vidal  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.

Re: [request for review] Port of s6 documentation to mdoc(7)

[Laurent Bercot]

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

Re: [request for review] Port of s6 documentation to mdoc(7)

[eric vidal]

On Sun, 30 Aug 2020 18:30:16 +1000
Alexis  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 

[request for review] Port of s6 documentation to mdoc(7)

[Alexis]

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.