RefDoc Patch

[Robert Graham <in...@gmail.com>]

I would prefer to send out a tarball, but all I have access to right
now is zip so I've been forced to include several files, a
readme, and the patch file of course. I believe this is all you need,
but make sure to check out the readme before trying anything new.

Robert

Re: RefDoc Patch

[Bertrand Delacretaz <bd...@apache.org>]

Hi Robert,

> ...I would prefer to send out a tarball, but all I have access to right
> now is zip so I've been forced to include several files, a
> readme, and the patch file of course. I believe this is all you need,
> but make sure to check out the readme before trying anything new..

I have applied your patch, with a minor change to the sitemap 
(reinstated a pattern="" so that refdoc/ shows the index page), and a 
reference to patch-README.txt in the index page. I haven't included the 
xconf change, as it might have unwanted side effects on other blocks. I 
think this is definitely going in the right direction!

(hint to other community members: you're most welcome to have a look a 
this and speak up ;-)

Here are a few comments:

All snippets of the same file which follow an @doktor:key statement 
should be assigned the same key. For example all snippets in 
AnnotatedClass.java should have the firstExample key, without having to 
repeat the key: property in each of them. This will make it easier to 
annotate existing files, as most of them will contain snippets for a 
single key.

This can be done in XSLT, by looking for the last key: property, for 
example. But there might be an easier way.

Regarding the Lucene indexing, I have had a quick look at the querybean 
block, and the way it uses the LuceneIndexTransformer looks 
interesting. It might be another option to create the index, maybe 
easier to configure from the pipeline than the other Lucene-related 
components. It would be good if you could have a look at this, and if 
we need to improve the existing components from the lucene or querybean 
blocks for the needs of refdoc it's also a possibility.

But this can come later, as the indexing is basically working as is - 
if you prefer to work on the document assembly (getting the full 
snippet content in the assembled documents), no problem.

For the document assembly, the snippets will have to be sorted so that 
the final document makes sense. I assume we'll want to order them by 
type, starting with type:description, then type:parameter (for 
component parameters), then type:example, etc. I don't have a very 
precise idea about this at this point, feel free to suggest what you 
think makes sense.

Also, we need some concrete snippets to test this on more serious 
stuff, do you think you could annotate some of the existing blocks to 
have a concrete use case? The jfor, fop and slop blocks come to mind as 
they do not contain many files and it wouldn't be too much work to 
annotate them, I think.

Thanks very much for your work, It's exciting to see this going forward!

-Bertrand