From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.8 required=5.0 tests=MAILING_LIST_MULTI, NICE_REPLY_A autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 23395 invoked from network); 31 Aug 2020 17:46:06 -0000 Received: from alyss.skarnet.org (95.142.172.232) by inbox.vuxu.org with ESMTPUTF8; 31 Aug 2020 17:46:06 -0000 Received: (qmail 31529 invoked by uid 89); 31 Aug 2020 17:46:31 -0000 Mailing-List: contact supervision-help@list.skarnet.org; run by ezmlm Sender: Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Received: (qmail 31521 invoked from network); 31 Aug 2020 17:46:31 -0000 X-Zone-Loop: 1ac31d514ad486c004a7a00896cb8502e86831b82540 X-Originating-IP: [149.28.56.236] Subject: Re: [request for review] Port of s6 documentation to mdoc(7) To: "J. Lewis Muir" , Laurent Bercot Cc: supervision@list.skarnet.org References: <877dtgtu1z.fsf@ada> <20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org> From: Jason Lenz Message-ID: Date: Mon, 31 Aug 2020 12:45:52 -0500 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.11.0 MIME-Version: 1.0 In-Reply-To: <20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-Language: en-US X-AuthUser: jason@lenzplace.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