[Ksummit-discuss] [CORE TOPIC] Documentation

[josh at joshtriplett.org]

On Wed, Aug 05, 2015 at 07:08:04PM +0200, Michael Kerrisk (man-pages) wrote:
> 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.

I've seen multiple scripts to convert mdwn to groff for manual pages.
And once you have groff, you can typeset PDFs from that, right?

The biggest thing I've noticed about asciidoc is that it seems to be
incredibly *slow*.  For all the projects I know of that use it, building
the documentation is by far the slowest part of the build process.

Honestly, groff isn't *that* hard to deal with.

- Josh Triplett