Hibernate guide review feedback

For https://issues.jboss.org/browse/JBEAP-11963, did a review of the Hibernate guide. Some minor updates were submitted through that JIRA, but here are the rest of the outstanding items from the review:

1. "For the ID FieldCache to be used, the ids of targeted entities must be using a TwoWayFieldBridge (as all builting bridges)"
   • What is "builting" supposed to be? Can this part just be removed?
2. "By design Hibernate Search stores an untokenized ID in the index to ensure index unicity for a given entity."
   • Can this be reworded to remove the word "unicity"? Might be a real word, but not sure. Either way it's odd.
3. "searchFactory.optimize() is applied to the master node because it does not affect the JMC back end."
   • Should "JMC" be "JMS"?
   • This looks like it might be a repeat of the above note, maybe could be removed altogether?
4. "For the complete list of connection properties, see Connection Properties Configurable in the persistence.xml File in the JBoss EAP Development Guide."
   • This link does not exist in the Development Guide.
5. "Through JPA applications, using persistence.xml in the JBoss EAP Development Guide"
   • This link does not exist in the Development Guide.
   • Also the way this link and book name are used in this sentence make the sentence not make sense. It should be reworded or separated into two sentences.
6. "The main use cases for an org.hibernate.integrator.spi.Integrator are registering event listeners and providing services, see org.hibernate.integrator.spi.ServiceContributingIntegrator."
   • Should this link point to the EAP Javadocs instead of the ones on jboss.org? There might be other instances like this as well.
7. In the table "List of Available LockFactory Implementations", the first cell has the text "LockFactory Configuration" which doesn't look like it belongs.
8. "You can achieve this by using one of the following code snippets (see also ):"
   • This is missing a link. Check the EAP 6 docs in case a link was accidentally dropped.
9. "If it does represent an entity, the resulting instances are returned in the NEW state (not managed!)."
   • Reword the "(not managed!)" part w/o exclamation point and w/o parentheses
10. “The prior release of JBoss EAP included Hibernate 4.2 and Hibernate Search 4.6”
    • The release version needs to be specified here, because that’s not true for the 7.1 version. Should it be “JBoss EAP 6 included…” ?
11. “the same way an HQL, JPA-QL, or native query would.”
    • Is "JPA-QL" supposed to be "JPQL"?
12. "and lets you build your customized analyzer in a very flexible way (like Lego)"
    • Is this supposed to be like the LEGO building blocks? Can this just be removed?
13. "Alternatively, use the Hibernate Search query DSL, which selects the correct analyzer automatically. See "
    • There is a hanging "See". Check the EAP 6 docs in case a link was accidentally dropped.
14. "It is important for the two-way process to be idempotent (i.e., object = stringToObject( objectToString( object ) ) )."
    • I think this could be improved/explained better.
15. "While the filter can be a regular filter (as defined in )"
    • I don't understand what "as defined in" is supposed to be saying. Maybe it is missing a link when it was converted from the EAP 6 docs?
16. These few sentences seem to run on really long and should probably be broken up and reworded to remove parentheses:
    • "With some queries, the class type will not be needed at all, in that case even if you enabled the CLASS field cache, this might not be used; for example if you are targeting a single class, obviously all returned values will be of that type (this is evaluated at each Query execution)."
    • "For the ID FieldCache to be used, the IDs of targeted entities must be using a TwoWayFieldBridge (as all builting bridges), and all types being loaded in a specific query must use the fieldname for the id, and have IDs of the same type (this is evaluated at each Query execution). "
    • "A Directory is the most common abstraction used by Lucene to represent the index storage; Hibernate Search does not interact directly with a Lucene Directory but abstracts these interactions via an IndexManager: an index does not necessarily need to be implemented by a Directory. "
17. "the recommended approach is to use a MassIndexer: see for more details."
    • Missing a link after "see". Check EAP 6 docs again.
18. Section 7.7.1. Automatic Optimization has two lines where probably only one should be shown:
    • "Hibernate Search can automatically optimize an index after either:"
    • "Infinispan Query automatically optimizes the index after:"
19. The items under “Directory Providers and Their Properties” have some issues
    • They do not use the same formatting, for example, “filesystem” and “filesystem-master”.
    • The sentences under “filesystem-master” could maybe be combined into paragraphs, instead of each sentence being on a separate line. Also some oddities like the “Like filesystem.” sentence standing alone.
    • Inconsistent use of punctuation and the end of items in the various sections.
20. "7.3.1. First Steps with Hibernate Search" lists topics to start with, but is missing an "Add Annotations" section that is there as well.
21. Bootstrap Registry - This is displayed several ways “Boot-strap Registry”, “BootstrapRegistry”. Should be consistent in usage. I don’t believe that should be a hyphen, so it should either be “Boostrap Registry” or “BoostrapRegistry”.
22. "See Similarity's Javadocs for more information."
    • This could provide a link to the Javadocs.
23. SQL code examples could be marked with "source,sql"
24. There are a lot of instances of "via" that should be replaced with "by/using" or reworded.
25. There are some inconsistencies on syntax for replaceable values. They should be uppercase and italicized.
    • For example, "default.<indexname>.indexwriter.<parameter_name>" should be "default.INDEX_NAME.indexwriter.PARAMETER_NAME"
26. The diagrams should probably be given to our graphic designers (Emme Eble and Jessica Schaefer) to conform with brand standards.
    • Figure 7.1. Lucene Back-end Configuration
    • Figure 7.2. JMS Back-end Configuration
    • Figure 7.3. JMS Backend Configuration
27. At some point, this guide should be reviewed and the appropriate literal values/classes should be monospace as appropriate. There a lot of insteances where words look to be inappropriately capitalized, but it’s because they should have backticks to be monospace. For example, “List” and “Object[]” in this sentence:
    • First, the query can specify to return a List rather than an Object[] for scalar results: