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

[Norman Walsh <ndw@nwalsh.com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Mark Johnson <mrj@debian.org> was heard to say:
| 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]." 

Done. I also added system identifier and public identifier as defined terms.

| 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"

Done.

| 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 ..."

Done.

| *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:)

I attempted to reword those sentences to make that point of view clearer.

| 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."

Uhm, I fixed the example instead :-)

| 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"

Done.

| 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'

Done.

| 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.

I hope the addition of those terms to the terminology section will also help.

| 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.'

Done.

                                        Be seeing you,
                                          norm

- -- 
Norman.Walsh@Sun.COM    | To enjoy yourself and make others enjoy
XML Standards Architect | themselves, without harming yourself or any
Web Tech. and Standards | other; that, to my mind, is the whole of
Sun Microsystems, Inc.  | ethics.--Chamfort
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE+oFZ9OyltUcwYWjsRAogzAJ9CdHJzkM7dw0QlIuw/5ERGGotmHwCbBI4L
Jenzmgh8OyXzZptkR00llH4=
=s+rU
-----END PGP SIGNATURE-----