Re: Primer

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.

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
> <http://w3.ibm.com/jct03019wt/bluepages/simpleSearch.wss?searchBy=Internet+address&location=All+locations&searchFor=johnarwe>
> Cloud and Smarter Infrastructure OSLC Lead
>
>