* [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions @ 2006-12-31 1:27 Pavel Pisa 2006-12-31 5:36 ` Randy Dunlap 2007-01-02 0:41 ` Randy Dunlap 0 siblings, 2 replies; 5+ messages in thread From: Pavel Pisa @ 2006-12-31 1:27 UTC (permalink / raw) To: tali, rdunlap, linux-kernel Simple increase of section TOC level generation significantly enhances navigation experience through generated kernel API documentation. This change restores back state from SGML tools time. Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> Index: linux-2.6.19/Documentation/DocBook/stylesheet.xsl =================================================================== --- linux-2.6.19.orig/Documentation/DocBook/stylesheet.xsl +++ linux-2.6.19/Documentation/DocBook/stylesheet.xsl @@ -4,4 +4,5 @@ <param name="funcsynopsis.style">ansi</param> <param name="funcsynopsis.tabular.threshold">80</param> <!-- <param name="paper.type">A4</param> --> +<param name="generate.section.toc.level">2</param> </stylesheet> ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions 2006-12-31 1:27 [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions Pavel Pisa @ 2006-12-31 5:36 ` Randy Dunlap 2007-01-02 0:41 ` Randy Dunlap 1 sibling, 0 replies; 5+ messages in thread From: Randy Dunlap @ 2006-12-31 5:36 UTC (permalink / raw) To: Pavel Pisa; +Cc: tali, linux-kernel, akpm On Sun, 31 Dec 2006 02:27:46 +0100 Pavel Pisa wrote: > Simple increase of section TOC level generation significantly > enhances navigation experience through generated kernel > API documentation. > > This change restores back state from SGML tools time. > > Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> Acked-by: Randy Dunlap <rdunlap@xenotime.net> Andrew, please put this into -mm for testing. > Index: linux-2.6.19/Documentation/DocBook/stylesheet.xsl > =================================================================== > --- linux-2.6.19.orig/Documentation/DocBook/stylesheet.xsl > +++ linux-2.6.19/Documentation/DocBook/stylesheet.xsl > @@ -4,4 +4,5 @@ > <param name="funcsynopsis.style">ansi</param> > <param name="funcsynopsis.tabular.threshold">80</param> > <!-- <param name="paper.type">A4</param> --> > +<param name="generate.section.toc.level">2</param> > </stylesheet> > - --- ~Randy ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions 2006-12-31 1:27 [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions Pavel Pisa 2006-12-31 5:36 ` Randy Dunlap @ 2007-01-02 0:41 ` Randy Dunlap 2007-01-02 9:18 ` Pavel Pisa 1 sibling, 1 reply; 5+ messages in thread From: Randy Dunlap @ 2007-01-02 0:41 UTC (permalink / raw) To: Pavel Pisa; +Cc: tali, linux-kernel On Sun, 31 Dec 2006 02:27:46 +0100 Pavel Pisa wrote: > Simple increase of section TOC level generation significantly > enhances navigation experience through generated kernel > API documentation. > > This change restores back state from SGML tools time. > > Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> > > Index: linux-2.6.19/Documentation/DocBook/stylesheet.xsl > =================================================================== > --- linux-2.6.19.orig/Documentation/DocBook/stylesheet.xsl > +++ linux-2.6.19/Documentation/DocBook/stylesheet.xsl > @@ -4,4 +4,5 @@ > <param name="funcsynopsis.style">ansi</param> > <param name="funcsynopsis.tabular.threshold">80</param> > <!-- <param name="paper.type">A4</param> --> > +<param name="generate.section.toc.level">2</param> > </stylesheet> Hi, Is it possible to make the TOC contain active links to their sections/functions? That would be even better, wouldn't it? --- ~Randy ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions 2007-01-02 0:41 ` Randy Dunlap @ 2007-01-02 9:18 ` Pavel Pisa 2007-01-07 20:23 ` [PATCH] DocBook/HTML: correction of recursive A tags in HTML output Pavel Pisa 0 siblings, 1 reply; 5+ messages in thread From: Pavel Pisa @ 2007-01-02 9:18 UTC (permalink / raw) To: Randy Dunlap; +Cc: tali, linux-kernel On Tuesday 02 January 2007 01:41, Randy Dunlap wrote: > On Sun, 31 Dec 2006 02:27:46 +0100 Pavel Pisa wrote: > > Simple increase of section TOC level generation significantly > > enhances navigation experience through generated kernel > > API documentation. > > > > This change restores back state from SGML tools time. > > > > Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> > > > > Index: linux-2.6.19/Documentation/DocBook/stylesheet.xsl > > =================================================================== > > --- linux-2.6.19.orig/Documentation/DocBook/stylesheet.xsl > > +++ linux-2.6.19/Documentation/DocBook/stylesheet.xsl > > @@ -4,4 +4,5 @@ > > <param name="funcsynopsis.style">ansi</param> > > <param name="funcsynopsis.tabular.threshold">80</param> > > <!-- <param name="paper.type">A4</param> --> > > +<param name="generate.section.toc.level">2</param> > > </stylesheet> > > Hi, > Is it possible to make the TOC contain active links to their > sections/functions? That would be even better, wouldn't it? Hello Randy, this is another sort of the problem. This problem has been probably introduced by switch from OpenJade to xsltproc for HTML generation as well. I have found temporarily workaround on next pages http://darkk.livejournal.com/ http://darkk.livejournal.com/7429.html I am attaching copy of the patch. The copy of generated HTML documentation can be seen there http://cmp.felk.cvut.cz/~pisa/linux/lkdb-2.6.19.tar.gz The problem is caused by nested <refentrytitle><phrase> tags. XML source: <refentrytitle><phrase id="API-struct-x">struct x</phrase></refentrytitle> Generates next malformed HTML with nested anchor <a> sections, which is interpreted as link with empty text by most browsers: <a href="re02.html"><span><a id="API-struct-x"></a>struct x</span></a> I do not know, if nesting of <refentrytitle><phrase> is on the border of DocBook specification (but it seems, that it is not against DocBook DTD) or if this is bug of xsltproc / XML -> HTML DocBook formater. The valid HTML should read as <a href="re02.html" id="API-struct-x">struct x</span></a> I has not been sure, if it is only problem of my tools set. But is seems, that links are broken even on Free-Electrons from 2.6.14 or may it be 2.6.12 days http://free-electrons.com/kerneldoc/latest/DocBook/kernel-api/ It would be good if somebody with more knowledge about xsltproc and DocBook could help there to find clean solution. May it be, that somebody from http://docbook.sourceforge.net/ could help there. Best wishes Pavel Pisa Index: linux-2.6.19/scripts/kernel-doc =================================================================== --- linux-2.6.19.orig/scripts/kernel-doc +++ linux-2.6.19/scripts/kernel-doc @@ -590,7 +590,7 @@ sub output_function_xml(%) { print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n"; + print " <refentrytitle>".$args{'function'}."</refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; @@ -666,7 +666,7 @@ sub output_struct_xml(%) { print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n"; + print " <refentrytitle>".$args{'type'}." ".$args{'struct'}."</refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; @@ -750,7 +750,7 @@ sub output_enum_xml(%) { print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n"; + print " <refentrytitle>enum ".$args{'enum'}."</refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; @@ -816,7 +816,7 @@ sub output_typedef_xml(%) { print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n"; + print " <refentrytitle>typedef ".$args{'typedef'}."</refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH] DocBook/HTML: correction of recursive A tags in HTML output 2007-01-02 9:18 ` Pavel Pisa @ 2007-01-07 20:23 ` Pavel Pisa 0 siblings, 0 replies; 5+ messages in thread From: Pavel Pisa @ 2007-01-07 20:23 UTC (permalink / raw) To: Randy Dunlap; +Cc: tali, linux-kernel, Jirka Kosek The malformed HTML was generated after switch to XSLTPROC from SGML tools. The reference title <refentrytitle><phrase id="API-struct-x">struct x</phrase></refentrytitle> is converted into two recursive <a> tags <a href="re02.html"><span><a id="API-struct-x"></a>struct x</span></a> There is more possible solutions for this problem. One can be found at http://darkk.livejournal.com/ The proposed solution is based on suggestion provided by Jiri Kosek. Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz> --- scripts/kernel-doc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) Index: linux-2.6.19/scripts/kernel-doc =================================================================== --- linux-2.6.19.orig/scripts/kernel-doc +++ linux-2.6.19/scripts/kernel-doc @@ -583,14 +583,14 @@ sub output_function_xml(%) { $id = "API-".$args{'function'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "<refentry>\n"; + print "<refentry id=\"$id\">\n"; print "<refentryinfo>\n"; print " <title>LINUX</title>\n"; print " <productname>Kernel Hackers Manual</productname>\n"; print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n"; + print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; @@ -659,14 +659,14 @@ sub output_struct_xml(%) { $id = "API-struct-".$args{'struct'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "<refentry>\n"; + print "<refentry id=\"$id\">\n"; print "<refentryinfo>\n"; print " <title>LINUX</title>\n"; print " <productname>Kernel Hackers Manual</productname>\n"; print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n"; + print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; @@ -743,14 +743,14 @@ sub output_enum_xml(%) { $id = "API-enum-".$args{'enum'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "<refentry>\n"; + print "<refentry id=\"$id\">\n"; print "<refentryinfo>\n"; print " <title>LINUX</title>\n"; print " <productname>Kernel Hackers Manual</productname>\n"; print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n"; + print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; @@ -809,14 +809,14 @@ sub output_typedef_xml(%) { $id = "API-typedef-".$args{'typedef'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "<refentry>\n"; + print "<refentry id=\"$id\">\n"; print "<refentryinfo>\n"; print " <title>LINUX</title>\n"; print " <productname>Kernel Hackers Manual</productname>\n"; print " <date>$man_date</date>\n"; print "</refentryinfo>\n"; print "<refmeta>\n"; - print " <refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n"; + print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n"; print " <manvolnum>9</manvolnum>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2007-01-08 9:09 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2006-12-31 1:27 [PATCH] DocBook/HTML: Generate chapter/section level TOCs for functions Pavel Pisa 2006-12-31 5:36 ` Randy Dunlap 2007-01-02 0:41 ` Randy Dunlap 2007-01-02 9:18 ` Pavel Pisa 2007-01-07 20:23 ` [PATCH] DocBook/HTML: correction of recursive A tags in HTML output Pavel Pisa
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®