[presentation-api] Pull Request: Switched to ReSpec editing tool

tidoust has just submitted a new pull request for 
https://github.com/w3c/presentation-api:

== Switched to ReSpec editing tool ==
I converted the specification to ReSpec as suggested in #116.

The result is visible at:
http://tidoust.github.io/presentation-api/

The conversion went relatively smoothly although I may of course have 
missed a few things here and there. It makes the spec easier to 
maintain overall because most references now boil down to being simple
 `<a>` tags possibly decorated for interface members. The main updates
 that I had to make are detailed in the first commit message of this 
pull request (and copied below). I updated the Makefile and 
Echidna-related files accordingly (but did not update the work mode on
 the Wiki yet). See relevant commit message as well for details.

Main updates to the spec:

1. Anolis uses `<span>` and `<code>` for cross-references whereas 
ReSpec only
understands `<a>`.
2. All terms used in the specification are now defined in the 
Terminology
section. Other sections link back to that section. No need to specify 
the
spec anymore each time one wants to cross-reference a specific term.
3. WebIDL definitions are no longer decorated with `<dfn>` and `<a>` 
since ReSpec
takes care of everything.
4. However, cross-references to interface attributes now need to 
specify the
interface name in a `for` attribute. For sections that reference or 
define
more than one attribute of the same interface, I used `dfn-for` or 
`link-for`
on the common ancestor to be able to stick to simple `<a>` within the 
prose.
5. Note wrapping `<code>` is no longer needed for cross-references to 
interface
definitions as ReSpec automatically adds `<code>` in the generated 
prose.
However, note that there is a known bug in ReSpec that makes some of 
the
references to "startSession" look like code when they should not:
 w3c/respec#441
6. Switched to using uppercase MUST, SHOULD, MAY, because ReSpec does 
not like
it when someone writes the "The key words MAY, MUST, SHOULD are to be
interpreted as described in [RFC2119]" in the Conformance section and 
creates
a duplicate.
7. I defined terms with singular and plural forms when needed to be 
able to
reference them either way.
8. To reference the term "presentation", one needs to use the longer 
form
"presentation context" or "presenting browsing context" (possibly in a
 "title"
attribute). The term collided with the "Presentation" interface that 
cannot
be easily renamed.

See https://github.com/w3c/presentation-api/pull/145

Received on Friday, 17 July 2015 15:49:33 UTC