Re: Comments on current editor's draft (Web 1.0, 3rd October 2012)

Thanks Antoine for this feedback. It'll require a few passes to fix all
this. I've made the first one (see below).

You can view the new version at
https://dvcs.w3.org/hg/WebID/raw-file/7076a5009bbb/spec/index-respec.html

On Tue, Oct 23, 2012 at 12:53 PM, Antoine Zimmermann <
antoine.zimmermann@emse.fr> wrote:

> These are small comments on the current version of the WebID spec.
>
> The document is obviously not finished yet and will certainly evolve a lot
> still until it gets to a stable state.
>
> General comments:
>  1.  all current W3C specs in the Semantic Web activity now use IRI, you
> should replace URI with IRI everywhere, I think;
>  2.  there is some freedom taken in capitalising words arbitrarily.
> Starting a word with a capital letter is not a proper way of emphasing a
> word. A noun with a capital letter has a different meaning than the same
> noun without a capital letter, e.g., web VS Web. For emphasis, use italic,
> bold face, or underline;
>  3.  masculine and feminine are both used randomly, to talk about a user,
> but even sometimes to talk about an agent in general. Either stick to a
> consistent gender, with a disclaimer that you use it for ease of reading to
> avoid "he/she" spelling, or simply use "he/she", or reformulate the
> sentences to make them gender-neutral, or stick to masculine only when you
> talk about Bob, and feminine only when you talk about Alice, being neutral
> in any other case;
>  4.  I don't see where the use of Bob and Alice actually helps. A generic
> "user" or "user agent" would be fine, as far as I can see, since we don't
> rely on the notion so heavily;
>  5.  W3C specs are normally written in American English dialect.
>
> Detailed comments:
> Intro:
> "in one click" -> this suggests a specific way of implementing which
> requires a mouse.
>
fixed

"a URI whose sense" -> "whose" is normally for people
>
no, http://www.merriam-webster.com/dictionary/whose


> "foaf" -> it's an acronym, use "FOAF"
>
fixed


> "such that the he is known" -> "such that he", I guess (modulo gender
> neutralisation)
> "his Certification" -> why not hers?
> "the the private" -> the private
> "she used" -> why not he?
>
I've fixed many he/she instances throughout the whole document, I hope I
got them all.


>
> Sec.1.1:
> "organisation" -> British English (BE)
>
fixed


> "Key Store [...] by the Subject" -> it has just been said that the subject
> will be called Bob! In fact, Alice and Bob are very little used and could
> easily be removed (except only in examples)
> "Service" -> there is a dot missing at the end of the sentence
>
fixed


> "Guard [...] authorised [...] authorisation" -> BE
>
fixed


> "WebID Claim [...] be thought of a set" -> thought of as a set
>
fixed


> "Subject Alternate Names" is sometimes written in normal font, sometimes
> in Courrier-like font
>
fixed


> "between the a Subject Alternative name" -> between the subject
> alternative name
>
fixed


> The example does not use a valid lexical part for the hexBinary value
> (separators of octets not allowed).
>
fixed


> "WebID Certificate [...] at http://bob.example/profile Such [...]" ->
> first, bob.example is not a valid domain name, second, there is a missing
> dot after the IRI.
> "WebID Profile [...] RDF-XML" -> RDF/XML
>
fixed


> "serialisations" -> BE
>
fixed


>
> Sec.2.1:
> "The WebID URL itself ..." -> isn't it the WebID IRI?
>
> Sec.2.1.1:
> "can sends a keyrequest" -> can send a key request
>
fixed


>
> Sec.2.2:
> "personalise [...] serialisation [...] serialisation [...] serialisations"
> -> BE
>
fixed


>
> Sec.2.2.1:
> "foaf" -> FOAF
>
fixed


>
> Sec.2.2.1.1:
> "his key" -> why not hers or its (we talk about the subject, not
> necessarily a person)?
>
fixed


>
> Sec.2.2.1.2:
> """foaf:name
> The name that is most commonly used to refer to the individual or agent."""
>
> why the most commonly used? foaf:name is just a name, common or not, and
> there can be several foaf:names for an entity.
>
fixed


>
> Sec.2.2.2:
> Update the reference to Turtle to W3C RDF 1.1 Turtle. Turtle will
> certainly be standardised before the WebID spec is completed.
>
ok, we will update the spec then when biblio.js includes the reference to
1.1.


>
> Sec.2.2.3:
> "The style="word-wrap" ... right of the screen." -> who cares? This
> sentence is useless.
> "he MAY publish" -> why not she?
>
fixed


>
> Sec.2.3:
> "if she is the" -> if he/it?
> "then he can" -> can she?
>
both fixed


>
> Sec.3.1:
> "summarised" -> BE
>
fixed


> "The guard requests of the TLS agent that it make [sic] a Certificate
> Request to the client." -> weird sentence...
>
fixed


> "is the transformed into an RDF graph [RDF-MT]" -> why the hell is RDF
> semantics referenced here?
>
good point, this is just AWWW. Henry, did you have anything in mind there?


> "in Processing the WebID Profile ." -> "in processing the WebID profile."
>
fixed


>
> Sec.3.2.1:
> "a few web pages without having authenticated" -> without being
> authenticated(?)
>
yes, fixed


>
> Sec.3.2.3:
> "[section 7.4.4]" -> [Section 7.4.4] (capital 'S')
>
fixed


> "on CA's signing [...] the CA's they were" -> CAs signing ... the CAs ...
>
fixed


> "As far as possible it is important ..." -> As much as possible
>
fixed


> "advertised" -> BE
>
advertise is valid in both BE and AE, and seems much more common than
advertized which some dictionaries don't seem to know. my spellchecker
complains about it too.


>
> Sec.3.2.4:
> "it's meaning can be had by" -> can be gotten / can be obtained
>
fixed


> "RDF defining URIs [RFC3986]" -> add colon after ref.
>
fixed

Sec.3.2.4.2:
> "the query engine MUST support the D-entailment regime fpr xsd:hexBinary"
> -> this implies that the query engine MUST support RDFS entailment, since
> D-entailment subsumes RDFS entailement. This is unlikely to be the case.
> "normalisation [...] normalise [...] normalised" -> BE
>
fixed


> Sec.3.2.4.3:
> "personalise [...] personlise" -> BE
>
fixed


> "those friends friends" -> those friends' friends
> "It is even be possible" -> it is even possible
>
both fixed

>
> B. Acknowledgments:
> The list of acknowledged people should be put inline, as it is the case in
> all W3C specs.
>
done.


>
> C. References:
> [RDF-SPARQL-QUERY] -> consider reference to SPARQL 1.1 (not yet
> standardised but quite stable already)
> Why is there a referencec to RDFa 1.0 and to RDFa 1.1, both for the formal
> syntaxes and the primers?
>
normalized all references to RDFA-CORE (the latest RDFa 1.1).


> [TURTLE-TR] -> should use RDF 1.1 Turtle
>

we use biblio.js/respec for managing these, I know there is a way to
override them but since we're still using respec v1, I'd rather take care
of that when moving to v3, which should make things easier.

Steph.


>
>
>
> Best,
> --
> Antoine Zimmermann
> ISCOD / LSTI - Institut Henri Fayol
> École Nationale Supérieure des Mines de Saint-Étienne
> 158 cours Fauriel
> 42023 Saint-Étienne Cedex 2
> France
> Tél:+33(0)4 77 42 66 03
> Fax:+33(0)4 77 42 66 66
> http://zimmer.**aprilfoolsreview.com/<http://zimmer.aprilfoolsreview.com/>
>
>


-- 
Steph.