From 32c1735c4091ef0de8e39f68a9d83a07450b959b Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:06:44 +0100 Subject: DocBook: Don't store mtime (or name) in compressed man pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The mtime on a man page is the build time. As gzip stores the mtime and original name in the compressed file by default, this makes compressed man pages unreproducible. Neither of these are important metadata in this case, so turn this off. Reported-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b6a6a2e0dd3b..11a41456b943 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -56,7 +56,7 @@ htmldocs: $(HTML) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) - find $(obj)/man -name '*.9' | xargs gzip -f + find $(obj)/man -name '*.9' | xargs gzip -nf installmandocs: mandocs mkdir -p /usr/local/man/man9/ -- cgit From b48ed85145711b28f9024dcdaf6c0238d7b5042c Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:06:51 +0100 Subject: DocBook: Generate consistent IDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit By default, DocBook XSL uses a non-deterministic function to generate IDs for HTML elements where it can't take a name from the input document. However, it has the option to generate 'consistent' (deterministic) IDs instead. Enable this to make the HTML pages reproducible. Reported-by: Jérémy Bobbio Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- Documentation/DocBook/stylesheet.xsl | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 85b25275196f..3bf4ecf3d760 100644 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -5,6 +5,7 @@ 80 0 +1 2 1 -- cgit From b44158b17099ed5c7c8f4bfb7029942adbfbc318 Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Wed, 8 Jul 2015 20:07:05 +0100 Subject: DocBook: Avoid building man pages repeatedly and inconsistently MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Ben Hutchings Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 10 +++++++++- Documentation/DocBook/device-drivers.tmpl | 6 ++++++ Documentation/DocBook/gadget.tmpl | 3 +++ Documentation/DocBook/kernel-api.tmpl | 6 ++++++ 4 files changed, 24 insertions(+), 1 deletion(-) (limited to 'Documentation/DocBook') 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>.*/\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 Sound Devices + + !Iinclude/sound/core.h + !Esound/sound_core.c + + !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 + 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). + + !Iinclude/linux/usb/ch9.h + Core Objects and Methods 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 @@ String Conversions !Elib/vsprintf.c + + !Finclude/linux/kernel.h kstrtol !Finclude/linux/kernel.h kstrtoul + !Elib/kstrtox.c String Manipulation @@ -178,7 +181,10 @@ X!Ekernel/module.c Hardware Interfaces Interrupt Handling + + !Ekernel/irq/manage.c + DMA Channels -- cgit From e9c9963b439db734e9705f96909c5a3388dd81bb Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 6 Aug 2015 12:44:23 -0600 Subject: Revert "DocBook: Avoid building man pages repeatedly and inconsistently" This reverts commit b44158b17099ed5c7c8f4bfb7029942adbfbc318. This commit introduced warnings and possibly inconsistent results into the doc build process. The goal is good but it will need to be achieved another way. Reported-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 10 +--------- Documentation/DocBook/device-drivers.tmpl | 6 ------ Documentation/DocBook/gadget.tmpl | 3 --- Documentation/DocBook/kernel-api.tmpl | 6 ------ 4 files changed, 1 insertion(+), 24 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 83fcb6c2a00f..11a41456b943 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -56,13 +56,6 @@ htmldocs: $(HTML) MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) - @dups=$$(sed -n 's/.*\([^<]*\)<\/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 @@ -157,7 +150,7 @@ quiet_cmd_db2html = HTML $@ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi quiet_cmd_db2man = MAN $@ - cmd_db2man = if grep -q refentry $<; then xmlif excludeextra=1 <$< >$<.noextra && xmlto man $(XMLTOFLAGS) -o $(obj)/man $<.noextra ; fi + cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi %.9 : %.xml @(which xmlto > /dev/null 2>&1) || \ (echo "*** You need to install xmlto ***"; \ @@ -224,7 +217,6 @@ 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 87853ea1f70b..faf09d4a0ea8 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -194,13 +194,8 @@ X!Edrivers/pnp/system.c Sound Devices - - !Iinclude/sound/core.h - !Esound/sound_core.c - - !Iinclude/sound/pcm.h !Esound/core/pcm.c !Esound/core/device.c @@ -216,7 +211,6 @@ X!Edrivers/pnp/system.c !Esound/core/hwdep.c !Esound/core/pcm_native.c !Esound/core/memalloc.c - diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index e1b87bd63f82..641629221176 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -488,10 +488,7 @@ These are the same types and constants used by host side drivers (and usbcore). - - !Iinclude/linux/usb/ch9.h - Core Objects and Methods diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 722249a0dbfe..ecfd0ea40661 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -58,11 +58,8 @@ String Conversions !Elib/vsprintf.c - - !Finclude/linux/kernel.h kstrtol !Finclude/linux/kernel.h kstrtoul - !Elib/kstrtox.c String Manipulation @@ -181,10 +178,7 @@ X!Ekernel/module.c Hardware Interfaces Interrupt Handling - - !Ekernel/irq/manage.c - DMA Channels -- cgit