[go: up one dir, main page]

Re: [Generic Resources 53] Updated Finding On Linking Alternatives And Discovery

Noah comments in-lined.

You caught a lot of the typos I usually catch with a perl linter
that I run at the very end --- I'll describe what I did for your
various comments:


noah_mendelsohn@us.ibm.com writes:
 > Raman,
 > 
 > Mostly this looks fine and ready to go.  I did notice a few more purely 
 > editorial issues, though the first two are significant and need to be 
 > fixed.  That one is that the status section has a statement "An informal 
 > guide to previous discussion of this topic is available and may be useful 
 > to reviewers of this draft."  The link is in fact to the draft itself.  I 
 > strongly suspect that this entire sentence traces to your
 > perhaps having 
Good guess, it's gone.
 > adopted the metadataInUri draft finding as a starting point.  It had such 
 > a link to informal discussion, so my guess is that this entire sentence is 
 > to be deleted.  Anyway, the link is bogus. 
 > 
 > The other significant comment is that you also have carried over the usual 
 > reference to RFC 2119, but in fact the formal uppercase SHOULD, MUST, MUST 
 > NOT, etc. are not used in the finding.  I suggest that the
 > sentence in the 
Nuked that reference, and turned the "Should Not" at the end to
 > lower case by rewriting that sentence.

 > status, and the corresponding bibliography entry be dropped.  (Warning: I 
 > do comment later on one place in which the finding uses the odd 
 > capitalization Should Not;  my recommendation is to lowercase that one, 
 > but if you uppercase it, then obviously you should keep the RFC 2119 
 > reference after all.)
 > 
 > Other less significant comments follow.  I think most of these are worth 
 > fixing, but I leave that entirely to you.  There are a fair number of 
 > them.  If you want to fix only the two above and ship, I'm fine with that. 
 >  I don't think the suggestions below are the sort of thing that would 
 > trigger another round of formal reviews.  Most are typos or barely above 
 > that in significance.  I'm afraid these are in the order I discovered 
 > them, which is not necessarily document order.
 > 
 > If you find that you do want to fix these but that the editing is 
 > burdensome, I'll be glad to share the load.  We can pick a time when the 
 > CVS copy is clean and I'll be glad to help patch up some of these, 
 > particularly where the issues are just punctuation and spacing.
 > 
 > ---
 > From 2.1.1 list item 5:
 > 
 > "In contrast, links meant for machine consumption, e.g., Atom/RSS feeds 
 > might use the HTML link element."
 > 
 > I think that this is hard to parse, partly due to the position
 > of the 

this wasn't quite saying what I watned it to, rewrote it --
  please look it over.

 > commas and partly due to the wording.  I think what you meant was that 
 > Atom/RSS feeds are examples of resources to which an HTML document might 
 > link for purposes of machine consumption.  My eye tends to hang up on the 
 > comma after the e.g., and tries to parse as "Atom/RSS feeds might use the 
 > HTML link element", before backtracking and realizing that's not intended. 
 >  Proposed rewording:
 > 
 > "In contrast, links meant for machine consumption, e.g. links to Atom/RSS 
 > feeds, might use the HTML link element."
 > 
 > ---
 > From 2.1.1:
 > 
 > 
 > "If no content negotiation is in place, Serve a canonical representation 
 > of the content at http://example.com/ubiquity/resource"
 > 
Fixed
 > The word "Serve" should be lowercase.
 > 
 > ---
 > The punctuation that terminates list items is inconsistent throughout the 
 > finding.
 > 
 > For example in the abstract, there's a list of:

This was a consequence of specxml structuring, I used a slist
there, and ended u using "," at each bullet; now nuked.

 > 
 >         Representations appropriate for different delivery contexts,
 >         Representations in different languages,
 > 
 > I'm not sure why these end with commas.  The style guides I've seen mainly 
 > say to use periods for list items if and only if they are each complete 
 > sentences, and otherwise to use no punctuation at all.  In any case, the 
 > commas look suspect. 
 > ---
 > In chapter 3:
 > 
 > "As can be seen from the use-cases and suggested solutions enumerated in 
 > the previous section, pointers to Web Resources (URIs) can either:
 > 
Fixed. nuked Can
 >     * Be canonical URIs, i.e., have no context hard-wired.
 >     * Can encapsulate partial context, e.g., encapsulate language,
 >     * Encapsulate multiple context bits, e.g., language and device 
 > profile,
 >     * Capture all context, i.e., the creator of the URI guarantees that 
 > all state is completely captured by the URI."
 > 
 > I think the word "Can" should be deleted from the second item in the list.
 > ---
 > 
 > In the abstract:
 > 
Fixed.

 > "This document explores the issues that arise in this context, and 
 > attempts to define best practices that help toward:
 > 
 >     *  Preserve the One Web while enabling content publishing to a 
 > multiplicity of delivery contexts.
 >     *  Enable automatic discovery of the available representations.
 >     *  Enable the creation of RESTful URIs that remain representation 
 > agnostic while delivering the correct end-user experience."
 > 
 > I think it would be better grammar to delete the word "toward", so the 
 > list can be interpreted as "practices that help Preserve the One Web", 
 > "practices that Enable automatic discovery", etc.
 > 
Remaining typos fixed as you suggested.
 > ---
 > 
 > In the very first sentence of the introduction:
 > 
 > "There has always been a need to serve user-agent specific contents for a 
 > given URI --- thus highlighting the distinction..."
 > 
 > you have approximated an emdash with three hyphens, which looks sort of 
 > bad.  For your convenience, this is a real emdash ô you can copy it if you 
 > like, or else use the entity —.  A useful guide to dashes and their 
 > use in HTML is at [1].
 > 
 > --
 > 
 > I hesitate to raise this, because it's more a question of patching around 
 > bugs than doing things right, but both Firefox and IE tend to render the 
 > text in <code> elements too small relative to the text around them.  I've 
 > seen this discussed on the Web, but I'm not sure why the problem occurs. 
 > Anyway, to get around this, I reluctantly made the drafts of metadata in 
 > URI point to a stylesheet (which happens to be metadataInURI.xsl in the 
 > same doc directory as your finding) which has in it:
 > 
 >         code        {font-family: monospace;
 >                      font-size: 130%;}
 >         pre         {font-family: monospace;
 >                      font-size: 120%;}
 > 
 > in the generated HTML <style>.  I find this makes the text sizes line up 
 > better.  Others may disagree.
 > 
 > ---
 > 
 > Chapter 3:
 > 
 > "URIs are cheap, we suggest creating as many distinctive URIs as is 
 > meaningful."
 > 
 > I believe that the correct punctuation to join the independent clauses is 
 > a semicolon:
 > 
 > "URIs are cheap; we suggest creating as many distinctive URIs as is 
 > meaningful."
 > 
 > ---
 > 
 > Similar issue also in chapter 3:
 > 
 > "The hyperlink structure of the Web is crucial for content discovery; When 
 > creating..."
 > 
 > One option is to leave the semicolon, I think, but then the word "When" 
 > following the semicolon should be lowercase.  Otherwise, I think you could 
 > make the semicolon a period, and leave the "When" in caps.
 > 
 > ---
 > 
 > Also in that same list, the 3rd item has:
 > 
 > "in the absence of user context; Or equivalently"
 > 
 > There too, I think the "Or" should be lowercase.
 > 
 > ---
 > Chapter 3, same list:
 > 
 > "Contrast these findings with the metadata in URIs and state finding which 
 > each enumerate use cases where user context Should Not be encapsulated by 
 > URIs"
 > 
 > That "Should Not" has only initial caps.  I think it should either be all 
 > caps or no caps.  My vote, as signaled above, would be to make them 
 > lowercase, as nowhere else in the finding do we use RFC 2119 directives. 
 > If you want to make them uppercase, then obviously you should not follow 
 > my advice above on getting rid of the RFC 2119 reference in the status and 
 > biblio.
 > 
 > ---
 > Chapter 4:
 > 
 > "URIs are cheap, create them as needed, publish them to the Web, and 
 > ensure that they are appropriately linked in to the rest of the Web. Thus, 
 > each representation of interest should get it's own URI and there should 
 > be one additional URI representing the generic resource."
 > 
 > More independent clause punctuation.  I think that should either be "URIs 
 > are cheap. Create..." with a period, or else "URIs are cheap; create..." 
 > with a semicolon.  The comma seems incorrect to me.
 > ---
 > Chapter 4:
 > 
 > "Thus, given one of the alternatives for a resource,ensure "
 > 
 > Missing space before the word ensure.
 > ---
 > 
 > That's it.  Sorry I didn't catch more of these before.  Again, I'm very 
 > happy with the substance of the finding.  Thanks for the hard work on 
 > this.
 > 
 > Noah
 > 
 > [1] http://alistapart.com/stories/emen/
 > 
 > --------------------------------------
 > Noah Mendelsohn 
 > IBM Corporation
 > One Rogers Street
 > Cambridge, MA 02142
 > 1-617-693-4036
 > --------------------------------------
 > 
 > 
 > 
 > 

-- 
Best Regards,
--raman

Title:  Research Scientist      
Email:  raman@google.com
WWW:    http://emacspeak.sf.net/raman/
Google: tv+raman 
GTalk:  raman@google.com, tv.raman.tv@gmail.com
PGP:    http://emacspeak.sf.net/raman/raman-almaden.asc

Received on Wednesday, 13 September 2006 23:44:06 UTC