misc minor doc cleanups

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18875 1b8cb986-b30d-0410-93ca-fae66ebed9b2

entitymanager/src/main/docbook/en/modules/metamodel.xml

@@ -23,8 +23,8 @@
   ~ Boston, MA  02110-1301  USA
   -->
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY jpa2Biblio '<xref linkend="JPA2"/>'>
+<!ENTITY jpa2Ref '<xref linkend="JPA2"/>'>
-<!ENTITY jpa2Cite '<citation>&jpa2Biblio;</citation>'>
+<!ENTITY jpa2Cite '<citation>&jpa2Ref;</citation>'>
 <!ENTITY criteriaRef '<xref linkend="querycriteria"/>'>
 <!ENTITY apt '<ulink url="http://java.sun.com/javase/6/docs/technotes/tools/solaris/javac.html#processing">annotation processor</ulink>'>
 ]>
@@ -43,20 +43,19 @@
     <para>
         The metamodel is a set of objects that describe your domain model.
         <interfacename>javax.persistence.metamodel.Metamodel</interfacename> acts as a repository of these metamodel
-        objects and provides access to them.  We ask either the
+        objects and provides access to them, and can be obtained from either the
         <interfacename>javax.persistence.EntityManagerFactory</interfacename> or the
-        <interfacename>javax.persistence.EntityManager</interfacename> for a reference to the
+        <interfacename>javax.persistence.EntityManager</interfacename> via their
-        <interfacename>javax.persistence.metamodel.Metamodel</interfacename> via their
         <methodname>getMetamodel</methodname> method.
     </para>
 
     <para>
         This metamodel is important in 2 ways.  First, it allows providers and frameworks a generic way to
         deal with an application's domain model.  Persistence providers will already have some form of
-        metamodel that they use to describe the domain model being mapped.  This API simply allows general access
+        metamodel that they use to describe the domain model being mapped.  This API however defines a single,
-        to that existing information.  A validation framework, for example, could use this information to
+        independent access to that existing information.  A validation framework, for example, could use this
-        understand associations; a marshaling framework might use this information to decide how much of an
+        information to understand associations; a marshaling framework might use this information to decide how
-        entity graph to marshal.  This usage is beyond the scope of this documentation.
+        much of an entity graph to marshal.  This usage is beyond the scope of this documentation.
     </para>
 
     <important>
@@ -86,7 +85,7 @@
 
         <blockquote>
             <attribution>
-                <citation><xref linkend="JPA2"/>, section 6.2.1.1, pp 198-199</citation>
+                <citation>&jpa2Ref;, section 6.2.1.1, pp 198-199</citation>
             </attribution>
             <para>
                 <itemizedlist>
@@ -233,7 +232,7 @@ public class Person_ {
             When the Hibernate <interfacename>EntityManagerFactory</interfacename> is being built, it will
             look for a canonical metamodel class for each of the managed typed is knows about and if it finds
             any it will inject the appropriate metamodel information into them, as outlined in
-            <citation><xref linkend="JPA2"/>, section 6.2.2, pg 200</citation>
+            <citation>&jpa2Ref;, section 6.2.2, pg 200</citation>
         </para>
     </section>
 

entitymanager/src/main/docbook/en/modules/query_criteria.xml

@@ -22,7 +22,12 @@
   ~ 51 Franklin Street, Fifth Floor
   ~ Boston, MA  02110-1301  USA
   -->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY jpa2Ref '<xref linkend="JPA2"/>'>
+<!ENTITY jpa2Cite '<citation>&jpa2Ref;</citation>'>
+<!ENTITY staticMetamodelRef '<xref linkend="metamodel-static"/>'>
+]>
+
 <chapter id="querycriteria">
     <title>Criteria Queries</title>
 
@@ -65,10 +70,10 @@
 
     <note>
         <para>
-            <citetitle pubwork="chapter">Chapter 6 Criteria API</citetitle> of the
+            <citetitle pubwork="chapter">Chapter 6 Criteria API</citetitle> of the &jpa2Cite; already contains a
-            <citation><xref linkend="JPA2"/></citation> already contains a decent amount of reference material
+            decent amount of reference material pertaining to the various parts of a criteria query.  So rather
-            pertaining to the various parts of a criteria query.  So rather than duplicate all that content here,
+            than duplicate all that content here, lets instead look at some of the more widely anticipated usages
-            lets instead look at some of the more widely (anticipated) usages of the API.
+            of the API.
         </para>
     </note>
 
@@ -124,7 +129,7 @@ for ( Person person : people ) { ... }]]></programlisting>
                         <para>
                             <emphasis>Person_.eyeColor</emphasis> is an example of the static form of metamodel
                             reference.  We will use that form exclusively in this chapter.
-                            See (todo link to metamodel section once written).
+                            See &staticMetamodelRef; for details.
                         </para>
                     </callout>
                 </calloutlist>
@@ -486,7 +491,7 @@ for ( Tuple tuple : valueArray ) {
         <title>FROM clause</title>
         <blockquote>
             <attribution>
-                <citation><xref linkend="JPA2"/></citation>
+                <citation>&jpa2Ref;, section 6.5.2 Query Roots, pg 262</citation>
             </attribution>
             <para>
                 A CriteriaQuery object defines a query over one or more entity, embeddable, or basic abstract