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: [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.

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