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