Salikh, Thanks for a detailed and constructive response :) I am sorry if I sounded too oppressive or negative about Asciidoc. I have used it successfully and have nothing against it, though I can't say it's a preference with me :)
Your advice helps me understand how to best customize it to our needs. > I am sure configuring it for producing XML is perfectly possible. Great to hear it! > 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 Ok, maybe, we can have something like //cut-function-start <functioname> //cut-function-end <functionname> This way, each such string will be unique and easy-to-find. What do you say? Thank you, Nadya Morozova -----Original Message----- From: news [mailto:[EMAIL PROTECTED] On Behalf Of Salikh Zakirov Sent: Tuesday, October 17, 2006 9:42 PM To: harmony-dev@incubator.apache.org Subject: Re: "Hot to Write GC" requires improvement 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] --------------------------------------------------------------------- Terms of use : http://incubator.apache.org/harmony/mailing.html To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
