Re: editorial: assorted

Thank you for these comments.

Daniel Barklay wrote:



> Regarding the document "The Self-Describing Web" at
> http://www.w3.org/2001/tag/doc/selfDescribingDocuments-2008-12-03 :
> 
> 
> Section 4.2.2 begins:
> 
>    [Microformats] provide a simple means of marking up ...
> 
> instead of:
> 
>    Microformats [Microformats] provide a simple means of marking up ...
> 
> (as sections 4.2.3 and 5 begin:
> 
>     XML Namespaces [XMLNamespaces] facilitate the creation ...
> 
> and:
> 
>    RDF [RDF] provides an interoperable means ...
> 
> .)

I would agree if the short names in brackets were generated automatically, 
but they are authored by the editor manually.  I've made the choice that 
in many cases it's easier on the reader if I just ensure that a sensible 
short name is chosen, and avoid the duplication, so for most of these I 
plan not to make a change.  I've received no other complaints about this 
in the year or more that versions using these constructions have been out 
for review.  In cases where I could not conveniently achieve that, use use 
the construction as in 4.2.3. (I never use spaces in the tokens, and 
XMLNamespaces doesn't read well without the space.)  Since you've called 
out the inconsistency, I've changed the RDF [RDF] one to read just [RDF].

> 
> 
> The last sentence in section 5 seems to have a similar, though slightly
> different, problem:
> 
>    [NamespaceDocuments] describes this technique in more detail.
> 
> If the document were using numbered reference keys (in the brackets), 
that
> would become something like:
> 
>    [123] describes this technique in more detail.
> 
> That's more clearly wrong (if that's not clear, recall that "[123]" 
meant
> a superscripted "123"), and should instead be:
> 
>    Reference 123 describes this technique ...
> 
> or
> 
>    _Associating Resources with Namespaces_ [123] describes this 
technique ...
> 
> However, applying the first pattern would yield:
> 
>      Reference NamespaceDocuments describes ...
> 
> which doesn't work.

I'm pretty sure you meant the last sentence of section 4.2.3.   Note that, 
just above the sentence you quote, we find the first reference in this 
fragment:

"The TAG Finding "Associating Resources with Namespaces" 
[NamespaceDocuments], recommends "

Given that it's been introduced that way, I don't find the problem you 
raise to be really troubling.  I think that, with that already introduced, 
the sentence you point to:

 [NamespaceDocuments] describes this technique in more detail.

is reasonably self-evident.  I would think it's pretty clear that the 
former introduces [NamespaceDocuments] as a key referring to the finding 
"Associating Resources with Namespaces".  Still, since it caused you to 
trip up, I'm changing that to:

The "Associating Resources with Namespaces" Finding describes this 
technique in more detail.

I hope that these dispositions of your comments are satisfactory, and that 
you find the finding as a whole to be useful.  Thank you for taking the 
trouble to comment.

Noah





Probably the sentence in question should read:

   _Associating Resources with Namespaces_ [NamespaceDocuments] describes 
...

(where the underlines denote italicization).



Section 4.2.3 refers to "XML tag names"; that should at least be "XML 
element
names."  (Technically, they're "element type names" per the XML 
specification,
but, admittedly, not all the follow-on XML specifications use that term.)



Section 4.2.3 also says:

   Qualified names map to expanded names such as
   {http://example.org/inventoryNamespace,inventoryItem}, comprised of a
   namespace name URI (http://example.org/inventoryNamespace) and a local
   name (inventoryItem).

The occurrence of "comprise of" there should be "comprised" (the current
usage is backwards).


The relationship between expanded names what one comprises might be 
clearer
if the first part of the sentence used singular terms:

   A qualified names maps to an expanded name such as
   {http://example.org/inventoryNamespace,inventoryItem}, comprising a
   namespace name URI ... and a local  name ...

(You could certainly clarify that in other ways, e.g.,

   Qualified names map to expanded names such as
   {http://example.org/inventoryNamespace,inventoryItem}.  A qualified 
name
   comprises ...

)



Several occurrences of "e.g." and "i.e." aren't punctuated with the 
standard
following commas.



Not all the URIs in the reference section are links (to make them 
convenienct
to the normal degree).

Daniel
--
(Plain text sometimes corrupted to HTML "courtesy" of Microsoft Exchange.) 
[F]




--------------------------------------
Noah Mendelsohn 
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------

Received on Saturday, 7 February 2009 01:26:56 UTC