Merge pull request #462 from handrews/wording

Improve wording with feedback from awwright

Author: handrews

jsonschema-core.xml

@@ -436,10 +436,21 @@
             </t>
             <t>
                 <cref>
-                    While this pattern is likely to remain best practice for schema authoring,
-                    implementation behavior is subject to be revised or liberalized in future
-                    drafts.
+                    Using multiple "$schema" keywords in the same document would imply that the
+                    vocabulary and therefore behavior can change within a document.  This would
+                    necessitate resolving a number of implementation concerns that have not yet
+                    been clearly defined.  So, while the pattern of using "$schema" only in root
+                    schemas is likely to remain the best practice for schema authoring,
+                    implementation behavior is subject to be revised or liberalized in
+                    future drafts.
                 </cref>
+                <!--
+                    In particular, the process of validating an instance, including validating a
+                    schema as an instance against its meta-schema, only allows for a single set
+                    of rules across the entire instance document.  There is no equivalent of
+                    changing the meta-schema partway through the validation for non-schema
+                    instances.
+                  -->
             </t>
             <t>
                 Values for this property are defined in other documents and by other parties.

jsonschema-hyperschema.xml

@@ -182,10 +182,10 @@
                             in the Link Description Object.
                         </t>
                         <t hangText="generic user agent">
-                            A user agent which is only aware of standardized link relations,
-                            media types, URI schemes, and protocols.  It may have an extensible
-                            architecture to allow adding support for standards beyond the core
-                            set of which it is aware.
+                            A user agent which can be used to interact with any resource, from
+                            any server, from among the standardized link relations, media types,
+                            URI schemes, and protocols that it supports; though it may be
+                            extendible to specially handle particular profiles of media types.
                         </t>
                         <t hangText="client application">
                             An application which uses a hypermedia system for a specific
@@ -1788,7 +1788,8 @@ Link: <https://schema.example.com/entry> rel=describedBy
                 </figure>
                 <t>
                     Notice the "href*" keywords in place of "targetUri".  These are three
-                    possible "targetUri" values covering different sorts of input:
+                    possible kinds of "targetUri" values covering different sorts of input.  Here
+                    are examples of each:
                     <list style="hanging">
                         <t hangText="No additional or changed input:">
                             "mailto:[email protected]?subject=The%20Awesome%20Thing"