| Message ID | 1435173024-19550-1-git-send-email-danilo.cesar@collabora.co.uk (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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 <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.cesar@collabora.co.uk> >> Cc: Randy Dunlap <rdunlap@infradead.org> >> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> >> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> >> Cc: linux-doc@vger.kernel.org >> Cc: intel-gfx <intel-gfx@lists.freedesktop.org> >> Cc: dri-devel <dri-devel@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 > > 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 '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ >> $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ >> +%.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 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 0000000..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 = ( >> + "<function>(.*?)</function>", >> + "\"<function>\" . convert_function(\$1) . \"</function>\"", >> + "<structname>(.*?)</structname>", >> + "\"<structname>\" . convert_struct(\$1) . \"</structname>\"", >> + "<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>", >> + "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\""); >> + >> +while($ARGV[0] =~ m/^-(.*)/) { >> + my $cmd = shift @ARGV; >> + if ($cmd eq "-db") { >> + $databasefile = shift @ARGV >> + } >> +} >> +$inputfile = shift @ARGV; >> + >> +sub open_database { >> + open my $handle, '<', $databasefile; >> + chomp(my @lines = <$handle>); >> + close $handle; >> + >> + @database = @lines; >> +} >> + >> +sub process_file { >> + open_database(); >> + >> + my $dohighlight; >> + foreach my $pattern (keys %highlights) { >> + $dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n"; >> + } >> + >> + open(FILE, $inputfile) or die("Could not open $inputfile"); >> + foreach my $line (<FILE>) { >> + eval $dohighlight; >> + print $line; >> + } >> +} >> + >> +sub trim($_) >> +{ >> + my $str = $_[0]; >> + $str =~ s/^\s+|\s+$//g; >> + return $str >> +} >> + >> +sub has_key_defined($_) >> +{ >> + if ( grep( /^$_[0]$/, @database)) { >> + return 1; >> + } >> + return 0; >> +} >> + >> +sub convert_function($_) >> +{ >> + my $arg = $_[0]; >> + my $key = $_[0]; >> + >> + $key = trim($key); >> + >> + $key =~ s/[^A-Za-z0-9]/-/g; >> + $key = "API-" . $key; >> + >> + if (!has_key_defined($key)) { >> + return $arg; >> + } >> + >> + my $head = $arg; >> + my $tail = ""; >> + if ($arg =~ /(.*?)( ?)$/) { >> + $head = $1; >> + $tail = $2; >> + } >> + return "<link linkend=\"$key\">$head</link>$tail"; >> +} >> +sub convert_struct($_) >> +{ >> + my $arg = $_[0]; >> + my $key = $_[0]; >> + $key =~ s/(struct )?(\w)/$2/g; >> + $key =~ s/[^A-Za-z0-9]/-/g; >> + $key = "API-struct-" . $key; >> + >> + if (!has_key_defined($key)) { >> + return $arg; >> + } >> + >> + my ($head, $tail) = split_pointer($arg); >> + return "<link linkend=\"$key\">$head</link>$tail"; >> +} >> + >> +sub split_pointer($_) >> +{ >> + my $arg = $_[0]; >> + if ($arg =~ /(.*?)( ?\* ?)/) { >> + return ($1, $2); >> + } >> + return ($arg, ""); >> +} >> + >> +sub convert_param($_) >> +{ >> + my $type = $_[0]; >> + my $keyname = convert_key_name($type); >> + >> + if (!has_key_defined($keyname)) { >> + return $type; >> + } >> + >> + my ($head, $tail) = split_pointer($type); >> + return "<link linkend=\"$keyname\">$head</link>$tail"; >> + >> +} >> + >> +sub convert_key_name($_) >> +{ >> + #Pattern $2 is optional and might be uninitialized >> + no warnings 'uninitialized'; >> + >> + my $str = $_[0]; >> + $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ; >> + >> + # trim >> + $str =~ s/^\s+|\s+$//g; >> + >> + # spaces and _ to - >> + $str =~ s/[^A-Za-z0-9]/-/g; >> + >> + return "API-" . $str; >> +} >> + >> +sub usage { >> + print "Usage: $0 -db database filename ]\n"; >> + print " xml source file(s) > outputfile\n"; >> + exit 1; >> +} >> + >> +# starting point >> +process_file(); >> + >> +if ($errors) { >> + print STDERR "$errors errors\n"; >> +} >> + >> +exit($errors); >> -- >> 2.1.4 >> >
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 $@))</a><p>' > $@ +%.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 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 0000000..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 = ( + "<function>(.*?)</function>", + "\"<function>\" . convert_function(\$1) . \"</function>\"", + "<structname>(.*?)</structname>", + "\"<structname>\" . convert_struct(\$1) . \"</structname>\"", + "<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>", + "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\""); + +while($ARGV[0] =~ m/^-(.*)/) { + my $cmd = shift @ARGV; + if ($cmd eq "-db") { + $databasefile = shift @ARGV + } +} +$inputfile = shift @ARGV; + +sub open_database { + open my $handle, '<', $databasefile; + chomp(my @lines = <$handle>); + close $handle; + + @database = @lines; +} + +sub process_file { + open_database(); + + my $dohighlight; + foreach my $pattern (keys %highlights) { + $dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n"; + } + + open(FILE, $inputfile) or die("Could not open $inputfile"); + foreach my $line (<FILE>) { + eval $dohighlight; + print $line; + } +} + +sub trim($_) +{ + my $str = $_[0]; + $str =~ s/^\s+|\s+$//g; + return $str +} + +sub has_key_defined($_) +{ + if ( grep( /^$_[0]$/, @database)) { + return 1; + } + return 0; +} + +sub convert_function($_) +{ + my $arg = $_[0]; + my $key = $_[0]; + + $key = trim($key); + + $key =~ s/[^A-Za-z0-9]/-/g; + $key = "API-" . $key; + + if (!has_key_defined($key)) { + return $arg; + } + + my $head = $arg; + my $tail = ""; + if ($arg =~ /(.*?)( ?)$/) { + $head = $1; + $tail = $2; + } + return "<link linkend=\"$key\">$head</link>$tail"; +} +sub convert_struct($_) +{ + my $arg = $_[0]; + my $key = $_[0]; + $key =~ s/(struct )?(\w)/$2/g; + $key =~ s/[^A-Za-z0-9]/-/g; + $key = "API-struct-" . $key; + + if (!has_key_defined($key)) { + return $arg; + } + + my ($head, $tail) = split_pointer($arg); + return "<link linkend=\"$key\">$head</link>$tail"; +} + +sub split_pointer($_) +{ + my $arg = $_[0]; + if ($arg =~ /(.*?)( ?\* ?)/) { + return ($1, $2); + } + return ($arg, ""); +} + +sub convert_param($_) +{ + my $type = $_[0]; + my $keyname = convert_key_name($type); + + if (!has_key_defined($keyname)) { + return $type; + } + + my ($head, $tail) = split_pointer($type); + return "<link linkend=\"$keyname\">$head</link>$tail"; + +} + +sub convert_key_name($_) +{ + #Pattern $2 is optional and might be uninitialized + no warnings 'uninitialized'; + + my $str = $_[0]; + $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ; + + # trim + $str =~ s/^\s+|\s+$//g; + + # spaces and _ to - + $str =~ s/[^A-Za-z0-9]/-/g; + + return "API-" . $str; +} + +sub usage { + print "Usage: $0 -db database filename ]\n"; + print " xml source file(s) > outputfile\n"; + exit 1; +} + +# starting point +process_file(); + +if ($errors) { + print STDERR "$errors errors\n"; +} + +exit($errors);
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.cesar@collabora.co.uk> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: linux-doc@vger.kernel.org Cc: intel-gfx <intel-gfx@lists.freedesktop.org> Cc: dri-devel <dri-devel@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 | 176 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 13 deletions(-) create mode 100755 scripts/kernel-doc-xml-ref