W3C home > Mailing lists > Public > www-tag@w3.org > January 2009

editorial: assorted

From: Barclay, Daniel <daniel@fgm.com>
Date: Fri, 30 Jan 2009 15:58:45 -0500
Message-ID: <49836A05.80705@fgm.com>
To: <www-tag@w3.org>
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 ...

.)



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.

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]
Received on Friday, 30 January 2009 20:59:53 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 26 April 2012 12:48:11 GMT