[Laszlo-checkins] r10520 - in openlaszlo/trunk/docs/src: nav reference/navbuilder xsl/js2doc2dbk
dda@openlaszlo.org
dda at openlaszlo.org
Wed Jul 30 09:14:47 PDT 2008
Author: dda
Date: 2008-07-30 09:14:04 -0700 (Wed, 30 Jul 2008)
New Revision: 10520
Modified:
openlaszlo/trunk/docs/src/nav/toc.xml
openlaszlo/trunk/docs/src/reference/navbuilder/navxmlbuilder.rb
openlaszlo/trunk/docs/src/reference/navbuilder/toccheck.rb
openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl
Log:
Change 20080730-dda-n by dda at lester.local on 2008-07-30 11:52:43 EDT
in /Users/dda/laszlo/src/svn/openlaszlo/trunk-doc2
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: lz.* renaming in doc and associated cleanups
New Features:
Bugs Fixed: LPP-6591 Adjust doc tool to list Javascript name of <tag> as `lz.tag`
LPP-6593 Adjust javascript type declarations to not use LzView
LPP-6588 Clean up reference 'left nav' to uniformly use <tagname> and lz.classname (PARTIAL)
Technical Reviewer: ptw (pending)
QA Reviewer: (pending)
Doc Reviewer: liorio (pending)
Documentation:
Release Notes:
Details:
All class names in the documentation infrastructure are now handled (nearly) consistently in the refguide.
By infrastructure, I mean:
- Contents, Classes, Tags tabs on the refguide navbar
(these changes are nearly complete, some inconsistencies remain - LPP-6588 will be used to track)
- class names that appear in the title of the each page
- class names that appear in 'extends ...' or 'Attrbutes/Events/Methods inherited from ...'
- class names that appear as type arguments, or return types in method signatures
- class names that appear as (Javascript) typing for attributes.
type names that appear in the content of pages is not changed by this, and may need additional cleanup.
Any class that has an associated lzx tag <foo> is now referred to as 'lz.foo'.
Otherwise a class name formally known aas LzFooBar is now referred to as 'lz.FooBar'.
All the above cases are now handled in a single xslt template (lztype-rename), which has been modified to
apply the above rules. In addition, more complex types have been fixed: an array of view ([lz.view])
now appears correctly.
Debug has been added to the classes list, it was not there before.
Additional checks have been made against the TOC to verify that the naming used in Contents tab
corresponds to the name in the Tags or Classes tabs. This has pointed up some inconsistencies
that we're tracking separately.
Tests:
Regenerate doc and check selected pages for output.
Modified: openlaszlo/trunk/docs/src/nav/toc.xml
===================================================================
--- openlaszlo/trunk/docs/src/nav/toc.xml 2008-07-30 16:13:31 UTC (rev 10519)
+++ openlaszlo/trunk/docs/src/nav/toc.xml 2008-07-30 16:14:04 UTC (rev 10520)
@@ -149,7 +149,7 @@
<item title="&lt;method&gt;" href="tag.method.html" />
<item title="&lt;node&gt;" href="LzNode.html" />
<item title="&lt;script&gt;" href="LzScript.html" />
- <item title="Lz.CSSStyleSheet" href="LzCSSStyleSheet.html" />
+ <item title="lz.CSSStyleSheet" href="LzCSSStyleSheet.html" />
</category>
<category title="States">
<item title="&lt;dragstate&gt;" href="lz.dragstate.html" />
Modified: openlaszlo/trunk/docs/src/reference/navbuilder/navxmlbuilder.rb
===================================================================
--- openlaszlo/trunk/docs/src/reference/navbuilder/navxmlbuilder.rb 2008-07-30 16:13:31 UTC (rev 10519)
+++ openlaszlo/trunk/docs/src/reference/navbuilder/navxmlbuilder.rb 2008-07-30 16:14:04 UTC (rev 10520)
@@ -76,7 +76,7 @@
open(filename) {|f|
f.each_line { |line|
line.chomp!
- if (line =~ /<title>.*<\/title>/) then
+ if (!tag && line =~ /<title>.*<\/title>/) then
if (line =~ /<title><.*>.*<\/title>/) then
tag = line.sub(/.*<title></, '').sub(/>/, '').sub(/<\/title>.*/, '')
end
@@ -96,7 +96,7 @@
open(filename) {|f|
f.each_line { |line|
line.chomp!
- if (line =~ /<title>.*<\/title>/) then
+ if (!name && line =~ /<title>.*<\/title>/) then
if (line =~ /<title>.*<\/title>/ &&
line !~ /<title><.*>.*<\/title>/) then
name = line.sub(/.*<title>/, '').sub(/<\/title>.*/, '')
@@ -142,18 +142,20 @@
if (name) then
name = "&lt;" + name + "&gt;";
end
+
name
}
-generate_index("Lz*.html", $outdir + "/classes.xml", "index") { | file,fullname |
+generate_index("{Lz*,Debug*}.html", $outdir + "/classes.xml", "index") { | file,fullname |
name = tagname_for(fullname);
if (name) then
name = 'lz.' + name;
else
name = nontagname_for(fullname);
- if (!name) then
+ if (name) then
+ name = name.sub(/\$lzc\$class_/, 'lz.');
+ else
name = file.sub(/\.html/, '').sub(/([^+]*)\+(.*)/, '\1 (\2)').gsub(/\+/, ' ');
end
- name = name.sub(/^Lz/, 'lz.').tr('A-Z','a-z');
end
name
}
Modified: openlaszlo/trunk/docs/src/reference/navbuilder/toccheck.rb
===================================================================
--- openlaszlo/trunk/docs/src/reference/navbuilder/toccheck.rb 2008-07-30 16:13:31 UTC (rev 10519)
+++ openlaszlo/trunk/docs/src/reference/navbuilder/toccheck.rb 2008-07-30 16:14:04 UTC (rev 10520)
@@ -28,7 +28,31 @@
}
end
-def check_link(fromname, refname)
+def check_title(href, title, reffile)
+ found = false;
+ for_line($indir + reffile) { | refline |
+ if (refline.index("href=\"" + href + "\"")) then
+ found = true;
+ wanttitle = refline.sub(/^.*title="([^"]*)".*/, '\1')
+
+ # class LzFooService is always refered to as LzFoo in the toc
+ wanttitle = wanttitle.sub(/Service$/,'');
+
+ # remove any platform specific naming, like LzFoo (swf8) -> LzFoo
+ wanttitle = wanttitle.sub(/ \(.*\)/, '');
+
+ if (wanttitle != title) then
+ $stderr.puts('Warning: toc.xml has title "' + title + '" and ' + reffile + ' has "' + wanttitle + '"')
+ end
+ break
+ end
+ }
+ if (!found) then
+ $stderr.puts('Warning: toc.xml has title "' + title + '" and ' + reffile + ' does not list it')
+ end
+end
+
+def check_link(fromname, refname, title)
result = true
if (!File.exist?($indir + refname)) then
$stderr.puts("Error: broken link in doc navigation: " + refname + " referenced from " + fromname + " does not exist")
@@ -39,6 +63,11 @@
result = false
}
end
+ if (title =~ /&lt/) then
+ check_title(refname, title, "tags.xml")
+ else
+ check_title(refname, title, "classes.xml")
+ end
return result
end
@@ -72,7 +101,8 @@
end
if (line =~ /<item.*href=/) then
filename = line.sub(/^.*href="([^"]*)".*$/, '\1')
- if (!check_link('toc.xml', filename))
+ title = line.sub(/^.*title="([^"]*)".*/, '\1')
+ if (!check_link('toc.xml', filename, title))
ecode = false
end
end
Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl 2008-07-30 16:13:31 UTC (rev 10519)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl 2008-07-30 16:14:04 UTC (rev 10520)
@@ -89,10 +89,74 @@
</xsl:otherwise>
</xsl:choose>
</xsl:template>
-
+
+ <!-- lztype-rename
+ rename a type, allowing for []*| syntax complexities
+ e.g. [LzView]|[LzNode] => [lz.view]|[lz.node]
+ -->
<xsl:template name="lztype-rename">
<xsl:param name="type"/>
+ <xsl:variable name="length" select="string-length($type)"/>
+ <xsl:variable name="first" select="substring($type,1,1)"/>
+ <xsl:variable name="last" select="substring($type,$length,1)"/>
<xsl:choose>
+ <xsl:when test="contains($type, '[')">
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-before($type,'[')"/>
+ </xsl:call-template>
+ <xsl:value-of select="'['"/>
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-after($type,'[')"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="contains($type, ']')">
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-before($type,']')"/>
+ </xsl:call-template>
+ <xsl:value-of select="']'"/>
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-after($type,']')"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="contains($type, '*')">
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-before($type,'*')"/>
+ </xsl:call-template>
+ <xsl:value-of select="'*'"/>
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-after($type,'*')"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="contains($type, '|')">
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-before($type,'|')"/>
+ </xsl:call-template>
+ <xsl:value-of select="'|'"/>
+ <xsl:call-template name="lztype-rename">
+ <xsl:with-param name="type" select="substring-after($type,'|')"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="lztype-rename-inner">
+ <xsl:with-param name="type" select="$type"/>
+ </xsl:call-template>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <xsl:template name="lztype-rename-inner">
+ <xsl:param name="type"/>
+ <xsl:variable name="lzxname" select="/js2doc/property[@name=$type]/doc/tag[@name='lzxname']/text"/>
+ <xsl:choose>
+ <xsl:when test="$type=''">
+ <xsl:value-of select="''"/>
+ </xsl:when>
+ <xsl:when test="substring($type,1,3)='lz.'">
+ <xsl:value-of select="$type"/>
+ </xsl:when>
+ <xsl:when test='$lzxname'>
+ <xsl:value-of select="concat('lz.', $lzxname)"/>
+ </xsl:when>
<xsl:when test="substring($type,1,2)='Lz'">
<xsl:value-of select="concat('lz.', substring-after($type, 'Lz'))"/>
</xsl:when>
More information about the Laszlo-checkins
mailing list