cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <>
Subject Re: RefDoc - Neutral XML Document Format Input/Current State
Date Mon, 01 Aug 2005 08:58:02 GMT
Hi Robert,

Thanks for your analysis - I hope others are going to answer as well, 
but here are at least my comments:

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

ok - my view was a more high-level one than classes and methods, which 
are adequately covered by the javadocs. These are certainly useful 
though, but see the proposed use-cases below for a more 
component-oriented view.

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

ok, we'll need to be more detailed here I think, differentiating 
sitemap parameters, component configuration parameters, etc.

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

ok, this is a very important one.

> A few new pieces of metadata:
> *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...

ok, this will be needed for example to republish XML snippets as XML I 

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

The sorting of snippets to build the final document will be a problem 
as soon as there are more than a few snippets. Maybe introducing an 
"order number" metadata attribute would help and not be too hard to 
manage? We could then rearrange the snippets be changing their order 
numbers, while keeping the overall order based on the snippet types.

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

I'm not sure what you mean here, can you elaborate or give an example?

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

Starting from a javadoc model is certainly good.

> ...Finally, any further comments, ideas, or discussion is welcomed...

I'm just going to add a few brief use-cases, or rather a few example 
questions that I'd like refdoc-generated documentation to answer:

a) What is the FileGenerator?
scenario: search the refdoc for "FileGenerator" or navigate the refdoc: 

b) Which generator can read URLs through a proxy?
scenario: full-text search for a refdoc document from the "components" 
collection, containing both the "URL" and "proxy" words.

c) What sitemap parameters can be used for the FileGenerator?
scenario: find the document as in a), the document contains a list of 
parameters build from "sitemap-parameter" metadata elements found in 
doktor comments. The parameter descriptions stay up to date as the 
@doktor comments are right next to the source code which reads the 
parameter, so people remember to keep them up to date.

d) I need an example of how to use the HtmlTransformer in a sitemap
scenario: search the refdoc for a snippet ot type "sitemap-example" 
where property "component-name" is HtmlGenerator. The snippet points to 
its "parent document" which describes the HtmlGenerator.

It might be good to elaborate on these use-cases and maybe document 
them in a text file in the refdoc block, but for now I hope they help 
clarifiy the needs and priorities.

Note that these assume a dynamic search of the refdoc index - I think 
the full power of the refdoc will be available only when querying the 
Lucene index directly, as is done in some of these use-cases, but the 
document-oriented version (that will probably be published as static 
HTML pages) will contain the same information, only with less precise 
searches. The Lucene index will be available to people who start Cocoon 
on their own machines anyway, so I think having to use the Lucene index 
for precise queries is not a big problem.


View raw message