W3C home > Mailing lists > Public > public-secondscreen@w3.org > July 2015

[presentation-api] new commits pushed by tidoust

From: François Daoust via GitHub <sysbot+gh@w3.org>
Date: Mon, 20 Jul 2015 07:42:50 +0000
To: public-secondscreen@w3.org
Message-ID: <push-272717687d0694cc648c28d2fd0ceb0a09496ee8-1437378169-sysbot+gh@w3.org>

The following commits were just pushed by tidoust to 
https://github.com/w3c/presentation-api:

* Spec source converted to ReSpec editing tool

On top of the JSON header needed to tell ReSpec how to generate the 
right
boilerplates, main changes that I introduced are:

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. 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 for 
the time
being:
 https://github.com/w3c/respec/issues/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.
  by Francois Daoust
https://github.com/w3c/presentation-api/commit/61b43effab4fc05e3ab83c4ef9762cc6b6faa46e

* Dropped distinction between source and generated file.

ReSpec runs client-side, so there is no need to keep the source in a 
separate
"Overview.src.html" file anymore. I overwrote the former "index.html" 
file
with the updated source file.
  by Francois Daoust
https://github.com/w3c/presentation-api/commit/83dea834020a697f40d83bc9e7997f6f17464e45

* Adapted Makefile, Travis CI and Echidna configurations for ReSpec 
version

The Makefile is now only useful to tidy the document. Note that tidy 
reports
warnings due to the use of proprietary attributes such as "for" in 
ReSpec. That
is normal. Problem is tidy also seems to exit with code 1 whenever a 
warning is
reported. I tried all tidy config options that may affect how warnings
 are
processed but did not find a way to have it exit with code 0.

The Makefile could ignore the error by prefixing the command with "-" 
but since
that's the only command run by the Makefile (and since we would not 
want to
ignore real errors), I left things as is for the time being.

Publication to Echidna will only happen on the TR branch as before, 
but note it
will directly use the "index.html" file. Generating a separate Working
 Draft is
no longer needed. We can revisit that in the future if we feel that 
generating
a separate Working Draft different from the Editor's Draft would 
actually be
useful.
  by Francois Daoust
https://github.com/w3c/presentation-api/commit/1796181e96c2f9ac8b0d50c9597e071c31b16148

* Recovered TIDY-HTML5 alias in Makefile, set only if not defined 
already
  by Francois Daoust
https://github.com/w3c/presentation-api/commit/1a58ede919546045e0eb1456c4ff17bf4568425d

* Merge pull request #145 from tidoust/respec

Switched to ReSpec editing tool
  by François Daoust
https://github.com/w3c/presentation-api/commit/272717687d0694cc648c28d2fd0ceb0a09496ee8
Received on Monday, 20 July 2015 07:42:52 UTC

This archive was generated by hypermail 2.3.1 : Monday, 20 July 2015 07:42:53 UTC