Missing 1.3.x Tag Reference Descriptions

[Paul Benedict <pb...@apache.org>]

I noticed on the Struts 1.3 web site, the reference guide for the tag 
libraries do not have any descriptions. Is this a problem with the 
current Maven 2 plug-in?

http://struts.apache.org/1.x/struts-taglib/tagreference.html#struts-html.tld

Paul

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

Re: Missing 1.3.x Tag Reference Descriptions

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

On 8/25/06, Ted Husted <hu...@apache.org> wrote:
> At this point, I'm uncertain as to how to proceed.

I have to dash, but, for S2, one approach just occurred to me.

The missing part in S2 is XDoclet generating a nominal TLD, for IDEs
and whatnot to use.

Moving forward, we might be able to use the maven-taglib-plugin to
generate a TLD and continue to use the snippet-macro with Confluence
to compose our own taglib reference, as we already have.

* http://cwiki.apache.org/WW/if.html

I'll try to take the maven-taglib-plugin TLD generator for a spin tonight.

Of cousre, this doesn't solve the problem for S1, unless someone wants
to move the documentation and examples to the Java source as
"snippets", and create a cwiki tag reference for S1.

-Ted.

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

Re: Missing 1.3.x Tag Reference Descriptions

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

On 8/24/06, Paul Benedict <pb...@apache.org> wrote:
> I noticed on the Struts 1.3 web site, the reference guide for the tag
> libraries do not have any descriptions. Is this a problem with the
> current Maven 2 plug-in?

They have descriptions, it's just that the plugin is not rendering the
content consistently between the tlddocs and tagreference. Also, they
way we are using HTML markup in the description tags might not work
with later versions of the plugin. Some of what we have in the S1
description element might be better placed in the example element.

We're starting to use the maven-taglib-plugin for Struts 2 as well.

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

To get it work for S2, for some reason, I had to specify the plugin
version in the pom.xml. Looking at the respective taglib sources, and
the output, I'd guess that we are not using the same plugin version
for Struts 1 and Struts 2.

In the S1 TLD, we use HTML markup in the tag and attribute description
elements, by virtue of the <![CDATA ... ]]> tag. When I try this for
S2, using maven-taglib-plugin 2.3, the HTML markup is escaped in the
tagreference, but it renders in the tlddocs. Meanwhile, in the S1
docs, the CDATA is being omitted altogether.

Rendering HTML markup from CDATA code in the descriptions is an
interesting idea, but I'm not sure if it's a bug or a feature. If it's
a feature, I wonder if there is a switch to govern it (that we haven't
turned on for S2). I dont' see any mention of such a thing in the
plugin documentation for either version 1 or version 2.

* http://maven-taglib.sourceforge.net/
http://maven-taglib.sourceforge.net/m2/

If we don't use CDATA in the descriptions, the 2.3 plugin *almost*
works well for us. I've filed two issues with the SourceForge project.
First, on the tlddocs, the linewraps for the CDATA code are not being
honored, and it displays as a single line. Second, including XML
entities is not honored, meaning we can't extract the example elements
to seperate file to reduce the TLD file size. (The latter may be a
Maven issue, I'm not sure.)

* http://sourceforge.net/tracker/?atid=606303&group_id=93991&func=browse

Looking at the S1 TLDs, it appears a lot of rework would be needed to
get them to work with latest maven-taglib-plugin. The way we use CDATA
there to convey markup in the description elements is apparently not
supported by 2.3. However, if we started to use the example tag in S1,
much of the need for the markup in the description element might go
away.

For JSP 2.x, the TLDs are no longer required, and the maven-tablig
plugin says it can generate a skeleton TLD, if you need one. I'm
wondering if we want to continue to invest in the TLD format or not.
For the 1.2 series, we generated our own HTML from the TLDs.

* http://struts.apache.org/1.2.x/userGuide/struts-bean.html

Maybe we need to look at a way that we could go back to that.
Otherwise, we might need to take a look at the maven-taglib-plugin
source and start suggesting some patches. The tags are essential, and
the tag documentation is essential, and we may need to become directly
involved in how it is generated (again).

S2 was using the XDoclet plugin to generate the TLD, and then we used
the snippet macro to create our own cwiki-based tag reference from the
Java source code. Right now, XDoclet and Maven 2 are not compatible,
but that's something that could be fixed soon. Again, if we want to go
back to using XDoclet, we may need to become more involved, to ensure
we continut to get the results we need.

At this point, I'm uncertain as to how to proceed.

-Ted

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

Re: Missing 1.3.x Tag Reference Descriptions

[Wendy Smoak <ws...@gmail.com>]

On 8/24/06, Paul Benedict <pb...@apache.org> wrote:

> I noticed on the Struts 1.3 web site, the reference guide for the tag
> libraries do not have any descriptions. Is this a problem with the
> current Maven 2 plug-in?
>
> http://struts.apache.org/1.x/struts-taglib/tagreference.html#struts-html.tld

Are there any related issues open for the plugin?  Are the missing
descriptions actually in the tlds?  Do they show on the other form of
generated docs, (tlddoc)?

http://struts.apache.org/1.x/struts-taglib/tlddoc/html/tld-summary.html

-- 
Wendy

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