| 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
| ||
|
Date: Tue, 26 Jan 2016 14:08:55 +0200 From: Jani Nikula <jani.nikula@...el.com> To: Jonathan Corbet <corbet@....net>, 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 10/10] Documentation: build asciidoc documentation 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@...el.com> --- 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
Powered by blists - more mailing lists