supervision - discussion about system services, daemon supervision, init, runlevel management, and tools such as s6 and runit
 help / color / mirror / Atom feed
From: Jason Lenz <Jason@Lenzplace.org>
To: "J. Lewis Muir" <jlmuir@imca-cat.org>,
	Laurent Bercot <ska-supervision@skarnet.org>
Cc: supervision@list.skarnet.org
Subject: Re: [request for review] Port of s6 documentation to mdoc(7)
Date: Mon, 31 Aug 2020 12:45:52 -0500	[thread overview]
Message-ID: <ce4a975b-c861-74f4-c991-ddb6ba6370fa@Lenzplace.org> (raw)
In-Reply-To: <20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org>

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



  reply	other threads:[~2020-08-31 17:46 UTC|newest]

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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=ce4a975b-c861-74f4-c991-ddb6ba6370fa@Lenzplace.org \
    --to=jason@lenzplace.org \
    --cc=jlmuir@imca-cat.org \
    --cc=ska-supervision@skarnet.org \
    --cc=supervision@list.skarnet.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).