On Oct 16, 2007, at 8:46 PM, Benjamin Shine wrote:
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 think it's important to make the distinction between docbook (a way
to represent data), and docbook-xsl (a set of templates used to
transform that data into another
form (HTML, PDF, etc.)).
Docbook does not produce a combined index, TOC, lists of tables,
figures, and examples; using docbook-xsl does.
In my opinion, a 100% docbook solution means using 100% docbook. That
means we can use any tools that understand docbook (editors, xmllint,
tidy, etc.)
to make sure we have the docbook right.
If we choose to use other tools in addition to docbook-xls to process
the docbook source, I don't think that breaks the 100% docbook
philosophy.
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
