Skip to content

Copy editing of non-normative text #429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 5, 2017
Merged

Copy editing of non-normative text #429

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
471724e
First round of edits
markafoltz May 4, 2017
4d28bcd
Finish edits
markafoltz May 4, 2017
afbe049
Tidy
markafoltz May 4, 2017
9a5440a
Address @anssiko comment
markafoltz May 4, 2017
7d5c676
Further editing
markafoltz May 4, 2017
fe784b4
Clarify use of trademarks in spec.
markafoltz May 5, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 113 additions & 99 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,9 +138,8 @@
<body>
<section id="abstract">
<p>
This specification defines an API to enable web content to access
external presentation-type displays and use them for presenting web
content.
This specification defines an API to enable Web content to access
presentation displays and use them for presenting Web content.
</p>
</section>
<section id="sotd">
Expand Down Expand Up @@ -176,58 +175,61 @@ <h2>
Introduction
</h2>
<p>
This specification aims to make <a>presentation displays</a> such as
projectors or connected TVs, available to the Web and takes into
account displays that are attached using wired (HDMI, DVI, or similar)
and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, or
similar).
The Presentation API aims to make <a>presentation displays</a> such as
projectors, attached monitors, and network-connected TVs available to
the Web. It takes into account displays that are attached using wired
(HDMI, DVI, or similar) and wireless technologies (Miracast,
Chromecast, DLNA, AirPlay, or similar).
</p>
<p>
Devices with limited screen size lack the ability to show content to a
larger audience, for example, a group of colleagues in a conference
room, or friends and family at home. Showing content on an external
large <a>presentation display</a> helps to improve the perceived
quality and impact of the presented content.
Devices with limited screen size lack the ability to show Web content
to a larger audience: a group of colleagues in a conference room, or
friends and family at home. Web content shown on a larger
<a>presentation display</a> has greater perceived quality, legibility,
and impact.
</p>
<p>
At its core, this specification enables an exchange of messages between
a page that acts as the <a>controller</a> and another page that
represents the <a href=
"#dfn-receiving-browsing-context">presentation</a> shown in the
<a>presentation display</a>. How the messages are transmitted is left
to the UA in order to allow the use of <a>presentation display</a>
devices that can be attached in a wide variety of ways. For example,
when a <a>presentation display</a> device is attached using HDMI or
Miracast, the same UA that acts as the <a>controller</a> renders the
<a href="#dfn-receiving-browsing-context">presentation</a>. Instead of
displaying the <a href=
"#dfn-receiving-browsing-context">presentation</a> in another window on
the same device, however, it can use whatever means the operating
system provides for using the external <a>presentation displays</a>. In
such a case, both the <a>controller</a> and <a href=
"#dfn-receiving-browsing-context">presentation</a> run on the same UA
and the operating system is used to route the <a>presentation
display</a> output to the <a>presentation display</a>. This is commonly
referred to as the <dfn><b id="1-ua">1-UA</b></dfn> case. This
specification imposes no requirements on the <a>presentation
display</a> devices connected in such a manner.
At its core, the Presentation API enables a <a>controller</a> page to
show a <a href="#dfn-receiving-browsing-context">presentation</a> page
on a <a>presentation display</a> and exchange messages with it. How the
presentation page is transmitted to the display and how messages are
exchanged between it and the controller page are left to the
implementation; this allows the use of a wide variety of display
technologies.
</p>
<p>
If the <a>presentation display</a> is able to render HTML documents and
communicate with the <a>controller</a>, the <a>controller</a> does not
need to render the <a href=
"#dfn-receiving-browsing-context">presentation</a>. In this case, the
UA acts as a proxy that requests the <a>presentation display</a> to
show and render the <a href=
"#dfn-receiving-browsing-context">presentation</a> itself. This is
commonly referred to as the <b id="2-ua">2-UA</b> case. This way of
attaching to displays could be enhanced in the future by defining a
standard protocol for delivering these types of messages that display
devices could choose to implement.
For example, if the <a>presentation display</a> is connected by HDMI
or Miracast, which only allow audio and video to be transmitted, the
user agent (UA) hosting the <a>controller</a> will also render the
<a href="#dfn-receiving-browsing-context">presentation</a>. It then
uses the operating system to send the resulting graphical and audio
output to the presentation display. We refer to this situation as the
<dfn data-lt="1-UA">1-UA mode</dfn> implementation of the Presentation
API. The only requirements are that the user agent is able to send
graphics and audio from rendering the presentation to the
presentation display, and exchange messages internally between
the controller and presentation pages.
</p>
<p>
The API defined here is intended to be used with UAs that attach to
<a>presentation display</a> devices through any of the above means.
If the <a>presentation display</a> is able to render HTML natively and
communicate with the <a>controller</a> via a network, the user agent
hosting the controller does not need to render the <a href=
"#dfn-receiving-browsing-context">presentation</a>. Instead, the user
agent acts as a proxy that requests the presentation display to load and
render the presentation page itself. Message exchange is done over a
network connection between the user agent and the presentation display.
We refer to this situation as the <dfn data-lt="2-UA">2-UA mode</dfn>
implementation of the Presentation API.
</p>
<p>
The Presentation API defined is intended to be used with user agents
that attach to <a>presentation displays</a> in <a>1-UA mode</a>,
<a>2-UA mode</a>, and possibly other means not listed above. To improve
interoperability between user agents and presentation displays,
standardization of network communication between browsers and displays
is being considered in the <a href=
"https://www.w3.org/community/webscreens/">Second Screen Community
Group</a>.
</p>
</section>
<section id="use-cases-and-requirements" class="informative">
Expand Down Expand Up @@ -255,7 +257,7 @@ <h2>
</p>
<section>
<h3>
Conformance Classes
Conformance classes
</h3>
<p>
This specification describes the conformance criteria for two classes
Expand Down Expand Up @@ -303,7 +305,7 @@ <h3>
and implements all of their required interfaces. This can happen when
the same user agent is able to host the <a>controlling browsing
context</a> and the <a>receiving browsing context</a> for a
presentation, as in the <a>1-UA</a> implementation of the API.
presentation, as in the <a>1-UA mode</a> implementation of the API.
</p>
<p>
Conformance requirements phrased against a <a>user agent</a> apply
Expand Down Expand Up @@ -670,7 +672,7 @@ <h3>
var request = new PresentationRequest(presUrls);
request.getAvailability().then(function(availability) {
// availability.value may be kept up-to-date by the controlling UA as long
// as the availability object is alive. It is advised for the web developers
// as the availability object is alive. It is advised for the Web developers
// to discard the object as soon as it's not needed.
handleAvailabilityChange(availability.value);
availability.onchange = function() { handleAvailabilityChange(this.value); };
Expand Down Expand Up @@ -885,8 +887,9 @@ <h3>
</h3>
<p>
A <dfn lt="presentation display|presentation displays">presentation
display</dfn> refers to an external screen available to the user
agent via an implementation specific connection technology.
display</dfn> refers to a graphical and/or audio output device
available to the user agent via an implementation specific connection
technology.
</p>
<p>
A <dfn lt=
Expand All @@ -906,13 +909,13 @@ <h3>
<p>
Some <a>presentation displays</a> may only be able to display a
subset of Web content because of functional, security or hardware
limitations. Examples are set-top boxes, smart TVs or networked
limitations. Examples are set-top boxes, smart TVs, or networked
speakers capable of rendering only audio. We say that such a display
is an <dfn lt=
"available presentation display|available presentation displays">available
presentation display</dfn> for a URL if the <a>controlling user
agent</a> can reasonably guarantee that the presentation of the URL
on that display will succeed.
presentation display</dfn> for a <a>presentation URL</a> if the
<a>controlling user agent</a> can reasonably guarantee that
presentation of the URL on that display will succeed.
</p>
<p>
A <dfn lt=
Expand Down Expand Up @@ -2208,9 +2211,9 @@ <h4>
connect the <a>controlling browsing context</a> with the presented
document is an implementation choice of the user agent. The
connection must provide a two-way messaging abstraction capable of
carrying <code>DOMString</code> payloads in a reliable and in-order
fashion as described in the <a>Send a Message</a> and <a>Receive a
Message</a> steps below.
carrying <code>DOMString</code> and binary payloads in a reliable
and in-order fashion as described in the <a>Send a Message</a> and
<a>Receive a Message</a> steps below.
</div>
</section>
<section>
Expand Down Expand Up @@ -2646,10 +2649,8 @@ <h4>
<p class="note">
This could happen by an explicit user action, or as a policy of
the user agent. For example, the <a>receiving user agent</a>
could be configured to terminate presentations that have no
<a>PresentationConnection</a> objects whose <a>presentation
connection state</a> is in the <a link-for=
"PresentationConnectionState">connected</a> state after 30
could be configured to terminate presentations whose
<a>PresentationConnection</a> objects are all closed for 30
minutes.
</p>
</li>
Expand Down Expand Up @@ -2935,7 +2936,9 @@ <h4>
</p>
<p class="note">
This algorithm is intended to create a well defined environment to
allow interoperable behavior for 1-UA and 2-UA presentations.
allow interoperable behavior for <a>1-UA</a> and <a>2-UA</a>
presentations, and to minimize the amount of state remaining on a
<a>presentation display</a> used for a <a>2-UA</a> presentation.
</p>
<p>
The <a>receiving user agent</a> SHOULD fetch resources in a
Expand All @@ -2949,8 +2952,8 @@ <h4>
</p>
<p class="note">
Given the operating context of the <a>presentation display</a>,
some APIs will not work by design (for example, by requiring user
input) or will be obsolete (for example, by attempting window
some Web APIs will not work by design (for example, by requiring
user input) or will be obsolete (for example, by attempting window
management); the <a>receiving user agent</a> should be aware of
this. Furthermore, any modal user interface will need to be handled
carefully. The <a>sandboxed modals flag</a> is set on the
Expand Down Expand Up @@ -3121,10 +3124,10 @@ <h3>
</h3>
<p>
The <a>change</a> event fired on the <a>PresentationAvailability</a>
object reveals one bit of information about the presence (or
non-presence) of a <a>presentation display</a> typically discovered
through the local area network. This could be used in conjunction
with other information for fingerprinting the user. However, this
object reveals one bit of information about the presence or absence
of a <a>presentation display</a>, often discovered through the
browser's local area network. This could be used in conjunction with
other information for fingerprinting the user. However, this
information is also dependent on the user's local network context, so
the risk is minimized.
</p>
Expand All @@ -3147,35 +3150,36 @@ <h3>
</h3>
<p>
A <a href="#dfn-receiving-browsing-context">presentation</a> is
allowed to be accessed across origins; the presentation URL and
presentation ID used to create the presentation are the only
information needed to reconnect to a connection from any origin in
that user agent. In other words, a presentation is not tied to a
particular opening origin.
allowed to be accessed across origins; the <a>presentation URL</a>
and <a>presentation identifier</a> used to create the presentation are
the only information needed to reconnect to a presentation from any
origin in the controlling user agent. In other words, a presentation
is not tied to a particular opening origin.
</p>
<p>
This design allows controlling contexts from different domains to
This design allows controlling contexts from different origins to
connect to a shared presentation resource. The security of the
presentation ID prevents arbitrary pages from connecting to an
existing presentation.
presentation identifier prevents arbitrary origins from connecting to
an existing presentation.
</p>
<p>
This specification allows a user agent to publish information about
its <a>set of controlled presentations</a>, and allows a browsing
context on another user agent to connect to a running presentation
via <a for="PresentationRequest">reconnect</a>. To connect, the
additional browsing context must discover the presentation URL and
presentation ID of the presentation, either provided by the user, or
via a shared service.
This specification also allows a <a>receiving user agent</a> to
publish information about its <a>set of controlled presentations</a>,
and a <a>controlling user agent</a> to reconnect to presentations
started from other devices. This is possible when the <a>controlling
browsing context</a> obtains the <a>presentation URL</a>
and <a>presentation identifier</a> of a running presentation from the
user, local storage, or a server, and then connects to the
presentation via <a for="PresentationRequest">reconnect</a>.
</p>
<p>
However, this specification makes no guarantee as to the identity of
the connecting party. Once connected, the receiving application may
This specification makes no guarantee as to the identity of any party
connecting to a presentation. Once connected, the presentation may
wish to further verify the identity of the connecting party through
application-specific means. For example, the connecting application
could provide a token via <a for="PresentationConnection">send</a>
that the receiving application could verify corresponds an authorized
entity.
application-specific means. For example, the presentation could
challenge the controller to provide a token
via <a for="PresentationConnection">send</a> that the presentation
uses to verify identity and authorization.
</p>
</section>
<section>
Expand Down Expand Up @@ -3242,24 +3246,26 @@ <h3>
<p>
The presentation API abstracts away what "local" means for displays,
meaning that it exposes network-accessible displays as though they
were local displays. The Presentation API requires user permission
for a page to access any display to mitigate issues that could arise,
such as showing unwanted content on a display viewable by others.
were directly attached to the user's device. The Presentation API
requires user permission for a page to access any display to mitigate
issues that could arise, such as showing unwanted content on a
display viewable by others.
</p>
</section>
<section>
<h3>
Temporary identifiers and browser state
</h3>
<p>
The presentation URL and presentation ID can be used to connect to a
presentation from another browsing context. They can be intercepted
if an attacker can inject content into the controlling page.
The <a>presentation URL</a> and <a>presentation identifier</a> can be
used to connect to a presentation from another browsing context. They
can be intercepted if an attacker can inject content into the
controlling page.
</p>
</section>
<section>
<h3>
Incognito mode and clearing of browsing data
Private browsing mode and clearing of browsing data
</h3>
<p>
The content displayed on the presentation is different from the
Expand Down Expand Up @@ -3308,10 +3314,18 @@ <h2>
Kanai, Tobie Langel, Tomoyuki Shimizu, Travis Leithead, and Wayne Carr
for help with editing, reviews and feedback to this draft.
</p>
<p>
<em>AirPlay</em>, <em>HDMI</em>, <em>Chromecast</em>, <em>DLNA</em> and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tidoust, is the recommendation to explicitly call these out in the spec, or does the "Non-W3C Trademarks; Member Trademarks" section in https://www.w3.org/Consortium/Legal/2002/trademarks-20021231 cover specs as well? I assume the term "Site" in this generic boilerplate refers to any resource hosted on the w3.org domain, including specs in the TR space.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked internally. Specs we publish usually do not contain non-W3C trademarks for various reasons. In our case, mentioning these technologies as examples in the introduction is important to clarify the context for readers, and the introduction is clear that other technologies are available.

It is a good idea to call these trademarks out explicitly in the acknowledgement section. The proposed text is fine. I recommend adding "They are only cited as background information" to the end of it to make it crystal clear that one does not need them to implement the specification.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

<em>Miracast</em> are registered trademarks of Apple Inc., HDMI
Licensing LLC., Google Inc., the Digital Living Network Alliance, and
the Wi-Fi Alliance, respectively. They are only cited as background
information and their use is not required to implement the
specification.
</p>
</section>
<section class="appendix">
<h2>
CR exit criteria
Candidate Recommendation exit criteria
</h2>
<p>
For this specification to be advanced to Proposed Recommendation, there
Expand Down