[entity-resolution] system vs. uri: editorial suggestions

[Mark Johnson <mrj@debian.org>]

Hi All,

Below are some editorial suggestions chiefly aimed at clarifying the
distinction between the uri & system elements and their intended usage 
in XML Catalogs. (I also point out a minor, unrelated, typo.) 

My perspective is not that the spec is unclear as written, but that some
very minor changes/additions would eliminate some misinterpretation on 
the part of the average reader -  such as a package maintainer who needs
to construct a catalog for a set of stylesheets or dtds. Another potential
reader would be the policy authors for xml catalog implementation on a 
given operating system, or flavor thereof.

These are mostly off-the-cuff, as I composed them in transit...


Sec 2 "Terminology"
-------------------

Include an "External Identifier" entry, so as to stress that this term
is used in the formal, technical sense as defined in Production 75 of 
the XML spec.

"The term <i>external identifier</i> is to be interpreted as defined in
Production 75 of [XML]." 


Sec 4.1 "External Identifier Entries"
-------------------------------------

The first sentence of this section 
"External identifiers ([Production 75] of [XML]) ..." 
is of supreme importance and should be referenced by statements in 
other sections. 

Furthermore, to further stress the formal, technical sense in which 
the term 'external identifier' is meant, a minor change of the sentence
to something like:

"<i>External Identifiers</i>, as defined in Production 75 of [XML], 
identify the external subset, ... , and notations of an XML document. 
They are <i>not</i> used to identify resources such as namespace names
and stylesheets; URI entries are used for that purpose"


Sec 4.2 "URI Entries"
---------------------

Perhaps the first sentence should be changed to further highlight the
distinction between External Identifier entries and URI entries. E.g.

"URI references that are <i>not</i> external identifiers, such as 
namespace names, stylesheets, included files, graphics, and hypertext
references, simply identify other resources and should make use of the
uri entries described below. The input to a resolver ..."

*Note that the use of the term "considered" in both Sec 4.1 & Sec 4.2
implies the perspective of the entity resolver, rather than that of a
catalog author. In other words, the explanation is given in terms of 
what catalog elements the resolver considers when parsing a catalog, 
rather than suggesting to a catalog author what might be the 
appropriate catalog element/entry for a given resource. Though I can
see the rationale for this perspective, my gut tells me that more
humans than resolvers will read the document:)


Sec 4.3 "Rewrite Entries"
-------------------------

Add a final sentence after the example, e.g.

"Note that in this example the rewrite prefix consists of a complete
uri reference, rather than a partial uri."


Sec 4.4 An XML Catalog Example
------------------------------

Correct the FPIs in examples 1 & 2 to the current, adopted one:

 "-//OASIS//DTD XML Catalogs V1.0//EN"


Secs 6.5.4, 6.5.5, 6.5.7: (system) Catalog Elements
---------------------------------------------------

The definitions of 'system', 'rewriteSystem', and 'delegateSystem' all
use the term "system identifier", w/o explicitly noting that the system
identifier is an external identifier, and not as some general url. Many 
times have I heard urls referred to as system identifiers, which in the
case of xml catalogs could be a source of confusion. The reader may find
these reference sections a bit more clear if this distinction were made
explicit. 

(Redundancy can be a good pedagogical tool:) 

E.g. replace occurences of 'system identifier' with 'system identifier
employed as an external identifier'

FWIW, I do understand the inherent redundancy of the suggested 
replacement text, but I believe such phrases will give the document
greater clarity to the non-expert.

Secs 6.5.8, 6.5.9, 6.5.10: (uri) Catalog Elements
-------------------------------------------------

Similarly, these definitions should each make it clear that the URI
references are _not_ external identifiers.

E.g. replace the final 'URI reference.' with something like:

'URI reference that is <i>not</i> an external identifier.'

=========

Well, that's it. 

These suggestions essentially address the points I was struggling with 
myself. I hope we can somehow incorporate them at least in spirit, if
not literally.

Thanks,
Mark
      
-- 
_____________________________________
Mark Johnson        <mark@dulug.duke.edu>
Debian XML/SGML     <mrj@debian.org>
Home Page:          <http://dulug.duke.edu/~mark/>
GPG fp: 50DF A22D 5119 3485 E9E4  89B2 BCBC B2C8 2BE2 FE81