[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [entity-resolution] system vs. uri: editorial suggestions
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC