This affects both the docs and the examples. Since GF 3.1.1 (I believe), the situation with JSF form-based login has improved: you can now use JSF inputText, inputSecret, and commandButton tags instead of plain HTML input tags within the login form.
You still have to use an HTML form instead of a JSF h:form tag.
The examples that use j_security check are security/hello1_formauth, the mailconnector example, and dukes-tutoring. I can fix the first two – Ian, would you like to do dukes-tutoring-war/web/resources/components/formLogin.xhtml or should I?
The only doc that needs correcting is the security-webtier chapter, which reproduces the login.xhtml file (see http://docs.oracle.com/javaee/6/tutorial/doc/bncbx.html#bncca).