[Laszlo-dev] For Review: Change 20080917-dda-F Summary: Change output naming for refguide to match lz.xxx naming convention

[Donald Anderson]

Change 20080917-dda-F by dda at lester.local on 2008-09-17 15:42:05 EDT
     in /Users/dda/laszlo/src/svn/openlaszlo/trunk-doc5
     for http://svn.openlaszlo.org/openlaszlo/trunk

Summary: Change output naming for refguide to match lz.xxx naming  
convention

New Features:

Bugs Fixed: LPP-7000 (name doc output files corresponding to new  
lz.xxx naming convention)

Technical Reviewer: (pending)
QA Reviewer: (pending)
Doc Reviewer: liorio (pending)

Documentation:

Release Notes:

Details:
     Committed in advance for review

     The general technique is to insert a <?dbhtml  
filename="zzzz.html" ?> processing instruction
     into the stream seen by docbook.  We choose the filename based on  
lz.tagname if there is a tagname
     (AKA lzxname); if there is none, lz.Classname; if there is none,  
the unique @id that is currently
     used.  This ends up changing many of the names.

     The known fallout is listed here and is fixed as part of this  
changeset.  It's possible that this has
     also introduced broken links for any links that reference a fixed  
page name.

     - toc.xml needs many updates to use the new naming

     - navxmlbuilder.tb, used to create classes.xml and tags.xml has  
been updated to use the new naming

     - some lzxnames had spaces in them, e.g. '<splash view>'.  Any  
spaces are converted to underscore.

     - any time pluses (e.g. +as3, +debug) appears in the @id, these  
are preserved in the file name.  That way
       we can continue to have filenames that are architecture  
dependent or runtime version dependent.

     - added a 'docfilename' tag (e.g. javadoc @docfile xxxx) to  
indicate the basename of the resulting
       xxxx.html output file.  We're using this currently only in  
wrappers.xml and attributes.xml to generate
       'canned' pages that need to be named specially.  This gives us  
an escape mechanism for filename
       tweaks if we need them.

     - fixed a couple &lt; &gt; issues in wrappers.xml .  These need  
to appear in the lzxname for certain
       tags (e.g. the lzxname for <a> is actually &lt;a&gt;  -- this  
makes <a> appear correctly in the output
       page).  Not sure why these are needed or how to get rid of  
them, this was an expedient fix.

     - pushed the original javascript name into a 'postprocessing'  
comment.

     Not part of the fallout, but a broken reference to Debug 
+debug.html has been commented out of the TOC,
     there doesn't seem to be a replacement page in place to describe  
the new debugger.  This change
     was needed to get the build to complete without error.

     Also, needed to turn the docbook 'chunk.fast' parameter to 0 in  
order to get the <?dbhtml processing instruction
     to work.  This doesn't seem to be documented in docbook.   
Unfortunately this makes the doc builds
     take a little longer, it seems.


Tests:
     Built ref, spot checked pages and naming.

Files:
M      docs/src/nav/toc.xml
M      docs/src/reference/wrappers.xml
C      docs/src/reference/postprocess.rb
M      docs/src/reference/info.xml
M      docs/src/reference/navbuilder/navxmlbuilder.rb
M      docs/src/xsl/js2doc2dbk.xsl
M      docs/src/xsl/parameters.xsl

Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20080917-dda-F.tar



--

Don Anderson
Java/C/C++, Berkeley DB, systems consultant

voice: 617-547-7881
email: dda at ddanderson.com
www: http://www.ddanderson.com



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.openlaszlo.org/pipermail/laszlo-dev/attachments/20080917/8ad1d860/attachment-0001.html