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


Mime
View raw message