[Laszlo-dev] For Review: Change 20071015-ben-y Summary: Add left nav for reference

[Benjamin Shine]

On Oct 16, 2007, at 12:22 PM, John Sundman wrote:

>>
>> nav/toc.xml is a standin for a real table of contents, which will  
>> have to be
>>     either hand-generated or generated with tools that know what  
>> topics each
>>     reference page belongs in.
>
> Sounds good.
>
>> (js2doc annotates each class with what topic
>>     it should be part of,
>
> This info is suspect, however, and should be explicityly reviewed  
> (by me, I guess), before we assume it's correct.  I pressume that  
> this information was used to drive the TOC in the 4.0 docs, and  
> much of that organization was bogus.

Yeah, those were weird categories. For now, I will endeavor to  
duplicate the TOC from the 3.4 docs.

>
>> but the new toolchain is not yet aware of that
>>     information. However, the TOC is relatively static, so it  
>> won't hurt
>>     much to generate and maintain this by hand, until the tools are
>>     smartified.)
>
> I agree.

Cool.

>>
>> nav/classes.xml, and nav/tags.xml are generated contents lists
>>     for nav.lzx. They are generated by navxmlbuilder.rb, a ruby
>>     script which only needs to be run by a developer when updating
>>     the classes.xml and tags.xml. This script just looks at
>>     filenames in directories; it is not js2doc-aware.
>>     (The addition of this script does not make the developer
>>     build require ruby; the entire project will build and
>>     run without even trying to execute this script.)
>
> Cool.
>>
>> docs/src/build.xml copies the files necessary for the live nav
>>     app to run into the reference directory,. It overwrites
>>     the docbook-generated index.html; while this goes against
>>     100% pure docbook philosophy, I've decided that it's
>>     more appropriate to design and maintain our own table
>>     of contents and home page, than to convince docbook to do
>>     it for us.
>
> Provisional approval here.  One of the benefits of moving to 100%  
> docbook is that we (theoretically) get a combined index of all docs  
> (Developer's Guide, Reference, Deployer's etc), as well as lists of  
> tables, lists of examples, lists of figures, etc.
>
> I would like to know more about what's lost when we overwrite the  
> docbook-generated index.html.  If it's valuable info, but in raw  
> form, perhaps we could rename it instead of overwriting it? And  
> then at some point massage it into something really useful?
>
> Or do I misunderstand your point?

There's an index, and there's index.html. index.html is the "landing  
page", which up until this morning was the 4.0, bogus-structured TOC.  
Now index.html is a frameset containing the left-nav app and  
welcome.html.

The index with all the unified good stuff - classes, tags,  
attributes, methods - is turned off because it made the build take 80  
minutes -- unfortunately, I can't find *where* it's turned off.  
Reactivating the index isn't a priority for ringding, so, for now  
I'll punt, and leave it off.

>>
>> welcome.html is the welcome page from the 3.4 reference, with
>>     just the tiniest tweaking to make sense for 4.1. This page
>>     will definitely require careful editorial review. The links
>>     on this page are probably broken.
>
> OK.
>>
>> Release Notes:
>>
>> nav.lzx does not currently work in dhtml; this needs to be  
>> investigated.
>> The layout of nav.lzx is not quite right since we no longer have
>> the lztahoe8 font.
>>
>> Details:
>>
>> Tests:
>> ant clean doc
>>
>> http://localhost:8080/paperpie/docs/reference/
>> Note that the left-nav app is back. Click on any
>> of the tabs or any of the entries in the tab, notice
>> that the associated reference page appears in the
>> right-hand frame.
>>
>> Files:
>> A      nav
>> A      nav/nav.lzx
>> A      nav/toc.xml
>> A      nav/classes.xml
>> A      nav/tags.xml
>> M      build.xml
>> M      reference/navbuilder/index-frames.html
>> A      reference/navbuilder/navxmlbuilder.rb
>> A  +   reference/welcome.html
>>
>> Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20071015- 
>> ben-y.tar
>