[Laszlo-dev] For Review: Change 20071105-ben-o Summary: Merging a few weeks of work in paperpie into trunk

[Benjamin Shine]

Change 20071105-ben-o by ben at slim.local on 2007-11-05 15:53:39 PST
     in /Users/ben/src/svn/openlaszlo/trunk-for-merging
     for http://svn.openlaszlo.org/openlaszlo/trunk

Summary: Merging a few weeks of work in paperpie into trunk

New Features:

Bugs Fixed:
LPP-4977 Refguide links to developers' guide chapters are wrongly mapped
LPP-4712 should not have two files with the same name and different  
caps in the same directory: lz.html and Lz.html
Incomplete progress on unfiled bugs on the general badness of the  
attributes list in the reference

Technical Reviewer: none (alas! my kingdom for an xslt reviewer!)
QA Reviewer: frisco (pending)
Doc Reviewer: sundman (pending)

Documentation:
This change makes substantial progress towards making the documentation
presentable again. The major change is to the attributes list reference,
wherein we're approaching good rules for selecting attribute "category."
The options for attribute category are now initialize-only, read/write,
read-only, and special. No "special" attributes have yet been  
discovered.
Many, many attributes are listed in the reference as "(FIXME:  
otherwise)".
These are indications to the doc toolsmith (me) that the js2doc comments
in the source are not internally consistent and must be repaired.
Similarly, "(TODO: declare attribute)" is a sign to the toolsmith that
the doc comments indicate that that attribute should be declared in
the source, but it is not. This situation arises because of swf's
permissiveness with undeclared attributes; the doctools are noticing
problems in the code that have been okay with swf < swf9 and okay
with dhtml, but that swf9 and the doctools will need to be squared
away.

Release Notes:

Details:

docs/src/xsl/js2doc2dbk.xsl
     Keep track of the attributes for each class as three sets:  
initialization
     args, instance variables, and setters. Do lots of boolean logic on
     the members of those sets to figure out what category (read/ 
write, readonly,
     initialize-only, todo/fixme) that attribute should belong in.
     Change the look of the attribute tables.
     Show the returns type of methods.
     Detect files that would be named Lz.html and lz.html; give them  
more
     different names.

docbook.css and docs/includes/styles.css:
     cosmetic changes to make the docs look more okay and more like  
the 3.4 docs

docs/src/build.xml
     Instead of totally blowing away the docbook-generated index,  
just rename it.

docs/src/xsl/js2doc2dbk/utilities.xsl
     More specific errors for when the javascript type is unknown. ? 
jstype? is
     easier to find in the output than ???

docs/src/xsl/xref.xsl
     Improve linking between reference guide and developer's guide
     and tutorials.

docs/src/xsl/simple-driver.xsl
     figuring out how to build a useful attributes list

docs/src/xsl/refguide-html.xsl
     put back in some templates I had moved out, in paperpie.

Tests:
ant clean build doc
...look at the doc.

Files:
  M     .
M      docs/includes/docbook.css
M      docs/includes/styles.css
M      docs/src/build.xml
M      docs/src/xsl/js2doc2dbk/utilities.xsl
M      docs/src/xsl/simple-driver.xsl
M      docs/src/xsl/js2doc2dbk.xsl
M      docs/src/xsl/refguide-html.xsl
M      docs/src/xsl/xref.xsl

Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20071105-ben- 
o.tar