[RFC 10/10] Documentation: build asciidoc documentation

[Jani Nikula]

Finally wrap up all the work in the preceding patches, and generate a
pipeline from asciidoc documentation as part of the DocBook
documentation.

The biggest difference in building DocBook xml from asciidoc compared to
the docproc pipeline is the use of intermediate asciidoc snippets for
the kernel-doc generated documentation, their inclusion into the source
asciidoc using the markup's own directives, with the dependencies set
right.

This is a big improvement in the build process:

First, kernel-doc is only called on the source files that have actually
changed. (Also, asciidoc is only called on the high level documents
where the included documentation has actually changed.)

Second, all of the kernel-doc processing parallelizes.

The xmlto proessing of the result is still slow, but the build time
improvement for the kernel-doc/asciidoc part is huge.

It's not yet all rosy though:

- The intermediate files should be put in a separate subdirectory
  instead of DocBook where it pollutes everything. Sorry, this is rather
  ugly now.

- The clean targets don't work properly.

- Some of the choices made in kernel-doc asciidoc support looked
  beautiful with the default asciidoc html output; however the DocBook
  pipeline is a different beast with different templates, and it's not
  so pretty anymore. (Particularly the numbered "tables" for parameters
  are ugly.)

- The cross-referencing probably needs more looking into. I think I've
  seen some weird stuff there. Also, since the kernel-doc asciidoc turns
  everything into xrefs, the later cross-referencing stage complains
  about dead links.

NOTE: When switching between this and master, be sure to clean the
Documentation/DocBook/*.cmd files. They don't seem to depend right, and
wasted me a few hours debugging my makefiles.

Signed-off-by: Jani Nikula <jani.nikula@xxxxxxxxx>
---
 Documentation/DocBook/Makefile | 37 +++++++++++++++++++++++++++++--------
 Documentation/DocBook/gpu.txt  |  2 +-
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index d70f9b68174e..aed990080aba 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -4,7 +4,9 @@
 # See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
 # to document the SRC - and how to read it.
 # To add a new book the only step required is to add the book to the
-# list of DOCBOOKS.
+# list of DOCBOOKS or ASCIIDOC_BOOKS.
+
+ASCIIDOC_BOOKS := gpu.txt
 
 DOCBOOKS := z8530book.xml device-drivers.xml \
 	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
@@ -14,18 +16,19 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
 	    80211.xml debugobjects.xml sh.xml regulator.xml \
 	    alsa-driver-api.xml writing-an-alsa-driver.xml \
-	    tracepoint.xml gpu.xml media_api.xml w1.xml \
-	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
+	    tracepoint.xml media_api.xml w1.xml \
+	    writing_musb_glue_layer.xml crypto-API.xml iio.xml \
+	    $(ASCIIDOC_BOOKS:%.txt=%.xml)
 
 include Documentation/DocBook/media/Makefile
 
 ###
 # The build process is as follows (targets):
-#              (xmldocs) [by docproc]
-# file.tmpl --> file.xml +--> file.ps   (psdocs)   [by db2ps or xmlto]
-#                        +--> file.pdf  (pdfdocs)  [by db2pdf or xmlto]
-#                        +--> DIR=file  (htmldocs) [by xmlto]
-#                        +--> man/      (mandocs)  [by xmlto]
+#                (xmldocs) [by docproc or asciidoc]
+# file.tmpl -+               +--> file.ps   (psdocs)   [by db2ps or xmlto]
+#            +--> file.xml --+--> file.pdf  (pdfdocs)  [by db2pdf or xmlto]
+# file.txt  -+               +--> DIR=file  (htmldocs) [by xmlto]
+#                            +--> man/      (mandocs)  [by xmlto]
 
 
 # for PDF and PS output you can choose between xmlto and docbook-utils tools
@@ -69,6 +72,9 @@ KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
 KERNELDOC       = $(srctree)/scripts/kernel-doc
 DOCPROC         = $(objtree)/scripts/docproc
 CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype
+ASCIIDOC_INCLUDES	= $(srctree)/scripts/asciidoc-includes
+KERNELDOC_DEPS		= $(srctree)/scripts/kernel-doc-deps
+KERNELDOC_HELPER	= $(srctree)/scripts/kernel-doc-helper
 
 # Use a fixed encoding - UTF-8 if the C library has support built-in
 # or ASCII if not
@@ -79,6 +85,21 @@ XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
 
 ###
+# Docbook pipeline for asciidoc and asciidoctor (both should work).
+%.xml: %.txt
+	asciidoctor -b docbook -o $@ $<
+
+# Generate dependencies and rules for building intermediate asciidoc files
+# included from the asciidoc high level documents. The intermediate files are
+# generated from kernel sources using kernel-doc, according to the file names
+# and suffixes in the asciidoc high level documents.
+%.deps: %.txt
+	$(ASCIIDOC_INCLUDES) < $< | $(KERNELDOC_DEPS) -k $(KERNELDOC) -t $(KERNELDOC_HELPER) -s $(srctree) -d $(obj) -m $(@:%.deps=%.xml) > $@
+
+# Include (and generate as necessary) the dependencies.
+-include $(addprefix $(obj)/,$(ASCIIDOC_BOOKS:%.txt=%.deps))
+
+###
 # DOCPROC is used for two purposes:
 # 1) To generate a dependency list for a .tmpl file
 # 2) To preprocess a .tmpl file and call kernel-doc with
diff --git a/Documentation/DocBook/gpu.txt b/Documentation/DocBook/gpu.txt
index 71aa1473461e..9ba9247d1c43 100644
--- a/Documentation/DocBook/gpu.txt
+++ b/Documentation/DocBook/gpu.txt
@@ -6,7 +6,7 @@ The Linux DRM layer contains code intended to support the needs of complex graph
 
 A note on versions: this guide covers features found in the DRM tree, including the TTM memory manager, output configuration and mode setting, and the new vblank internals, in addition to all the regular features found in current kernels.
 
-[Insert diagram of typical DRM stack here]
+// Insert diagram of typical DRM stack here
 
 == Style Guidelines
 
-- 
2.1.4