Yep, totally with you on the reference guide distinction and need. That's why I linked to Android's developer guide, not their API reference section. You may be right about doclava for their API docs, but their guide content is written the good old fashion way. :) I'm obviously not a "core developer" but my hope is that I can still help assemble something similar for Wicket. I especially liked Android's quickview sidebar with links to key classes and related samples, since many Wicket topics are already covered in these ways.
On Mon, Sep 12, 2011 at 1:07 AM, Martijn Dashorst < [email protected]> wrote: > The android docs are generated AFAIK using doclava, a replacement > javadoc doclet. I am not 100% sure what that needs to run online and > if it is something that would run inside Apache infrastructure. But I > am going to look into that for generating our online docs (which will > be available from http://ci.apache.org/projects/wicket/apidocs, > generated by buildbot) > > From what I read on the lemma website (i.e. the marketing blurb)... > What lemma would bring us is a *reference guide*, something that is > sorely missed in our community. With lemma it would be maintainable by > core developers, and not pose an extra burden which docbook would > bring. Executable code is much more favorable than non-executable > code. > > Martijn > > On Mon, Sep 12, 2011 at 7:16 AM, Dan Retzlaff <[email protected]> wrote: > > 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/ > > > > > > -- > Become a Wicket expert, learn from the best: http://wicketinaction.com >
