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>

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 11a41456b943f38872a000b073b4d56bfa69a319..83fcb6c2a00fd03671d656360868c05bbbcdd153 100644 (file)
--- 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 faf09d4a0ea8b3fe6eb5647ab2e851a922899f7e..87853ea1f70be72b393ad3d2e11047f2d5bc7eda 100644 (file)
--- 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 64162922117651344d698ffd53ece06eafca3324..e1b87bd63f82ad287b94dcac1443b43d5eadca47 100644 (file)
--- 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 ecfd0ea406619b0a2c76071b2024c7219b9c7a6a..722249a0dbfea3796c98a6a9cebc38a518a818a1 100644 (file)
--- 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>