harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Salikh Zakirov <Salikh.Zaki...@Intel.com>
Subject Re: "Hot to Write GC" requires improvement
Date Tue, 17 Oct 2006 17:41:48 GMT
First of all, I would like to make it clear
that I am *for* committing HARMONY-1881 changes.

My point was just a little bit of advertising
the tool which I personally consider the best
for the purposes of documentation authoring. 

Morozova, Nadezhda wrote:
> About concern for updating resulting HTML and not the source TXT
> for Asciidoc-generated documents: 

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

Personally, I don't intend adding anything just now.

But, perhaps, Xiao Feng may want to share some of his experience
of creating generational and/or parallel collectors?

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

Looking from the dumped config file ('asciidoc -c some.text > some.conf'),
I see that asciidoc is configurable inside out: starting from the configurable
syntax (you can configure what kinds of quotes are recognized as quotes),
and through to configuring the exact output templates.

I am sure configuring it for producing XML is perfectly 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?

Let's "vote with our feet" :)
Anyone writing new documentation picks his/her favourite tool.

> * Asciidoc formatting is unique, resembles Wiki formatting but is
> actually different - confused me when I was starting with it.

In fact, every wiki's formatting is unique. 
It never was a problem for me, as getting used to any given wiki
syntax usually took just a couple of hours.

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

In fact, this is not an asciidoc limitation, this was just the first solution
that I came up with. There may be better ways, for example something like
adding a explicit cut markers to the code that is supposed to be included verbatim
into other documents, e.g.

     // cut-function-start
     void function() {
     // cut-function-end

It would be obvious that these things should not be touched.
And in case of major changes like function rename, the document will need an update anyway.

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

View raw message