On Mar 15, 2007, at 3:57 AM, Konovalova, Svetlana wrote:
Alexey,
Thanks a lot for demonstrating interest in this issue!
I think that all longish pages should have the table, e.g. roadmap
[2]
lacks it.
+1. If there are no objections, I can add tables of content to longish
pages, such as [2]&[5]
In a previous life, I used velocity for all spec and documentation
work (the organization was using Word docs, with the resultant
problem that anytime someone checked in a change, we had no clue what
changed from CVS diff... so to XML we went :)
Anyway, I remember that I modified the VTL to generate a TOC contents
automatically. Now, I used a different style file for this, because
not ever page needs a TOC (like the front page of the website...)
Maybe we can try that - it will make maintenance so much easier to
have it happen automatically, and instead of an alternate stylesheet,
we simply add metadata to the document which indicates if a TOC is
appropriate.
The only thing I can't remember is if I did it using Anakia or DVSL,
a XSL-like processor that I wrote that lets you write your
stylesheets in Velocity rater than XML, which made it much easier for
me to distinguish between the VTL control statements, and the HTML
(XML-ish) content.
geir
From maintenance POV, it would be nice to provide automated
numbering rather than hardcode the digits as a part of contents.
+1. I'll make a research to find the most appropriate solution to this
problem.
[1] http://harmony.apache.org/subcomponents/drlvm/
developers_guide.html
[2] http://harmony.apache.org/roadmap.html
[3] http://harmony.apache.org/subcomponents/classlibrary/awt.html
[4] http://harmony.apache.org/subcomponents/drlvm/JVMTI-PopFrame.html
[5] http://harmony.apache.org/quickhelp_contributors.html
Best regards,
Sveta
-----Original Message-----
From: Alexey Varlamov [mailto:[EMAIL PROTECTED]
Sent: Thursday, March 15, 2007 8:52 AM
To: [email protected]
Subject: Re: [doc][website]do we need section numeration within pages?
My $0.02:
1) IMO it is not numbering which makes navigation easier, rather the
table of contents - which is orthogonal issue :) I think that all
longish pages should have the table, e.g. roadmap [2] lacks it.
Numbering is convenient for referencing or citing, which is important
for normative docs like specifications. E.g. I personally don't care
if awt guide [3] has numbering or not, as long as it is well
structured and easy to browse.
2) From maintenance POV, it would be nice to provide automated
numbering rather than hardcode the digits as a part of contents. Bad
example here is roadmap [2], which is inconstant by nature and painful
to keep consistent by hand.
So I'd prefer to not add hardcoded numbering until really needed.
--
Thanks,
Alexey
2007/3/14, Konovalova, Svetlana <[EMAIL PROTECTED]>:
Dear all,
I've noticed that certain [1]&[2] pages have numerated sections, and
certain [3]&[4] don't.
IMHO, section numeration makes navigation easier. For the sake of
convenience, you can just say "see section 2.5" instead of saying the
section name that is probably too long.
I'd like to ask you whether we need section numeration within pages,
or
not.
Could we get rid of this site inconsistency somehow? I'd like to, but
I
do not insist. :)
What's your opinion?
If you do not mind, I volunteer to fix this inconsistency.
Feel free to express your ideas! Your feedback is very welcome!
[1]
http://harmony.apache.org/subcomponents/drlvm/developers_guide.html
[2] http://harmony.apache.org/roadmap.html
[3] http://harmony.apache.org/subcomponents/classlibrary/awt.html
[4] http://harmony.apache.org/subcomponents/drlvm/JVMTI-PopFrame.html
Thanks,
Sveta
