So, I ask my question again:
If the additional information is useful, can we append it in some
acceptable way to the output and still meet the goal?
I don't believe the goal is to "replicate" the 3.4 docs -- that would
be silly, since we already have a way to get that: just use the 3.4
docs. I believe the goal is to convey the information in the same
format as the 3.4 docs; but we should be able to improve the
information content, no?
At the very least, rather than completely nuking the way this
information was passed through, can we just comment it out for now,
so it will be easier to revive at some later date if we decide we
will allow the additional information to be presented?
On 2007-09-29, at 13:01 EDT, Benjamin Shine wrote:
The extra information I'm filtering out is not duplicate
information -- it's additional information that was present in the
4.x docs but not in the 3.4 docs. This is in service of the project
goal for 4.1 docs: replicate the 3.4 documentation.
Note that the filtering is at the level of *presentation* not
*discovery* -- the js2doc output still has all the detailed info it
had yesterday, but the html presentation of the js2doc information
is slimmer. Changes to information architecture & presentation from
the 3.4 docs will indeed be worked out in concert with the
documentation architect, the community, the training organization,
etc.
-ben
On Sep 29, 2007, at 4:52 AM, P T Withington wrote:
Good stuff.
I have one question: is the 'extra information' you are filtering
out _duplicate_ information, or is it _additional_ information
that should still appear, just not where it was appearing? If it
is additional useful information, maybe you could consult our
documentation architect to see where it could fit in our
documentation architecture.
On 2007-09-28, at 22:04 EDT, Benjamin Shine wrote:
(I'm sending these doctools change package reviews as a matter of
courtesy; I'll ask for a "real" review when I have a chunk of
changes ready to go into trunk.)
Change 20070928-ben-3 by [EMAIL PROTECTED] on 2007-09-28 18:24:44 PDT
in /Users/ben/src/svn/openlaszlo/branches/paperpie
for http://svn.openlaszlo.org/openlaszlo/branches/paperpie
Summary: Make top part of individual pages in the reference guide
look more like 3.4 reference guide
Documentation:
This change is a number of small formatting and processing
changes which
make the generated documentation look superficially more like the
3.4
documentation. This mostly means filtering out some of the extra
information that had been added to the top of the page in reference
entries. Several minor CSS changes have been made to match the
look of the old documentation better.
This work was based on getting <tab> to match the 3.4 <tab>
reference. The formatting currently looks "best" for
components; other areas have not been evaluated.
Details:
Tests:
ant clean; ant build doc
passes.
Pages in the reference still look decent, for instance:
http://localhost:8080/paperpie/docs/reference/LzAnimator.html
Files:
M docs/src/build.xml
M docs/src/xsl/js2doc2dbk.xsl
M docs/src/xsl/common-html.xsl
M docs/src/xsl/refguide-html.xsl
M docs/src/xsl/parameters.xsl
M docs/includes/lzx-pretty-print.css
M docs/includes/docbook.css
M docs/includes/styles.css
Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20070928-
ben-3.tar
