Re: [request for review] Port of s6 documentation to mdoc(7)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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.
