Hi, I spent this afternoon evaluating the use of Lemma for Wicket's reference documentation. Prior to its mention by Martijn, I had evaluated Docbook since it appears to be something of a de facto standard for open source projects. While I am personally quite comfortable with XSLT and friends, I conclude that any advantages Docbook has over less abstract formats are outweighed by its massive DTD and stylesheets.
*Why Lemma?* Lemma is relatively light weight, and well-aligned with Wicket's philosophy of "just Java and HTML." Content is primarily maintained directly in XHTML. Citation mechanisms allow subsets of Java (Javadoc and code), XML and plain text files to be pulled into the document. Its implementation is based on a simple Pipeline class (XHTML in, XHTML out) which comprises an ordered list of Processors (XHTML in, XHTML out) that each do something simple like tables-of-content generation or citation validation/decoration. In the wild world of software, I consider Lemma's to be Good Code. :) *Lemma Customization.* Unfortunately, the only Pipeline provided by Lemma, XHTMLTemplateJavadocPipeline, is too simplistic for a product like Wicket. In particular, it only supports a monolithic output document and assumes that all cross-references are resolvable within that single document. In my opinion, a hierarchical, multi-page site like the Android Developer's Guide [1] will serve Wicket much better. I have penciled out the few Lemma customization classes we would need to build such a multi-page site. The crux is a Pipeline which follows relative links in its input XHTML and outputs a Map<String, XHTML> for the site keyed by path. I'll implement them over the next few days as time permits and share the results. I only mention this now in case someone else is working down a similar (or different) path, in which case I'd like to share notes. *Why not Wicket?* I keep asking myself why we don't use Wicket instead of Lemma. Lemma is certainly the simpler tool, but given the subject matter Wicket seems appropriate. By my estimation, a Wicket-based solution that's as easy to use as Lemma would need: 1) an offline rendering processor, 2) an IMarkupFilter that recognizes citations and instantiates citation components, and 3) citation components that return IMarkupFragments from Java, XML, text or Javadoc based on the citation type. Any thoughts or interest in such a solution? Dan [1] http://developer.android.com/guide/
