harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ivanov, Alexey A" <alexey.a.iva...@intel.com>
Subject RE: [doc][website]do we need section numeration within pages?
Date Thu, 15 Mar 2007 08:21:43 GMT
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.


[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.
>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,
>> not.
>> Could we get rid of this site inconsistency somehow? I'd like to, but
>> 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]
>> [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

View raw message