It can be confusing for application developers, who need to either output unescaped html to a page, or escape the html output to show the special characters to the users, to know how to accomplish this.

One source of confusion is that escaping requirements can vary between text rendered as an html attribute, or within special tags like button and an input with type of textarea, or just inline in the page.

The other main complication is that Facelets .xhtml files are themselves xml files that go through an xml parser, and so can't directly contain certain html identities, and so require additional escaping. Alternatively, text specified in a resource bundle will have it's own escaping considerations, that are completely different. And finally, hard-coded Java strings may be the easiest to deal with, but are the worst practice of the two.

So, we should create a tutorial that shows how to output all the various html identities, greater-than and less-than, and unicode characters, specified right in the Facelets .xhtml file, .properties resource bundle, and hard-coded Java strings, for each of the different components, which may provide the option for escaping or not escaping.

This might also facilitate our framework and component regression testing for escaping.