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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
