[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 wrote: > >> To ease the navigation in the documentation we should use 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 from the DocBook XML to generate a database. Then it looks >> for , and 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 >
[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 wrote: > To ease the navigation in the documentation we should use 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 from the DocBook XML to generate a database. Then it looks > for , and 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
[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 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 from the DocBook XML to generate a database. Then it looks > for , and 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 > Cc: Randy Dunlap > Cc: Daniel Vetter > Cc: Laurent Pinchart > Cc: Jonathan Corbet > Cc: Herbert Xu > Cc: Stephan Mueller > Cc: Michal Marek > Cc: linux-kernel at vger.kernel.org > Cc: linux-doc at vger.kernel.org > Cc: intel-gfx > Cc: dri-devel 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 > --- > 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 ' \ > $(patsubst %.html,%,$(notdir $@))' > $@ > +%.aux.xml: %.xml > + @rm -rf $@ > + (cat $< | egrep "^ > $<.db) > + $(KERNELDOCXMLREF) -db $<.db $< > $@ > > -%.html: %.xml > +%.html: %.aux.xml > @(which xmlto > /dev/null 2>&1) || \ >(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
[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 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 from the DocBook XML to generate a database. Then it looks
for , and 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
Cc: Randy Dunlap
Cc: Daniel Vetter
Cc: Laurent Pinchart
Cc: Jonathan Corbet
Cc: Herbert Xu
Cc: Stephan Mueller
Cc: Michal Marek
Cc: linux-kernel at vger.kernel.org
Cc: linux-doc at vger.kernel.org
Cc: intel-gfx
Cc: dri-devel
---
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 ' \
$(patsubst %.html,%,$(notdir $@))' > $@
+%.aux.xml: %.xml
+ @rm -rf $@
+ (cat $< | egrep "^
$<.db)
+ $(KERNELDOCXMLREF) -db $<.db $< > $@
-%.html:%.xml
+%.html:%.aux.xml
@(which xmlto > /dev/null 2>&1) || \
(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.
+#
+# usage:
+# kernel-doc-xml-ref -db filename
+# xml filename > outputfile
+
+# read arguments
+if ($#ARGV != 2) {
+ usage();
+}
+
+#Holds the database filename
+my $databasefile;
+my @database;
+
+#holds the inputfile
+my $inputfile;
+my $errors = 0;
+
+my %highlights = (
+ "(.*?)",
+ "\"\" . convert_function(\$1,
