[Laszlo-dev] For Review: Change 20071015-ben-y Summary: Add left nav for reference
ben at laszlosystems.com
Tue Oct 16 17:46:41 PDT 2007
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
> I agree.
>> 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.)
>> 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
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.
>> Release Notes:
>> nav.lzx does not currently work in dhtml; this needs to be
>> The layout of nav.lzx is not quite right since we no longer have
>> the lztahoe8 font.
>> ant clean doc
>> 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.
>> 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-
More information about the Laszlo-dev