linux-kernel - [RFC] A first shot at asciidoc-based formatted docs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <1453764522-29030-1-git-send-email-corbet@lwn.net>
Date:	Mon, 25 Jan 2016 16:28:38 -0700
From:	Jonathan Corbet <corbet@....net>
To:	linux-doc@...r.kernel.org
Cc:	linux-kernel@...r.kernel.org, Jani Nikula <jani.nikula@...el.com>,
	Daniel Vetter <daniel.vetter@...ll.ch>
Subject: [RFC] A first shot at asciidoc-based formatted docs

So here is a proof-of-concept series showing how a fully asciidoc-based
toolchain might work.  Lots of hackery here, this isn't meant to be applied
to anything at this point, but it's a good start.  What this series has is:

 - Jani Nikula's patch adding asciidoc output to kernel-doc.  Thanks for
   doing this!  It was the kickstart that was needed to get this process
   going.

 - Tweak docproc to handle asciidoc template files.  If a template ends in
   ".adt", it's an asciidoc template; it's processed pretty much the same
   way, except that kernel-doc gets the -asciidoc argument.

 - Bash on the Makefile to get it to process asciidoc templates into HTML.
   Naturally this was where most of the time got spent.  *Only* HTML output
   works at the moment.

 - Convert tracepoints.html to tpoint.adt as a proof of concept.  It works,
   and the output is much pleasing, IMO.

I'm sure there's a thousand details to deal with, and there is the issue of
the other output formats.  asciidoctor claims to be able to create man
pages, but I've not tried that yet; neither tool will do PDF.  Maybe we
could rely on pandoc to do that.  Otherwise, getting to asciidoc to XML is
straightforward, so it should be possible to use xmlto as is done now.

It's all in the doc/asciidoc branch of git://git.lwn.net/linux.git if
anybody wants to mess with it.

Comments?

jon