You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by "Konovalova, Svetlana" <sv...@intel.com> on 2007/03/14 09:47:45 UTC
[doc][website]do we need section numeration within pages?
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
RE: [doc][website]do we need section numeration within pages?
Posted by "Konovalova, Svetlana" <sv...@intel.com>.
Oops,
I'm going to fix this bug.
Thanks,
Sveta
-----Original Message-----
From: Alexey Varlamov [mailto:alexey.v.varlamov@gmail.com]
Sent: Thursday, March 15, 2007 8:57 AM
To: dev@harmony.apache.org
Subject: Re: [doc][website]do we need section numeration within pages?
BTW, the awt page[3] has funny numbering of pictures:
Fig1
Fig3
Fig2
Fig4
...
> > [3] http://harmony.apache.org/subcomponents/classlibrary/awt.html
Re: [doc][website]do we need section numeration within pages?
Posted by Alexey Varlamov <al...@gmail.com>.
BTW, the awt page[3] has funny numbering of pictures:
Fig1
Fig3
Fig2
Fig4
...
> > [3] http://harmony.apache.org/subcomponents/classlibrary/awt.html
RE: [doc][website]do we need section numeration within pages?
Posted by "Ivanov, Alexey A" <al...@intel.com>.
I tend to agree with Alexey. Number is not essential for this kind of
documents. Numbering is a must in specification where you constantly
need to refer to other sections.
Since all the pages use hypertext, then we should use its possibilities:
When referring to a section, make it a hyperlink; if it's an email
message, then -- again -- it's better to provide the address of the
section you refer to, so that there's no need to search it.
>From maintenance point of view, if numbers are hard coded, even a simple
modification of document will break numeration. Fixing it by hand is not
a funny thing.
CSS 2 provides a way for automatic numbering (counters) [1] but this
feature is not supported in Internet Explorer, even in v7.0. However
this feature is correctly supported in Firefox, Opera.
I think the best way to format Table of Contents is using <ol> or <ul>,
and not using paragraphs. Any style can be applied to lists (even
numbers or markers can be hidden), and the same formatting as it is now
may be achieved with CSS. But the semantics, IMHO, will improve.
Regards,
Alexey.
[1] http://www.w3.org/TR/CSS21/generate.html#counters
>-----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 <sv...@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
>>
Re: [doc][website]do we need section numeration within pages?
Posted by "Geir Magnusson Jr." <ge...@pobox.com>.
On Mar 16, 2007, at 3:08 AM, Ivanov, Alexey A wrote:
> Geir,
>
> As far I remember the only files which have TOC and numbering are
> those
> long-long HTML files which are not actually processed by Anakia -
> their
> HTML code merely included into VSL-generated template. Am I wrong?
That might be now, yes.
>
> Having this in mind, using your approach requires all these files
> to be
> converted into XML (some tags need changing etc.)
Yes - my thought was to do this for things going forward, to just
make it easier for new docs.
> Applying CSS doesn't
> require any changes. And I don't know why Microsoft doesn't implement
> support many CSS properties which may make life of web content
> developer
> easier.
Beats me :)
>
>
> Regards,
> Alexey.
>
>
>> -----Original Message-----
>> From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>> Sent: Thursday, March 15, 2007 2:24 PM
>> To: dev@harmony.apache.org
>> Subject: Re: [doc][website]do we need section numeration within
>> pages?
>>
>>
>> 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 <sv...@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
>>>>
RE: [doc][website]do we need section numeration within pages?
Posted by "Ivanov, Alexey A" <al...@intel.com>.
Geir,
As far I remember the only files which have TOC and numbering are those
long-long HTML files which are not actually processed by Anakia - their
HTML code merely included into VSL-generated template. Am I wrong?
Having this in mind, using your approach requires all these files to be
converted into XML (some tags need changing etc.) Applying CSS doesn't
require any changes. And I don't know why Microsoft doesn't implement
support many CSS properties which may make life of web content developer
easier.
Regards,
Alexey.
>-----Original Message-----
>From: Geir Magnusson Jr. [mailto:geir@pobox.com]
>Sent: Thursday, March 15, 2007 2:24 PM
>To: dev@harmony.apache.org
>Subject: Re: [doc][website]do we need section numeration within pages?
>
>
>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 <sv...@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
>>>
Re: [doc][website]do we need section numeration within pages?
Posted by "Geir Magnusson Jr." <ge...@pobox.com>.
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 <sv...@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
>>
RE: [doc][website]do we need section numeration within pages?
Posted by "Konovalova, Svetlana" <sv...@intel.com>.
Nadya,
Thanks for useful suggestions!
>= use TOCHeading and TOC paragraph styles for headings of 1st and 2nd
>levels respectively
+1
>= use lists to format the table of contents; if the page has section
>numbering, an ordered list would be ideal; for unnumbered sections, an
>unordered list would do.
+1
Best regards,
Sveta
-----Original Message-----
From: Morozova, Nadezhda [mailto:nadezhda.morozova@intel.com]
Sent: Thursday, March 15, 2007 11:01 AM
To: dev@harmony.apache.org
Subject: RE: [doc][website]do we need section numeration within pages?
Sveta,
Thanks for help.
>+1. If there are no objections, I can add tables of content to longish
>pages, such as [2]&[5]
Patches are always welcome. Would be great if the tables of content are
of unified format.
Suggestions:
= use TOCHeading and TOC paragraph styles for headings of 1st and 2nd
levels respectively
= use lists to format the table of contents; if the page has section
numbering, an ordered list would be ideal; for unnumbered sections, an
unordered list would do.
What do you think?
Cheers,
Nadya
>-----Original Message-----
>From: Konovalova, Svetlana [mailto:svetlana.konovalova@intel.com]
>Sent: Thursday, March 15, 2007 10:57 AM
>To: dev@harmony.apache.org
>Subject: RE: [doc][website]do we need section numeration within pages?
>
>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]
>
>>>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 <sv...@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
>>
RE: [doc][website]do we need section numeration within pages?
Posted by "Morozova, Nadezhda" <na...@intel.com>.
Sveta,
Thanks for help.
>+1. If there are no objections, I can add tables of content to longish
>pages, such as [2]&[5]
Patches are always welcome. Would be great if the tables of content are
of unified format.
Suggestions:
= use TOCHeading and TOC paragraph styles for headings of 1st and 2nd
levels respectively
= use lists to format the table of contents; if the page has section
numbering, an ordered list would be ideal; for unnumbered sections, an
unordered list would do.
What do you think?
Cheers,
Nadya
>-----Original Message-----
>From: Konovalova, Svetlana [mailto:svetlana.konovalova@intel.com]
>Sent: Thursday, March 15, 2007 10:57 AM
>To: dev@harmony.apache.org
>Subject: RE: [doc][website]do we need section numeration within pages?
>
>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]
>
>>>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 <sv...@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
>>
RE: [doc][website]do we need section numeration within pages?
Posted by "Konovalova, Svetlana" <sv...@intel.com>.
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]
>>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 <sv...@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
>
Re: [doc][website]do we need section numeration within pages?
Posted by Alexey Varlamov <al...@gmail.com>.
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 <sv...@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
>