subject:"\[PATCH\] scripts\/kernel\-doc\: Adding cross\-reference links to html documentation."

[PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.

2015-06-26 Thread Danilo Cesar Lemes de Paula

On 06/24/2015 06:22 PM, Daniel Vetter wrote:
> On Wed, Jun 24, 2015 at 04:10:24PM -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: 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
> 
> Already discussed on irc With Danilo but here for the record: I really
> like this since it massively improves the usefulness of the docbooks we
> have. One small thing I noticed though while clicking a bit more through
> the generated html: It also generates selflinks, i.e. drm_crtc_vblank_on
> links to itself. That one is a bit confusing. Could we filter out
> self-links somehow on the reference sections?

Yes we could! I'm sending a reviewed patch in a few minutes.

- Danilo Cesar

> -Daniel
> 
>>
>>  Documentation/DocBook/Makefile |  34 +---
>>  scripts/kernel-doc-xml-ref | 176 
>> +
>>  2 files changed, 197 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..756e897
>> --- /dev/null
>> +++ b/scripts/kernel-doc-xml-ref
>> @@ -0,0 +1,176 @@
>> +#!/usr/bin/perl -w
>> +
>> +use st

[PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.

2015-06-24 Thread Daniel Vetter

On Wed, Jun 24, 2015 at 04:10:24PM -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: 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

Already discussed on irc With Danilo but here for the record: I really
like this since it massively improves the usefulness of the docbooks we
have. One small thing I noticed though while clicking a bit more through
the generated html: It also generates selflinks, i.e. drm_crtc_vblank_on
links to itself. That one is a bit confusing. Could we filter out
self-links somehow on the reference sections?
-Daniel

> 
>  Documentation/DocBook/Makefile |  34 +---
>  scripts/kernel-doc-xml-ref | 176 
> +
>  2 files changed, 197 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..756e897
> --- /dev/null
> +++ b/scripts/kernel-doc-xml-ref
> @@ -0,0 +1,176 @@
> +#!/usr/bin/perl -w
> +
> +use strict;
> +
> +## Copyright (C) 2015  Intel Corporation ##
> +###
> +## This software falls under the GNU General Public License.

[PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.

2015-06-24 Thread Danilo Cesar Lemes de Paula

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: 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 | 176 +
 2 files changed, 197 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..756e897
--- /dev/null
+++ b/scripts/kernel-doc-xml-ref
@@ -0,0 +1,176 @@
+#!/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) . \"\"",
+   "(.*?)",
+   "\"\" . convert_struct(\$1) . \"\"",
+   "(.*?)(.*?)",
+   "\"\" .

[PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.

[PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.

[PATCH] scripts/kernel-doc: Adding cross-reference links to html documentation.

3 matches

Site Navigation

Mail list logo

Footer information