beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Hanson <stevelukehan...@gmail.com>
Subject Re: New Tool for Doc'ing NetUI Tag Libraries
Date Thu, 08 Dec 2005 22:48:31 GMT
No problem Eddie, I will hold off for now.

In case you find it useful, here is the text of my exchange with Mark Roth (
markroth8@gmail.com), the lead of tlddoc:

Hi Steve,

Nice to hear from you - great work on Beehive!

On Fri, 2005-12-02 at 14:01 -0800, Steve Hanson wrote:
> Hi Mark:
>
> I am looking around for tools to document the taglibraries in Apache
> Beehive (http://beehive.apache.org/).
>
> tlddoc is currently my favorite choice, but I have a question:

Awesome!  Glad to hear taglibrarydoc is useful to you and you're
considering using it for Beehive!

> Is it ok (according to the BSD license) to checkin tlddoc.jar to the
> Beehive source tree?  We would not be distributing tlddoc.jar with any
> Beehive release distributions, but it would be part of the source
> tree.

Absolutely, so long as you retain the copyright notice.  The BSD license
is one of the most liberal licenses and that's why I chose it.  You can
see the entirety of the license here:

 http://www.opensource.org/licenses/bsd-license.html

The relevant portion is:

"Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution."

It's strange how these things work.  I started the project while I was
working at Sun and now I've moved on to another position but Sun retains
the copyright.  So basically you can commit the JAR but you just have to
include a file that says that taglibrarydoc is licensed under BSD and is
copyrighted by Sun Microsystems (look at one of the source files for the
full copyright message).

FYI, if I find some time this weekend I'll be releasing a new version
with support for the new features in the JSP 2.1 specification.

Thanks for your interest, and best of luck with Beehive!

- Mark

On 12/8/05, Eddie O'Neil <ekoneil@gmail.com> wrote:
>
> Steve--
>
>   Give me an opportunity to clear this with the Apache legal folks
> before we commit this to the SVN tree.  Will be easier to keep it out
> at first than take it out later.
>
>   Will let you know what I hear back.
>
> Thanks!
>
> Eddie
>
>
> On 12/8/05, Steve Hanson <stevelukehanson@gmail.com> wrote:
> > An update on this issue.
> >
> > I have talked to the devs at tlddoc and they have assured me that its ok
> to
> > checkin the tlddoc.jar into the source tree (provided we include a copy
> of
> > their copyright notice).
> >
> > So, unless anyone objects, I will start to implement option (2) below.
> >
> > On 11/10/05, Steve Hanson <stevelukehanson@gmail.com> wrote:
> > >
> > > Hi all:
> > >
> > > In the coming couple of weeks, I would like to change the way that the
> > > NetUI JSP tags are doc'd.
> > >
> > > Currently the NetUI tags are doc'd using a doclet (the "JSP Taglib
> > > Doclet") developed by myself and Steve Traut.  It's a nice tool, but
> it has
> > > drawbacks: namely, (1) it has a dependency on XMLBeans and (2) it
> creates
> > > duplicated javadoc content in the NetUI tag Java classes.
> > >
> > > Please take a look at these options for a replacement doc tool.  If
> you
> > > any clear preferences, or other suggestions, please speak up.
> > >
> > > thanks,
> > > Steve Hanson
> > >
> > > (1) Plain old javadoc
> > >
> > > Sample doc:
> http://beehive.apache.org/docs/1.0/apidocs/classref_netui/org/apache/beehive/netui/tags/html/Anchor.html
> > >
> > >
> > > Drawbacks: Users have to translate Javadoc-isms into
> taglibrary-isms.  For
> > > example, they have to read the method "setName()" as the tag attribute
> > > "name".  Also, certain info important to tags is left out.  For
> example,
> > > whether an attribute is required or optional.
> > >
> > > (2) tlddoc (Sun's tool available at
> https://taglibrarydoc.dev.java.net/)<
> https://taglibrarydoc.dev.java.net/%29>
> > >
> > > Sample doc: http://struts.apache.org/struts-taglib/tlddoc/index.html
> > >
> > > Tlddoc can be run against the Java source directly or against the TLD
> > > files.  The output looks nice, to me at least.
> > >
> > > Open question: can we legally checkin the tlddoc.jar?  Some people
> have
> > > said "no".  But I see other projects have checked in the jar:
> > > http://cvs.sourceforge.net/viewcvs.py/myfaces/myfaces/lib/tlddoc
> > > .jar?rev=1.1&view=log
> > >
> > > Giving the BSD license a quick skim, it seems ok to checkin the jar,
> but I
> > > hesitate.  Does anyone understand the BSD license well enough to
> answer this
> > > question?
> > >
> > > (3) Maven taglib plugin (available at
> http://maven-taglib.sourceforge.net/
> > > )
> > > Sample doc:
> > > http://struts.apache.org/struts-taglib/tagreference-struts-html.html
> > > (I am not sure why Struts uses both tlddoc and Maven to doc the same
> > > taglibs.)
> > >
> > > This doc doesn't look as nice as the tlddoc, but I list it here as a
> > > possibility.
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message