Re: [Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.
On Fri, 26 Jun 2015 12:08:57 -0300 Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote: To ease the navigation in the documentation we should use links inside those tags so readers can easily jump between methods directly. This was discussed in 2014[1] and is implemented by getting a list of refentries from the DocBook XML to generate a database. Then it looks for function,structnames and paramdef tags that matches the ones in the database. As it only links existent references, no broken links are added. So I put a lot more time into this today than I really had available. I think it's cool stuff, and we definitely want it. But can I ask for one more pass? In particular: - It makes the docs build a lot more noisy, that would be nice to fix. - A bit more documentation in the script would be nice. It also is happy to run with silly arguments; a detail since nobody will run it directly, but still... - Most importantly, it breaks make htmldocs; in particular, vast amounts of error spew results when it gets around to media_api.html. I spent a while trying to figure out what was going on but didn't come up with anything conclusive; my suspicion is that it has to do with the separate makefile in Documentation/DocBook/media/. Thanks, jon ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.
On 07/09/2015 08:56 PM, Jonathan Corbet wrote: On Fri, 26 Jun 2015 12:08:57 -0300 Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk wrote: To ease the navigation in the documentation we should use links inside those tags so readers can easily jump between methods directly. This was discussed in 2014[1] and is implemented by getting a list of refentries from the DocBook XML to generate a database. Then it looks for function,structnames and paramdef tags that matches the ones in the database. As it only links existent references, no broken links are added. So I put a lot more time into this today than I really had available. I Thanks, I really appreciate that. think it's cool stuff, and we definitely want it. But can I ask for one more pass? In particular: - It makes the docs build a lot more noisy, that would be nice to fix. Fair enough. It was showing all the commands. I did change that to a fancy XMLREF Documentation/DocBook/FooBar.xml message. - A bit more documentation in the script would be nice. It also is happy to run with silly arguments; a detail since nobody will run it directly, but still... I did improve the documentation and also fixed the silly argument thing. - Most importantly, it breaks make htmldocs; in particular, vast amounts of error spew results when it gets around to media_api.html. I spent a while trying to figure out what was going on but didn't come up with anything conclusive; my suspicion is that it has to do with the separate makefile in Documentation/DocBook/media/. I'm not sure about this. media-api is spitting lots of warnings with or without the documentation patch. I compared the number of files and they're the same (excepting those auxiliary db files). For me, both builds actually spits 2825 lines on STDERR... I also did a smoke check in the media-api html documentation and it looks fine. Would you mind to check again if it happens with the v3 of my patch I'm sending next? Danilo Thanks, jon ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.
On Fri, Jun 26, 2015 at 12:08:57PM -0300, Danilo Cesar Lemes de Paula wrote: Functions, Structs and Parameters definitions on kernel documentation are pure cosmetic, it only highlights the element. To ease the navigation in the documentation we should use links inside those tags so readers can easily jump between methods directly. This was discussed in 2014[1] and is implemented by getting a list of refentries from the DocBook XML to generate a database. Then it looks for function,structnames and paramdef tags that matches the ones in the database. As it only links existent references, no broken links are added. [1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk Cc: Randy Dunlap rdun...@infradead.org Cc: Daniel Vetter daniel.vet...@ffwll.ch Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com Cc: Jonathan Corbet cor...@lwn.net Cc: Herbert Xu herb...@gondor.apana.org.au Cc: Stephan Mueller smuel...@chronox.de Cc: Michal Marek mma...@suse.cz Cc: linux-ker...@vger.kernel.org Cc: linux-...@vger.kernel.org Cc: intel-gfx intel-gfx@lists.freedesktop.org Cc: dri-devel dri-de...@lists.freedesktop.org I'm using this now to generate the drm docbook and I think it's a great improvement for them. No r-b since I can't really perl. Acked-by: Daniel Vetter daniel.vet...@ffwll.ch --- To understand a bit more of what this patch is trying to acomplish you can find two examples of the old and new htmldocs outputs: OLD: https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-crtc-vblank-on.html NEW: https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-crtc-vblank-on.html Documentation/DocBook/Makefile | 34 +--- scripts/kernel-doc-xml-ref | 181 + 2 files changed, 202 insertions(+), 13 deletions(-) create mode 100755 scripts/kernel-doc-xml-ref diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b6a6a2e..8aea45a 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -64,8 +64,9 @@ installmandocs: mandocs ### #External programs used -KERNELDOC = $(srctree)/scripts/kernel-doc -DOCPROC = $(objtree)/scripts/docproc +KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/docproc XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl XMLTOFLAGS += --skip-validation @@ -89,7 +90,7 @@ define rule_docproc ) $(dir $@).$(notdir $@).cmd endef -%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE +%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE $(call if_changed_rule,docproc) # Tell kbuild to always build the programs @@ -139,8 +140,12 @@ quiet_cmd_db2html = HTML$@ cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $ \ echo 'a HREF=$(patsubst %.html,%,$(notdir $@))/index.html \ $(patsubst %.html,%,$(notdir $@))/ap' $@ +%.aux.xml: %.xml + @rm -rf $@ + (cat $ | egrep ^refentry id | egrep -o \.*\ | cut -f 2 -d \ $.db) + $(KERNELDOCXMLREF) -db $.db $ $@ -%.html: %.xml +%.html: %.aux.xml @(which xmlto /dev/null 21) || \ (echo *** You need to install xmlto ***; \ exit 1) @@ -209,15 +214,18 @@ dochelp: ### # Temporary files left by various tools clean-files := $(DOCBOOKS) \ - $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ - $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ - $(patsubst %.xml, %.log, $(DOCBOOKS)) \ - $(patsubst %.xml, %.out, $(DOCBOOKS)) \ - $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ - $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ - $(patsubst %.xml, %.html, $(DOCBOOKS)) \ - $(patsubst %.xml, %.9,$(DOCBOOKS)) \ + $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ + $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ + $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ + $(patsubst %.xml, %.log, $(DOCBOOKS)) \ + $(patsubst %.xml, %.out, $(DOCBOOKS)) \ + $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ + $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ + $(patsubst %.xml, %.html,$(DOCBOOKS)) \ + $(patsubst %.xml, %.9, $(DOCBOOKS)) \ + $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ $(index) clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref new file mode 100755 index 000..c61cdad --- /dev/null +++ b/scripts/kernel-doc-xml-ref @@ -0,0 +1,181 @@ +#!/usr/bin/perl -w + +use strict; + +## Copyright (C) 2015 Intel Corporation ## +#
[Intel-gfx] [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation.
Functions, Structs and Parameters definitions on kernel documentation are pure cosmetic, it only highlights the element. To ease the navigation in the documentation we should use links inside those tags so readers can easily jump between methods directly. This was discussed in 2014[1] and is implemented by getting a list of refentries from the DocBook XML to generate a database. Then it looks for function,structnames and paramdef tags that matches the ones in the database. As it only links existent references, no broken links are added. [1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html Signed-off-by: Danilo Cesar Lemes de Paula danilo.ce...@collabora.co.uk Cc: Randy Dunlap rdun...@infradead.org Cc: Daniel Vetter daniel.vet...@ffwll.ch Cc: Laurent Pinchart laurent.pinch...@ideasonboard.com Cc: Jonathan Corbet cor...@lwn.net Cc: Herbert Xu herb...@gondor.apana.org.au Cc: Stephan Mueller smuel...@chronox.de Cc: Michal Marek mma...@suse.cz Cc: linux-ker...@vger.kernel.org Cc: linux-...@vger.kernel.org Cc: intel-gfx intel-gfx@lists.freedesktop.org Cc: dri-devel dri-de...@lists.freedesktop.org --- To understand a bit more of what this patch is trying to acomplish you can find two examples of the old and new htmldocs outputs: OLD: https://people.collabora.com/~danilo/intel/Documentation.old/DocBook/drm/API-drm-crtc-vblank-on.html NEW: https://people.collabora.com/~danilo/intel/Documentation.new/DocBook/drm/API-drm-crtc-vblank-on.html Documentation/DocBook/Makefile | 34 +--- scripts/kernel-doc-xml-ref | 181 + 2 files changed, 202 insertions(+), 13 deletions(-) create mode 100755 scripts/kernel-doc-xml-ref diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index b6a6a2e..8aea45a 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -64,8 +64,9 @@ installmandocs: mandocs ### #External programs used -KERNELDOC = $(srctree)/scripts/kernel-doc -DOCPROC = $(objtree)/scripts/docproc +KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/docproc XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl XMLTOFLAGS += --skip-validation @@ -89,7 +90,7 @@ define rule_docproc ) $(dir $@).$(notdir $@).cmd endef -%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE +%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE $(call if_changed_rule,docproc) # Tell kbuild to always build the programs @@ -139,8 +140,12 @@ quiet_cmd_db2html = HTML$@ cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $ \ echo 'a HREF=$(patsubst %.html,%,$(notdir $@))/index.html \ $(patsubst %.html,%,$(notdir $@))/ap' $@ +%.aux.xml: %.xml + @rm -rf $@ + (cat $ | egrep ^refentry id | egrep -o \.*\ | cut -f 2 -d \ $.db) + $(KERNELDOCXMLREF) -db $.db $ $@ -%.html:%.xml +%.html:%.aux.xml @(which xmlto /dev/null 21) || \ (echo *** You need to install xmlto ***; \ exit 1) @@ -209,15 +214,18 @@ dochelp: ### # Temporary files left by various tools clean-files := $(DOCBOOKS) \ - $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ - $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ - $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ - $(patsubst %.xml, %.log, $(DOCBOOKS)) \ - $(patsubst %.xml, %.out, $(DOCBOOKS)) \ - $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ - $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ - $(patsubst %.xml, %.html, $(DOCBOOKS)) \ - $(patsubst %.xml, %.9,$(DOCBOOKS)) \ + $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ + $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ + $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ + $(patsubst %.xml, %.log, $(DOCBOOKS)) \ + $(patsubst %.xml, %.out, $(DOCBOOKS)) \ + $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ + $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ + $(patsubst %.xml, %.html,$(DOCBOOKS)) \ + $(patsubst %.xml, %.9, $(DOCBOOKS)) \ + $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ $(index) clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man diff --git a/scripts/kernel-doc-xml-ref b/scripts/kernel-doc-xml-ref new file mode 100755 index 000..c61cdad --- /dev/null +++ b/scripts/kernel-doc-xml-ref @@ -0,0 +1,181 @@ +#!/usr/bin/perl -w + +use strict; + +## Copyright (C) 2015 Intel Corporation ## +### +## This software falls under the GNU General Public License. ## +## Please read the COPYING file for more information ## +# +# +# This software reads a XML file and a list of valid interal +# references to replace Docbook tags with links.
