Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: pass (asf.osuosl.org: domain of intrect@gmail.com designates
 64.233.184.205 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:reply-to:to:subject:mime-version:content-type:content-transfer-encoding:content-disposition;
        b=FJEXyedK598dlTve3nsxZQ4q32a4RH7AyImSoVQ14zAujEl1ODheAZDlj5ukkqN5CFTUmrg131GACiW4ydFHenb7OOvoZAn1ygCfRRITN/8shjeDCHIblXTYI41npxETghTcsGdgvdfG10jVmK9Nfn+ZJbsUyb+r6CtuhGk+cTw=
Message-ID: <92c58484050731213514b798f6@mail.gmail.com>
Date: Sun, 31 Jul 2005 23:35:26 -0500
From: Robert Graham <intrect@gmail.com>
Reply-To: Robert Graham <intrect@gmail.com>
To: dev@cocoon.apache.org
Subject: RefDoc - Neutral XML Document Format Input/Current State
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

Hello All,

I'd like any and all input on this as it would make it much better
than I will alone. However, I've sketched out something to start from.
First I'll give a brief description of what I'm talking about for
those that haen't kept up with RefDoc, then I'll present my ideas, and
finally I'll ask some questions that I've thought about in creating
these semantics. If you're current on RefDoc skip the next paragraph.
I apologize fo my long winded discussion.

RefDoc intersperses comments throughout various types of files (java,
xml, xsl, etc.) that are to be used as a form of documentation. They
aren't meant to replace javadoc, but to supplement it especially in
those cases where the files are not java files. These comments have
varying bits of metadata associated with them. The two pieces of
metadata that are well-defined for use now are 'key' and 'type'. In
publishing these documents they are sorted into groups of comments or
snippets with the same key being one document and then they are to be
sorted in some way by type.

I've created several types and other proposed 'well-defined' bits of
metadata to assist the publishing of these documents into a nice
format and easing the pain of parsing out such information. The types
are:

*method* - this type is for documenting methods or functions

*package* - this type indicates that the comment contains only the
package string for the file and perhaps the leading 'package'
declaration in java or a trailing semicolon

*class-declaration* - this type contains only the class declaration
(and maybe the trailing '{')

*codeblock* - this type is for indicating that the comment contains
code for publishing purposes

*name* - this type indicates the 'name' of the document of thing being
documented under
the current key (or specified key for this name

*warning* - this type expresses warnings

*example* - this type is used to indicate that the comment contains an exam=
ple

*details* - this type must include another piece of metadata
indicating what it is detailing more on this in a minute

*variable* - this type is used to document a variable or parameter

*description* - this type is used to describe what the purpose of the
current thing being documented is as per the current/specified key

*see-also* - this type specifies that it contains a listing of doktor
keys that you might also want to look at/search for

A few new pieces of metadata:

*method*
*codeblock*
*example* (?) - those metadata are used for naming a comment
describing a method, example, or codeblock so that you can supply the
same metadata to "detail" comment types or other such constructions
for expounding on things. Perhaps even associating examples with
codeblocks or methods. This adds some possibilities to how things are
published but may introduce too much complexity.

*filetype* - this is usually supplied with the key for the document
and indicates what kind of document it is which may be used in a
publishing context

Issue #1:
The need to associate a codeblock with an example comes from
publishing interests. If I have an example with a block of text
explaining things and then a demostration in code then without
separating them but keeping them associated publishing it correctly
becomes a nightmare. I'm afraid though that this may introduce too
much complexity to deal with.

Issue #2:
Of course simple having to index so many different metadata keys might
be annoying and they should perhaps all be changed to one 'id' or
'name' field. I feel this should be done.

Issue #3:
I figured that the layout of the neutral XML would be similar to how a
javadoc document is arranged with the name and packge followed by a
description and then examples/methods/variables followed finally by
details and perhaps codeblocks. This may be too similar to javadoc,
however and I'd like input on formatting decisions.

Finally, any further comments, ideas, or discussion is welcomed.
Thanks for reading.

Cheers,
Robert Graham