Thoughts on Lemma-based Wicket Reference Docs

[Dan Retzlaff <dr...@gmail.com>]

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/

Re: Thoughts on Lemma-based Wicket Reference Docs

[Dan Retzlaff <dr...@gmail.com>]

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 <
martijn.dashorst@gmail.com> 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 <dr...@gmail.com> 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
>

Re: Thoughts on Lemma-based Wicket Reference Docs

[Martijn Dashorst <ma...@gmail.com>]

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 <dr...@gmail.com> 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