cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Graham <>
Subject Re: RefDoc - Neutral XML Document Format Input/Current State
Date Mon, 01 Aug 2005 12:58:15 GMT
> 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.

Okay, this was something I wasn't sure about, but I thought it might
be the case.

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

Perhaps. I think some sort of "weight" might give the publisher
options while also introducing more complexity to the process.
> > ....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?

I meant instead of what I proposed up there:

@doktor-start type:method, method:methodName
@doktor-start type:codeblock, codeblock:blockName

we have something like:

@doktor-start type:codeblock, name:blockName
@doktor-start type:method, name:methodName

> a) What is the FileGenerator?
> scenario: search the refdoc for "FileGenerator" or navigate the refdoc:
> refdoc/components/FileGenerator
> 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.

I think that these make more sense and give me a good place to start
thinking from, but I'm not sure that with my limited experience with
Cocoon I could develop a comprehensive listing. Elaboration of more
cases would be helpful.

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

I always have believed that a dynamic use was if not the end goal for
this project it was at least the target for RefDoc in the future. We
still have a month to complete whatever it is you'd like and perhaps I
could better achieve it if I knew what you had in mind? Although, I'd
like to finish even if it isn't before September.


View raw message