Paul DuBois wrote:
> At 16:07 -0700 5/11/02, Hans Bergsten wrote:
>
>> The getRowCount() method is described in "10.9 Interface Result", and
>> the fact that an object implementing the Result interface is used to
>> hold the result from <sql:query> is decsribed in "10.3 <sql:query>".
>
>
> I understand your point (I think), but I'm going to disagree with it
> a little bit. One of the virtues of tags is that you don't have to
> be, or shouldn't have to be, a programmer to use them. The sections
> of the spec that you cite require that I as a tag user make the leap
> from seeing getRowCount() mentioned in the spec to figuring out that
> ${result.rowCount} can be used to get the same value.
>
> Maybe that connection is mentioned somewhere, but if it is, I missed it.
> Just a mention of this principle, if it is indeed a JSTL principle,
> somewhere early in the spec would be helpful to many of its readers.
True, but please also note that a specification is not the same as
a user's guide. The specification must contain a lot of details that
a regular user may not need, so that it can be implemented independently.
At the same time, it must leave out information that a typical user
might find useful, otherwise non-essential information needed to
implement the specification would drown in the "user informtion". That
said, the JSTL spec tries to strike a balance between the two extremes
and includes an overview for each part of the spec with examples to
place the actions in a user context. These examples are also useful
to the typical user.
The leap from getRowCount() to ${result.rowCount} is indirectly described
in the parts about the EL (such as Appendix A), since they say that
the EL can access bean property getter methods with this syntax. I
agree that it's not a leap the typical JSP page author will make, but
then again, a specification is not targetted to the end-user. An
experience Java programmer, however, should be able to make this connection.
>>
>> All information needed to implement the JSTL actions is provided in the
>> spec, and this should also provide all information you need to use JSTL.
>> Like Shawn said, detailed examples of how to develop applications with
>> the JSTL actions are not included, but will be covered by many books
>> shortly. Two that I know of are Shawn's upcoming JSTL book (Manning)
>> and the second edition of my JSP book (O'Reilly), to be released soon.
>>
>> Since this is an open source project, you are of course welcome to
>> add as much documentation as you think is needed. Just write it and
>> submit it to the list.
>
>
> I understand that point, too. But the working group *is* asking for
> comments on the spec. I'm making a comment, one that I hope is a
> constructive
> one.
Oh, sure. All comments are welcome. Please don't take my reply as a
discouragement for comments. I just wanted to answer the specific
question (as I understood it) and try to clarify the different goals for
a specification and a "user's guide". Other members of the team may
think that addressing your comment is within the charter for the spec.
It's too late for 1.0, though, since it's frozen at this point.
> Don't take it as a slam on the spec, which I view as light years
> ahead of previous editions - just as beta2 is so much nicer to work with
> than EA3.
I didn't, and I'm glad you noticed the improvements made for each rev of
the spec.
> Besides, the messages of this thread pretty much constitute the necessary
> documentation.
Also, I'm serious about submitting documentation that you think is
needed to the list. Open source is give and take, and a perfect way
for users to "give" is by submitting documentation (and answer questions
on the mailing list, of course, like you already do).
Hans
--
Hans Bergsten [EMAIL PROTECTED]
Gefion Software http://www.gefionsoftware.com
JavaServer Pages http://TheJSPBook.com
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
