Re: [s2] taglib and tld file -- PROPOSAL!

[Ted Husted <hu...@apache.org>]

eOK, I sorted out my issues with the maven-taglib plugin (needed to
specify the version), and we have that up and running now.

* http://struts.apache.org/2.x/

There are two issues I've found so far (and filed with the
maven-taglib project).

First, the plugin generates two sets of docs. An ominus "reference
sheet" and a set of javadoc-like "tlddocs". The reference sheet works
great, but it's one page for the entire taglib. Once we add the
example code, it will be a little-bit on the huge size :)

* http://struts.apache.org/2.x/tagreference.html

The tlddocs would work great too, except that the line-wrapping for
the example code is being lost. If that worked, then we could utilize
the tlddocs, same as javadocs.

* http://struts.apache.org/2.x/tlddoc/index.html

Second, we have the one Struts Tags taglib, which is cool, but once we
add all the examples, the TLD file too will be a little-bit on the
huge size :(

One workaround would be to use XML entities to include the example
code from separate files. But, when I tried that, the plugin ignored
the entities.

So far, I only added the example code for two tags, just so we could
see what it looks like.

*  http://struts.apache.org/2.x/tagreference.html#doubleselect
*  http://struts.apache.org/2.x/tagreference.html#subset

If the "example" line wrapping issue on the tlddoc versions is fixed,
so that  the examples displayed like the tag reference, then we would
be very close to where we were before:

* http://wiki.opensymphony.com/display/WW/doubleselect
* http://wiki.opensymphony.com/display/WW/subset

So, if we follow this tact, the action plan would look like:

* Update TLD from WW head and revise class references
** (/s/com.opensymphony.webwork/org.apache.struts2)

* Update TLD with snippets from Javadocs
** Remove example snippets from Javadocs (to avoid maintenance)

* Refer to Tag Reference (and Javadocs) from wiki docs
** Remove old tag reference pages

* When creating a distribution, update references in the wiki docs to
point to a local copy of the Tag and Java references. (ugh!)

* Work with maven-taglib team to fix "no-wrap example" and "ignores
enities" issues with tlddocs
(http://sourceforge.net/tracker/index.php?func=detail&aid=1543474&group_id=93991&atid=606303).

So, moving forward, we would maintain the struts-tags.tld, embedding
the example code there, and let the plugin generate the tag reference
and tag API docs. We would not need to maintain the xdoclet code, or
create a reference page in the wiki for each tag.

If we convince Maven or the plugin to observe XML entities, we can
move the example elements to separate files, making the rest of the
TLD more maintainable.

If anyone would like to explore another approach, now is the time to
jump in and make it so. One obvious alternative would be to try to use
the xdoclet plugin to do things as they were done before, or maintain
an minimal ant buildfile to do the same. I'm not opposed to any of
that, but I don't have the bandwidth to research it myself. If someone
wants to try an alternative to the maven-taglib plugin, now is the
time to volunteer.

-Ted.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org

Re: [s2] taglib and tld file -- PROPOSAL!

[Ted Husted <hu...@apache.org>]

On 8/20/06, Ted Husted <hu...@apache.org> wrote:
> So, if we follow this tact, the action plan would look like:
>
> * Update TLD from WW head and revise class references
> ** (/s/com.opensymphony.webwork/org.apache.struts2)

Since WW 2.2.3 just hit the street, I'll update our TLD to match the
one in that distribution, and proceed with the rest of the plan. I'm
thinking we could tag the build for 2.0.0 within the next few days. It
sounds like the new API is almost done, so we should have that ready
for 2.0.1.

I already updated the "Tag Developers Guide" to reflect the new taglib
references, and it's looking good!

* http://cwiki.apache.org/WW/tag-developers-guide.html

>
> * Update TLD with snippets from Javadocs
> ** Remove example snippets from Javadocs (to avoid maintenance)
>
> * Refer to Tag Reference (and Javadocs) from wiki docs
> ** Remove old tag reference pages
>
> * When creating a distribution, update references in the wiki docs to
> point to a local copy of the Tag and Java references. (ugh!)
>
> * Work with maven-taglib team to fix "no-wrap example" and "ignores
> enities" issues with tlddocs
> (http://sourceforge.net/tracker/index.php?func=detail&aid=1543474&group_id=93991&atid=606303).
>
> So, moving forward, we would maintain the struts-tags.tld, embedding
> the example code there, and let the plugin generate the tag reference
> and tag API docs. We would not need to maintain the xdoclet code, or
> create a reference page in the wiki for each tag.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org