From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 472F37AA for ; Wed, 5 Aug 2015 17:08:10 +0000 (UTC) Received: from mail-wi0-f172.google.com (mail-wi0-f172.google.com [209.85.212.172]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 143CF166 for ; Wed, 5 Aug 2015 17:08:09 +0000 (UTC) Received: by wicgj17 with SMTP id gj17so201147750wic.1 for ; Wed, 05 Aug 2015 10:08:07 -0700 (PDT) Message-ID: <55C242F4.7090005@gmail.com> Date: Wed, 05 Aug 2015 19:08:04 +0200 From: "Michael Kerrisk (man-pages)" MIME-Version: 1.0 To: Peter Huewe , Marcel Holtmann , Michael Ellerman References: <20150801164142.653012af@lwn.net> <1438672367.9418.3.camel@ellerman.id.au> <9B190076-263A-4C51-AFA4-A1D7FD403BC3@holtmann.org> In-Reply-To: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit Cc: ksummit-discuss@lists.linuxfoundation.org Subject: Re: [Ksummit-discuss] [CORE TOPIC] Documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , On 08/04/2015 10:33 AM, Peter Huewe wrote: > Hi > > Am 4. August 2015 09:42:55 MESZ, schrieb Marcel Holtmann : >> Hi Michael, >> >>>> Markdown in one of its many forms might be a good alternative here. >> I'm >>>> also somewhat attracted by Sphinx, which is designed for documenting >> code >>>> already and could probably be made to work well with our existing >> kerneldoc >>>> comments without a whole lot of trouble. The Sphinx idea, though, >> is >>>> hobbled by the inconvenient fact that I've not had the time to >> develop it >>>> far enough to even have a vague idea of whether it would make >> real-world >>>> sense. >>> >>> I'd vote for Markdown. It's very unobtrusive, reads nicely as plain >> text, and >>> all the young kids know it from writing Github README.md files. >> >> actually AsciiDoc might be something to look into as well. >> > I'm also in for AsciiDoc, as it also allows easy generation of Pdfs > and html files, with chapters and all that fancy stuff. > > (Probably the reason why docbook was chosen back then, compared to > the plaintext files) >>From a man-pages point of view, the discussion of tooling is interesting. For some years now I've contemplated a switch from groff's man macros, since some people do not like to work with them (although the basics are pretty simple, IMO). If there was a concerted movement to Asciidoc or Markdown for kernel docs, I'd be willing to invest some effort in the feasibility of switching man-pages to the same format. I'm not knowledgeable in either of those tools, but at a first glance, Asciidoc seems more interesting, since it seems to embrace a wider variety of output formats, in particular, PDF and Linux man-page macros (and also TeX). It doesn't appear that Markdown can do that. I know even less about Sphinx, although its output capabilities, as described at http://sphinx-doc.org/index.html , seem interesting also. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/