summaryrefslogtreecommitdiff
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorBen Hutchings <ben@decadent.org.uk>2015-07-08 22:07:05 +0300
committerJonathan Corbet <corbet@lwn.net>2015-07-10 20:03:21 +0300
commitb44158b17099ed5c7c8f4bfb7029942adbfbc318 (patch)
treebf9265f8010b3177c1f2625e0982e509f3c80e97 /Documentation/DocBook
parentb48ed85145711b28f9024dcdaf6c0238d7b5042c (diff)
downloadlinux-b44158b17099ed5c7c8f4bfb7029942adbfbc318.tar.xz
DocBook: Avoid building man pages repeatedly and inconsistently
Some kernel-doc sections are included in multiple DocBook files. This means the mandocs target will generate the same manual page multiple times with different metadata (author name/address and manual title, taken from the including DocBook file). If it's invoked in a parallel build, the output is nondeterminstic. For each section that is duplicated, mark the less specific manual's inclusion as 'extra' and exclude it during conversion to manual pages. Use xmlif for this, as that is bundled with xmlto which we already use. I would have preferred to use more conventional markup for this, but each of the following approaches failed: 1. Wrap the extra inclusions with a new element and add a template to the stylesheet to include/exclude them. Unfortunately DocBook XSL doesn't seem to support foreign elements at an intermediate level in the document tree. 2. Use DocBook profiling. This works but requires passing an absolute path to the profile stylesheet to xmlto, so it's not portable. 3. Use SGML marked sections. docbook2x can handle these but xmlto chokes on them. Reported-by: Jérémy Bobbio <lunar@debian.org> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/Makefile10
-rw-r--r--Documentation/DocBook/device-drivers.tmpl6
-rw-r--r--Documentation/DocBook/gadget.tmpl3
-rw-r--r--Documentation/DocBook/kernel-api.tmpl6
4 files changed, 24 insertions, 1 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 11a41456b943..83fcb6c2a00f 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -56,6 +56,13 @@ htmldocs: $(HTML)
MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN)
+ @dups=$$(sed -n 's/.*<refname>\([^<]*\)<\/refname>.*/\1/p' \
+ $(obj)/*.xml.noextra | sort | uniq -d); \
+ if [ -n "$$dups" ]; then \
+ echo >&2 "The following manual pages are generated more than once:"; \
+ printf >&2 '%s\n' "$$dups"; \
+ exit 1; \
+ fi
find $(obj)/man -name '*.9' | xargs gzip -nf
installmandocs: mandocs
@@ -150,7 +157,7 @@ quiet_cmd_db2html = HTML $@
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
quiet_cmd_db2man = MAN $@
- cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi
+ cmd_db2man = if grep -q refentry $<; then xmlif excludeextra=1 <$< >$<.noextra && xmlto man $(XMLTOFLAGS) -o $(obj)/man $<.noextra ; fi
%.9 : %.xml
@(which xmlto > /dev/null 2>&1) || \
(echo "*** You need to install xmlto ***"; \
@@ -217,6 +224,7 @@ clean-files := $(DOCBOOKS) \
$(patsubst %.xml, %.ps, $(DOCBOOKS)) \
$(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
$(patsubst %.xml, %.html, $(DOCBOOKS)) \
+ $(patsubst %, %.noextra, $(DOCBOOKS)) \
$(patsubst %.xml, %.9, $(DOCBOOKS)) \
$(index)
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index faf09d4a0ea8..87853ea1f70b 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -194,8 +194,13 @@ X!Edrivers/pnp/system.c
<chapter id="snddev">
<title>Sound Devices</title>
+<?xmlif if excludeextra='1'?>
+<?xmlif else?>
!Iinclude/sound/core.h
+<?xmlif fi?>
!Esound/sound_core.c
+<?xmlif if excludeextra='1'?>
+<?xmlif else?>
!Iinclude/sound/pcm.h
!Esound/core/pcm.c
!Esound/core/device.c
@@ -211,6 +216,7 @@ X!Edrivers/pnp/system.c
!Esound/core/hwdep.c
!Esound/core/pcm_native.c
!Esound/core/memalloc.c
+<?xmlif fi?>
<!-- FIXME: Removed for now since no structured comments in source
X!Isound/sound_firmware.c
-->
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
index 641629221176..e1b87bd63f82 100644
--- a/Documentation/DocBook/gadget.tmpl
+++ b/Documentation/DocBook/gadget.tmpl
@@ -488,7 +488,10 @@ These are the same types and constants used by host
side drivers (and usbcore).
</para>
+<?xmlif if excludeextra='1'?>
+<?xmlif else?>
!Iinclude/linux/usb/ch9.h
+<?xmlif fi?>
</sect1>
<sect1 id="core"><title>Core Objects and Methods</title>
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
index ecfd0ea40661..722249a0dbfe 100644
--- a/Documentation/DocBook/kernel-api.tmpl
+++ b/Documentation/DocBook/kernel-api.tmpl
@@ -58,8 +58,11 @@
<sect1><title>String Conversions</title>
!Elib/vsprintf.c
+<?xmlif if excludeextra='1'?>
+<?xmlif else?>
!Finclude/linux/kernel.h kstrtol
!Finclude/linux/kernel.h kstrtoul
+<?xmlif fi?>
!Elib/kstrtox.c
</sect1>
<sect1><title>String Manipulation</title>
@@ -178,7 +181,10 @@ X!Ekernel/module.c
<chapter id="hardware">
<title>Hardware Interfaces</title>
<sect1><title>Interrupt Handling</title>
+<?xmlif if excludeextra='1'?>
+<?xmlif else?>
!Ekernel/irq/manage.c
+<?xmlif fi?>
</sect1>
<sect1><title>DMA Channels</title>