harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Morozova, Nadezhda" <nadezhda.moroz...@intel.com>
Subject RE: Re: "Hot to Write GC" requires improvement
Date Tue, 17 Oct 2006 11:03:48 GMT
Salikh, 
About your concern for updating resulting HTML and not the source TXT
for Asciidoc-generated documents: 
I agree that technically Sveta's approach is not "professional" :)
However, for the How to Write a GC document, I do not think that the
issue is big enough because the doc seems quite stable, no frequent
changes are intended.
We only have a couple of code snippets in the doc so the dependency on
the reference source code is not big. 

Generally, Asciidoc might be a nice tool, it's just that we don't use it
well:) The current chain that we use with it is TXT + CONFIG > XHTML >
XHTML with manual edits to fit to site settings/presentation > XML >
output HTML for website. Now, this is LONG :) 
If we manage to have AsciiDoc produce XML that is valid for site
purposes = that would be great. It would reduce the whole chain to TXT +
CONFIG > XML > HTML for website! I do not know AsciiDoc internals that
well now to say whether that's possible.
 
Here are a couple of my personal considerations about using the tool for
Harmony docs:

Strong points: 
* Asciidoc enables using code chunks by references the source file, not
copy=and=paste from code.
* Asciidoc is a freeware common tool, why not use it?
* Asciidoc gets TXT as input, so patching is very easy.

Weak points:
* We have two technologies for writing for website now: XML directly and
HTML with <docinclude> to add to XML. Adding a new one can be another
option (good!) or another confusion (bad!). is the effort worth the
goal?
* Asciidoc formatting is unique, resembles Wiki formatting but is
actually different - confused me when I was starting with it.
* Asciidoc references into the source code (to get the code snippet
directly from the file) rely on a specific line in code - see the
GC-howto.txt we've been discussing. For example, the comment before the
function to include the function body into the doc. Now, if you update
the code, you'll probably update the comment as well - the reference
gets broken. This does not seem much better than manually copying the
code into the doc. Don't know how to overcome this.

Your comments are most welcome :)

Thank you, 
Nadya Morozova
 

-----Original Message-----
From: news [mailto:news@sea.gmane.org] On Behalf Of Salikh Zakirov
Sent: Tuesday, October 17, 2006 1:29 PM
To: harmony-dev@incubator.apache.org
Subject: Re: "Hot to Write GC" requires improvement

Svetlana,

I've looked through your changes.
Mostly they look okay, and they greatly improve the visual presentation.

Originally, GC-howto was created using AsciiDoc[1] toolchain from the
source
text file and source .cpp file. Modifying .html file directly means that
we cannot
update the document to keep it in sync with the source code.

I guess this is acceptable, since nobody is changing source code inlets
in GC-howto now,
but be warned: if anyone is to introduce source changes, it would
tedious
task to synchronize visual and content changes.

Have you tried to configure asciidoc to produce the content you want?

I will send you the version of gc-howto.txt and gc.cpp that I have,
but Nadya may have a later version, so please check with her.
Since I am not sure attachment will make it to the list, I'll send it to
you
directly. (* or to anyone else who might be interested, just ask *)

[1] http://www.methods.co.nz/asciidoc/

Konovalova, Svetlana wrote:
> Sorry about that! 
> I've created a new patch, hope it's the right one you need. Please let
> me know if you still have any problems. 
> 
> [JIRA 1881] http://issues.apache.org/jira/browse/HARMONY-1881
> 
> Cheers,
> Sveta Konovalova
> 
> -----Original Message-----
> From: Geir Magnusson Jr. [mailto:geir@pobox.com] 
> Sent: Tuesday, October 17, 2006 8:50 AM
> To: harmony-dev@incubator.apache.org
> Subject: Re: "Hot to Write GC" requires improvement
> 
> The problem with the patch is that it's to the rendered output
> 
>     site/xdoc/subcomponent/drlvm/gc-howto.html
> 
> when what we need is the patch to the source document
> 
>     site/xdoc/subcomponent/drlvm/gc-howto-content.html
> 
> Can you add a new patch with that please?
> 
> geir
> 
> Rana Dasgupta wrote:
>> This is a good document, thanks Svetlana. Even if a lot of custom
gc's
> 
>> don't
>> get written, it helps in understanding the current collecor farmework
> and
>> how it plugs into DRLVM.
>>
>> Rana
>>
>>
>>
>>> On 10/16/06, Konovalova, Svetlana <svetlana.konovalova@intel.com>
> wrote:
>>>>
>>>> Folks,
>>>>
>>>> I took a close look at "Hot to Write GC" [1] and created a patch
> for
>>>> this doc [JIRA 1881]. I fixed formatting, brushed up the code,
> removed
>>>> out-dated tags etc.
>>>> It would be great if someone can find a chance to look at the
> patch.
>>>> Thanks in advance!
>>>>
>>>> [1]
>>>>
> http://incubator.apache.org/harmony/subcomponents/drlvm/gc-howto.html
>>>> [JIRA 1881] http://issues.apache.org/jira/browse/HARMONY-1881
>>>>
>>>>
>>>> Cheers,
>>>> Sveta Konovalova
>>>>
>>>>
> 
> ---------------------------------------------------------------------
> Terms of use : http://incubator.apache.org/harmony/mailing.html
> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
> 
> ---------------------------------------------------------------------
> Terms of use : http://incubator.apache.org/harmony/mailing.html
> To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
> For additional commands, e-mail: harmony-dev-help@incubator.apache.org
> 
> 

---------------------------------------------------------------------
Terms of use : http://incubator.apache.org/harmony/mailing.html
To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
For additional commands, e-mail: harmony-dev-help@incubator.apache.org


Mime
View raw message