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 Mon, 19 Mar 2007 04:12:51 GMT

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 <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