[Ksummit-discuss] [CORE TOPIC] Documentation

[Michael Kerrisk (man-pages)]

On 08/04/2015 10:33 AM, Peter Huewe wrote:
> Hi
> 
> Am 4. August 2015 09:42:55 MESZ, schrieb Marcel Holtmann <marcel at holtmann.org>:
>> 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/