harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Geir Magnusson Jr." <g...@pobox.com>
Subject Re: [doc][website]do we need section numeration within pages?
Date Thu, 15 Mar 2007 11:24:14 GMT

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:alexey.v.varlamov@gmail.com]
> Sent: Thursday, March 15, 2007 8:52 AM
> To: dev@harmony.apache.org
> 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 <svetlana.konovalova@intel.com>:
>> 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
>>


Mime
View raw message