Documentation bugs, as pointed out by Marty Hall

This has been posted on the mailing list quite some time ago, and somehow we forgot about it. This is why I am opening a jira issue on this.

regards,

Martin

I am currently switching over my JSF tutorial
(http://www.coreservlets.com/JSF-Tutorial/) from the Sun Reference
Implementation to MyFaces, updating it significantly, and adding in info on:

• MyFaces setup and configuration
• MyFaces/Tomahawk custom validators
• MyFaces/Tomahawk custom components

In the process, I uncovered a few errors or omissions in the current
MyFaces documentation. I mention all of these things in my tutorial, but I
figured the MyFaces team would like to know. Here's what I noticed so far:

1) http://myfaces.apache.org/gettingstarted.html: Required JAR files
A) The docs say that commons-codec-1.2.jar is required only if you are
uploading files, but most of my apps crash when that JAR file is omitted.
These same apps run fine in the Sun RI.

B) The docs do not mention jstl.jar.
First of all, some I18N code crashes if jstl.jar is not included. For
example, if I do this:
<f:view locale="#

">
<f:loadBundle basename="messages" var="msgs"/>
it crashes if jstl.jar is not included, even though JSTL is not being
explicitly used anywhere. The same code runs fine in the Sun RI.
Secondly, since JSTL is supposed to be bundled with JSTL, IMHO you should
mention jstl.jar on the gettingstarted.html page anyhow.

C) The docs do mention commons-validator.jar but do not mention
jakarta-oro.jar. But the MyFaces validators that use regular expressions
(validateEmail, validateRegExpr, etc.) crash if jakarta-oro.jar is not
included.

D) Since you are mentioning some non-JSF-standard stuff here anyhow, you
might as well mention myfaces-extensions.jar, IMHO.

2) General configuration and documentation.
A) File extension. All of the examples use ".jsf" as the file extension. I
actually prefer that over ".faces", but since ".faces" is much more
standard and is what the JSF spec and all the JSF books use, IMHO you
should highlight this change to users and remind them how to edit web.xml
to change the file extension back.

B) Similarly, all the examples use examples-config.xml as the
configuration file. Again, newbie users will be confused since they will be
expecting faces-config.xml. IMHO you should highlight the change and remind
users how to edit web.xml to change the name of the config file.

C) The TLD Javadocs for the h: and f: libraries
(http://myfaces.apache.org/tlddoc/core/) is pretty poor. In contrast, the
TLD Javadocs for the Sun RI
(http://java.sun.com/j2ee/javaserverfaces/1.1/docs/tlddocs/) is pretty
good. Since they refer to the identical tag libraries, is it kosher for you
to just grab the Sun docs and use it as a starting point? Or just have your
link point there?

3) Custom components and validators.
A) I could not see where you document that you need the filter and
filter-mapping definitions in web.xml in order to use the custom components
that use JavaScript. IMHO you need to really highlight this or newbie users
will never figure it out. I also think you should clearly say that the
url-pattern of the filter-mapping needs to match the url-pattern of
servlet-mapping. Otherwise, users who changed the file extension from .jsf
to the more standard .faces will cut-and-paste the filter and
filter-mapping definitions from myfaces-examples, and it won't work.

B) In myfaces-examples, validate.jsf crashes because jakarta-oro.jar is
not in WEB-INF/lib.

C) Most of the online docs for the custom components (e.g.,