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.0 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 12417 invoked from network); 31 Aug 2020 16:08:16 -0000 Received: from alyss.skarnet.org (95.142.172.232) by inbox.vuxu.org with ESMTPUTF8; 31 Aug 2020 16:08:16 -0000 Received: (qmail 30258 invoked by uid 89); 31 Aug 2020 16:08:41 -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 30249 invoked from network); 31 Aug 2020 16:08:41 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=imca-cat-org.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=rbd7ArOo7HpQ7dwXIEA97E3cVSswHKpSpqotCnFZLZo=; b=xe0xT8N9MbofyKUpZpgaeolcMQ/6WADYriCm9ODMZxwJFgCiFjS1CL2x2DZ38v8l7p PsolqTqkiVSXEwKjWV2/Bl8+tn+vapHYEJ6hD1NiXRgilnToJgxQIId6kp9h5Ya57IzG JCxXlR+gO/YZo+oNZxgIYAxFAFDkhNbKK9fWxWnCI6lYw6JA6mSF//MAs//jvGG9lANP qiubZcz+ys56xxysrYhsKY5G3n8kcaQa/yPFKSWWtNuRNW12PQpEkEQrg6COqTBdnuxj HrYW42SZcIzf8gk6OtIynLS56P2y6L9+aemJHX5KAVmWUhfobAQp6MoOLO6acrvkydQZ dnUw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=rbd7ArOo7HpQ7dwXIEA97E3cVSswHKpSpqotCnFZLZo=; b=GxWAvRUoObZKQExOMU0ylzpGDnkqOr/0jo1LyYfxTGmd5xa1l4DWyLFzq/f7o+sx3f xsLHM3gvTiQ97KnR5mX1GUQJ7/ZhK0LAI4MvYVhi1cVZXqfR/BAa/dUOdnMG5YhDjThv 0RI9zPIg1enbwU0EJXCtn2rob0aGaqFU09G6klJzvK3K+i6QsGFGK8AW0AQDZCd7vwb8 tCEw4PFeXp94tJKM5ot6Z4oqsJ4I4/5TNZIDKfBDFgRS72C9WRaazEZlOMqFInstrc2c khVRRD5dWsxlvS+kmkN3NCygk2lRP1JhfWRwPWSJBFGUWJ94PHuW/KCeVtidgmkfvH16 dpjQ== X-Gm-Message-State: AOAM5309qJq8XFWDQe7GrZXA2c9nslWdzDk9qG1uEMdEHzkFNV0dqnQH HDoEmGDLQxw9DJY1h3mKKbK52g== X-Google-Smtp-Source: ABdhPJwH9FJDURnF7lHhV25tI1afZ3VR65jafFyEvWO8Iov1gROKBz2KKZbSPOubYWlZ2FXe0vxG9Q== X-Received: by 2002:a92:4950:: with SMTP id w77mr1839945ila.93.1598890093563; Mon, 31 Aug 2020 09:08:13 -0700 (PDT) Date: Mon, 31 Aug 2020 11:08:11 -0500 From: "J. Lewis Muir" To: Laurent Bercot Cc: supervision@list.skarnet.org Subject: Re: [request for review] Port of s6 documentation to mdoc(7) Message-ID: <20200831160811.6zqdbyjyzk4bembt@mail.imca-cat.org> References: <877dtgtu1z.fsf@ada> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: 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