Re: Primer

On 2 Jun 2014, at 16:02, Nandana Mihindukulasooriya <nmihindu@fi.upm.es> wrote:

> John,
> 
> Thanks a lot for your thorough review. I already merged the changes in the zip to the main branch and commit. We will go through the other comments listed in the email one by one, and fix them in the primer.  As soon as Henry is done, we will see how to merge the changes from the bblfish to the main branch. 

I had noticed a lot of those mistakes in the bblfish branch.
The latest version is online here:
  https://dvcs.w3.org/hg/ldpwg/raw-file/bblfish/ldp-primer/ldp-primer.html

I have gone through most of the file. I'll spend some more time tomorrow to finish it, but you can allready start merging some of those
elements.


> 
> Best Regards,
> Nandana
> 
> 
> On Mon, Jun 2, 2014 at 2:53 PM, John Arwe <johnarwe@us.ibm.com> wrote:
> Nandana/Roger, attached is a zip with a pile of small and probably non-controversial changes.  It had been my intent that doing them as a unit would make them painless to integrate, but since Tortoise decided to use the bblfish branch and over the weekend that branch has the massively compare-breaking change of inserting line breaks into all the long lines, I give up on trying to merge it.  It should be a pretty simple diff/merge against the default branch on its own.   
> 
> The added line breaks *are* a good idea long term, especially from the standpoint of merging cleanly (more+shorter source lines = reduced probability of conflicts), but doing that in the middle of a heavy review period w/o coordination is not something I'd recommend so when you do that in the default branch, please give warning enough to allow anyone with review in progress to choose to get in either before or after The Earthquake. 
> 
> In addition, there are a few pervasive things that I did not go after: 
> 
> 1:  The hostname of the examples alternates between example.org and data.example.org; example = 2.1 
> 
> 2:  You've got "a lot" (not pervasive, but more than a few) places with content-length=0 and status code 200.  IIRC 200 is legal in that case, but 204 is likely more natural (and it allows you to drop the C-L as well, if you are in the "shorter is better" camp). 
> 
> 3:  You've got relative URIs in Location headers; that's not legal, they must be absolute URIs, see http://tools.ietf.org/html/rfc2616#section-14.30
> 
> 4:  In all your "create" flows, the text reads as if it assumes that *because post is allowed and the uri is of an LDPC*, that create is the only possible outcome.  This is not what the spec says.  5.2.3.13 covers this specifically.  I'm not sure myself that I'd want to smack readers in the face with that cold hard reality, but I wanted to remind you as the authors so the decision to do so or not is a conscious one.  This gap is why I was pushing on a more specific definition of what came to be the Accept-Post header.
> 
> 
> 5:  Some of the included examples get cut off on the right margin when printed on US Letter format paper (same would be true on A4).  Ex's 11 and 22 are examples ;-) of this.  It seems to be cases where the Turtle representation is using the comma notation for repeated predicates so several objects appear on the same source line.  Ala Henry's change in the source, the answer here is just inserting CRLFs.
> 
> 
> 6: Your delete responses contain etags.  4.2.1.3 does not require them (I'm not sure what the semantics would even be on this - I guess it's the value prior to the deletion, but I can't think of any client use for it).
> 
> 
> 7:  You do a conditional delete in at least one case.  That's legal, but it led me to wonder if that's "important" since it's not mentioned in the text.
> 
> 
> 8: (fun one) you could christen "the bug tracker application" one of the following
> 
> The Products That have Bugs = TPTB
> 
> Track Products Having Bugs = TPHB
> 
> The [or Track] Products that have Bugs = interpretable either way
> 
> ...such is how I spent time on planes, sadly
> 
> 
> 9:  Ex 24: text says either turtle or json-ld but Accept header only has Turtle
> 
> 
> 10: Ex 26: first use of <> but its significance not discussed until later.  
> 
> 
> 11:  The refs for json-ld and turtle are "rather dated"; both are Recs now for several months.  I didn't see a localBiblio entry for them, so you might need to submit a patch to Robin to fix spec.js; check the archives first, I know Steve S has submitted other patches, maybe these are among them; I see the json-ld one is still downlevel in the LDP editor's draft, so that's probably from spec.js, but Turtle is current so we probably have a localBiblio entry for that one.
> 
> 
> 
> 
> Best Regards, John
> 
> Voice US 845-435-9470  BluePages 
> Cloud and Smarter Infrastructure OSLC Lead 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 

Social Web Architect
http://bblfish.net/