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
