Re: Cool URIs for the Semantic Web comments: some errors

Ivan, Danny,

Below is a list of the required changes to the Cool URIs IG Note [1],  
separated into editorial changes and more substantial ones.

Danny (and anyone else who can spare a few minutes), can you please  
double-check the corrections to make sure that I don't slip any new  
errors into the document? ;-)

A big thank you to Daniel for his in-depth review and attention to  
detail.

Best,
Richard

[1] http://www.w3.org/TR/cooluris/


-------------------------------------------------------------------

The following corrections and clarifications are based on feedback
from Daniel Barclay (daniel@fgm.com):
http://lists.w3.org/Archives/Public/public-sweo-ig/2009Jun/0000.html


* In Section 2.1, the second example says:
     Content-Location: http://www.example.com/people.en.html
   but should say:
     Content-Location: http://www.example.com/people/alice.en.html

* Section 3.1 says:
     Bob may not like the look of the homepage, but fancy the person
     Alice.  So two URIs are needed, one for Alice, one for the homepage
     or a RDF document describing Alice.
   Why two URIs are needed isn't clear.  There should be an intervening
   sentence:
     To avoid miscommunication, one has to be specific about which of
     these entities is meant in a statement.

* Section 4.1 says:
     When a client wants to retrieve a hash URI, then the HTTP protocol
     requires ...
   A client does not "retrieve" the URI. This should say "access"
   instead.

* Section 4.1 says:
     ... a URI that includes a hash cannot be retrieved directly ...
   This would be clearer as:
     ... a URI that includes a hash cannot be accessed directly
     via the HTTP protocol ...

* Section 5 says:
     http://ontoworld.org/wiki/Special:ExportRDF/Karlsruhe
   And later:
     A much cooler URI would be for example
     http://ontoworld.org/data/Karlsruhe, as it allows ...
   This should be:
     http://ontoworld.org/index.php?title=Special:ExportRDF/Karlsruhe&xmlmime=rdf
   and
     The latest versions of Semantic MediaWiki have improved their
     URI scheme, and now use
     http://ontoworld.org/wiki/Special:ExportRDF/Karlsruhe,
     which is a much cooler URI as it allows ...
   While it might be unfair to keep mentioning Semantic MediaWiki's
   older, crufty URI scheme, it serves an important point here in
   educating the reader about URI design.



Editorial
---------

* Section 1 says "frontpage."  This should be "homepage."

* Section 2 says:
     ... each of the pages ... are Web documents
   but should say:
     ... each of the pages ... is a Web document

* Section 2.1 says:
     Note that the URI of this representation is passed back in the
     Content-Location header, this is not required but a recommended
     good practice (see [CHIPS], 7.2).
   The comma should be a sentence break.

* Section 2.1 says:
     Instead of a direct answer, the server /redirects/ to another  
URL ...
   but should say:
     Instead of returning a direct answer, the server /redirects/ to
     another URL ...

* Section 3 says "home-page." This should be "homepage."

* Section 3.1 says:
     In HTTP, because a 200 response code should be sent when a Web
     document has been accessed, but a different setup is needed when
     publishing URIs that are meant to identify entities which are not
     Web documents.
   The "but" must be removed.

* Section 3.1 says:
     In the next section, solutions are described that allow you to
     mint URIs ...
   That would be much clearer as:
     The next section describes solutions that allow you to mint
     URIs ...

* Section 4.1 says:
     The decision which to return ...
   That would be clearer as:
     The decision of which to return ...

* Section 4.2 says:
     By doing this we avoid ambiguity between the original, real-world
     object and the resource that represents it.
   This should say "the resource that describes it".

* Section 4.2 says:
     For example, to redirect from http://www.example.com/id/alice to
     http://www.example.com/doc/alice.
   That's not a complete sentence. It should say:
     For example, http://www.example.com/id/alice would 303-redirect
     to http://www.example.com/doc/alice.

* Section 4.4 says:
     Any fragment identifier is valid, this in the above URI is a
     suggestion you may want to copy for your implementations.
   The comma should be a semicolon.

* Section 4.5 says:
     Keep implementation-specific bits and pieces such as .php and
     .asp out of your URIs, you may want to change technologies later.
   The comma should be a semicolon.

* Section 4.7 says:
     A qs value of 1.0 for application/rdf+xml and 0.5 for text/html,
     would mean ...
   The comma should be elided.

* Section 6 says:
     ... the criteria from Section 3, which are to be on the Web and
     don't be ambiguous.
   That should say:
     ... the criteria from Section 3, which are: "Be on the Web" and
     "Be unambiguous".

* Section 8 says:
      ... Tim Berners-Lee who ... helped us understanding the TAG
      solution ...
    The "understanding" should be "understand."

* Section 8 says "detailled"; this should be "detailed".

-------------------------------------------------------------------


> -------- Original Message --------
> Subject:     Cool URIs for the Semantic Web comments: some errors
> Resent-Date:     Fri, 12 Jun 2009 18:27:11 +0000
> Resent-From:     public-sweo-ig@w3.org
> Date:     Fri, 12 Jun 2009 14:26:48 -0400
> From:     Barclay, Daniel <daniel@fgm.com>
> To:     <public-sweo-ig@w3.org>
>
>
>
> For any future editions of the Cool URIs for the Semantic Web document
> currently at http://www.w3.org/TR/cooluris/ : There are a few errors,
> mostly editorial:
>
>
> * Section 2 says:
>    ... each of the pages ... are Web documents
>  but should say:
>    ... each of the pages ... is a Web document
>  or:
>    ... the pages ... are Web documents
>
> ** Section 2.1, in the example request and 202 response, says:
>    GET /people/alice HTTP/1.1
>  and then:
>    Content-Location: http://www.example.com/people.en.html
>  Was that URI supposed to be the following:
>    Content-Location: http://www.example.com/people/alice.en.html
>  (as it is in the 303 response)?
>
>
> * Section 2.1 says:
>    Note that the URI of this representation is passed back in the
>    Content-Location header, this is not required but a recommended
>    good practice (see [CHIPS], 7.2).
>  That comma should be a semicolon (or a sentence break).
>
> * Section 2.1 says:
>    Instead of a direct answer, the server redirects to another URL ...
>  That's not quite parallel.  It probably should say:
>    Instead of returning a direct answer, the server redirects to
>    another URL ...
>
> * Section 3.1 says:
>    Bob may not like the look of the homepage, but fancy the person
>    Alice.  So two URIs are needed, one for Alice, one for the homepage
>    or a RDF document describing Alice.
>  Why two URIs are needed isn't clear.  There should probably be an
>  intervening sentence that mentions something about representing
>  the objects of both of those statements about Bob's likes.
>
> * Section 3.1 says:
>    In HTTP, because a 200 response code should be sent when a Web
>    document has been accessed, but a different setup is needed when
>    publishing URIs that are meant to identify entities which are not
>    Web documents.
>  Either the "but" must be removed, or something needs to be added at
>  the end.
>
> * Section 3.1 says:
>    In the next section, solutions are described that allow you to
>    mint URIs ...
>  That would be much clearer as:
>    The next section describes solutions that allow you to mint
>    URIs ...
>
> * Section 4.1 says:
>    When a client wants to retrieve a hash URI, then the HTTP protocol
>    requires ...
>  and
>    ... a URI that includes a hash cannot be retrieved directly ...
>  The document probably should not approximate there (saying that the
>  client "retrieves ... the URI," even though it actually does _not_
>  retrieve the URI--clearly, it already has the URI), especially since
>  the document is discussing the details of when things are
>  retrieved vs. just identified.
>
> * Section 4.1 says:
>    The decision which to return ...
>  That would be clearer as:
>    The decision of which to return ...
>
> * Section 4.2 says:
>    By doing this we avoid ambiguity between the original, real-world
>    object and the resource that represents it.
>  Was that meant to say "the resource that describes it"?
>
> * Section 4.3 says:
>    For example, to redirect from http://www.example.com/id/alice to
>    http://www.example.com/doc/alice.
>  That's not a complete sentence.  (It probably should be part of
>  the previous sentence.
>
> * Section 4.4 says:
>    Any fragment identifier is valid, this in the above URI is a
>    suggestion you may want to copy for your implementations.
> That comma should be a semicolon (or a sentence break).
>
> * Section 4.5 says:
>    Keep implementation-specific bits and pieces such as .php and
>    .asp out of your URIs, you may want to change technologies later.
> That comma should be a semicolon (or a sentence break).
>
> * Section 4.7 says:
>    A qs value of 1.0 for application/rdf+xml and 0.5 for text/html,
>    would mean ...
>  The comma should be elided.
>
> ** Section 5 says:
>    http://ontoworld.org/wiki/Special:ExportRDF/Karlsruhe
>      RDF description of Karlsruhe
>    The URI of the RDF description is less than ideal, because it
>    exposes the implementation (php) ...
>  Is that last statement correct?  There is no ".php" suffix anywhere.
>
> * Section 6 says:
>    ... the criteria from Section 3, which are to be on the Web and
>    don't be ambiguous.
>  That should either say:
>    ... the criteria from Section 3, which are to be on the Web and
>    not be ambiguous.
>  or quote the two phrases italicized in the original.
>
> * Many occurrences of "e.g." (and maybe "i.e.") aren't followed
>  by a comma.
>
> * Section 8 says:
>     ... Tim Berners-Lee who ... helped us understanding the TAG
>     solution ...
>   The "understanding" should be "understand."
>
> * Section 8 says "detailled."
>
>
> * Section 1 says "frontpage."  Shouldn't that be "front page"?
>
> * Section 2 says "homepage" and section 3 says "home-page."  Shouldn't
>  those references say simply "home page"?
>
>
> Daniel
> -- 
> (Plain text sometimes corrupted to HTML "courtesy" of Microsoft
> Exchange.) [F]

Received on Monday, 17 August 2009 11:20:46 UTC