New website look: taglib docs

[Michael Jouravlev <jm...@gmail.com>]

<html:base/> seem to have gotten a new attribute: "ref" It is not
included in TLD supplied with 1.2.7, so apparently this is an 1.3
extension. If this is true, docs page should have "since 1.3" note for
this attribute. An example would be great too, kind of like this:

Document root: "/sf"
Navigating to action: "http://localhost:8080/sf/Home.do"
Action forwards to: "/mailreaderpages/home.jsp"
Adding <html:base/> to home.jsp page.

Runtime expansion of Struts tag to HTML tag:
<html:base/> --> <base href=http://localhost:8080/sf/mailreaderpages/home.jsp">
<html:base server="myserver"/> --> <base
href="http://myserver:8080/sf/mailreaderpages/home.jsp">
<html:base target="window1"/> --> <base
href="http://localhost:8080/sf/mailreaderpages/home.jsp"
target="window1">


I am also reposting my prior message on taglib docs. I am doing this
just in case those of you who use GMail did not see the message
delivered to a page now hidden by newer messages.

Repost starts here --------

On page http://struts.apache.org/struts-taglib/tagreference-struts-html.html

(1)

This is hardly readable:

=== cut here ==
base Render an HTML &lt;base&gt; Element Renders an HTML &lt;base&gt;
element with an href attribute pointing to the absolute location of
the enclosing JSP page
=== cut here ==

* Escaped tag angle brackets.
* This particular snippet looks like it was copied right from
Javadocs, the first sentence should obviously be removed.

(2)

On content note, the taglib docs always made me re-reading each
sentence twice or more trying to understand what it was about. For
example, here is submit element
http://struts.apache.org/struts-taglib/tagreference-struts-html.html#submit

This one is perfectly clear: "value - The value of the button label."
While this one left me scratching my head couple of years ago:
"property - Name of the request parameter that will be included with
this submission, set to the specified value." Why it could not be
simply "property - the value of 'name' attribute".

Still not good, both of these descriptions use "value", which happens
to be a meta-word. Such words as "value", "name", "parameter",
"forward", "redirect" should be used very carefully if there is a risk
to confuse an attribute name (here you have it) or a particular
request method with a meta-word.

So, I would change the first one to a simple:
"value - the 'value' of the button."
  or maybe would add some clarification for HTML-challenged people:
"value - the 'value' of the button (a button label, visible to a user)."

And the second one to:
"property - the 'name' of the button."
  or to a more descriptive for HTTP-challenged:
"property - the 'name' of the button (a request key)"

(3)

It is yet another question why the attribute name is "property" and
not just a "name", but this question was possibly raised too many
times on this list. The problem with this name is that a person
knowlegeable of HTML would look for "name", not a "property".

(4)

"property" and "value", being the most important attributes of
"submit" element, should be emphasized with bold.

(5)

There should be examples for the most common usages along with generated HTML.

(6)

Recalling an old discussion of user-defined attributes in the tags,
Struts should have it instead of redefining all standard HTML
attributes and then explaining their meaning. Just define ones that
are parsed and used by Struts, and leave all other attributes to app
developer's discretion, just pass them through to HTML. We should
trust developers who use the framework.

Michael.

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