Skip to content

Commit

Permalink
editorial: Reorganize internal slots into different sections
Browse files Browse the repository at this point in the history
In #152, it was reported that the `[[PostureOverride]]` slot was confusing,
and readers could end up thinking that its `null` value could be exposed to
script, which is not the case (this internal slot is only used internally in
calculations that result in a DevicePostureType).

To avoid confusion:
- Rename the "Internal slots" section to "Extensions to the Document
  interface", which is similar to what we already have for the Navigator
  interface.
- Move the `[[PostureOverride]]` slot's definition and the addition of
  internal slots to top-level traversables to the Automation section, and
  add a sentence explaining the values are not exposed to script directly.

While here, do some proof-reading in the "Extensions to the Document
interface" section.

Fixes #152
  • Loading branch information
Raphael Kubo da Costa committed Jul 22, 2024
1 parent 358ee8f commit c85b998
Showing 1 changed file with 42 additions and 40 deletions.
82 changes: 42 additions & 40 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -156,12 +156,10 @@ <h2>
</section>
<section>
<h3>
Internal slots
Extensions to the `Document` interface
</h3>
<p>
The following internal slots are added to the {{Document}} interface.
As it name implies, it will house the value of the current posture the
device is
</p>
<table class="simple">
<thead>
Expand All @@ -180,43 +178,7 @@ <h3>
<dfn data-dfn-for="Document">[[\CurrentPosture]]</dfn>
</td>
<td>
The <dfn>current posture</dfn>.
</td>
</tr>
</tbody>
</table>
<p>
[=Top-level traversables=] must have the following internal slots:
</p>
<table class="simple">
<thead>
<tr>
<th>
Internal slot
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<dfn data-dfn-for=
"top-level traversable">[[\PostureOverride]]</dfn>
</td>
<td>
Posture to override posture defined by hardware. Used in
automation. Possible values:
<ul>
<li>"{{DevicePostureType/continuous}}"
</li>
<li>"{{DevicePostureType/folded}}"
</li>
<li>
<code>null</code>: Used when posture is defined by hardware.
</li>
</ul>
The device's <dfn>current posture</dfn>.
</td>
</tr>
</tbody>
Expand Down Expand Up @@ -793,6 +755,46 @@ <h2>
commands=] that allows users to control the reported device posture and
simulate a real device.
</p>
<p>
To support the [=extension commands=] below and their integration with
[[[#algorithms]]], [=top-level traversables=] must have the following
internal slots:
</p>
<table class="simple">
<thead>
<tr>
<th>
Internal slot
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<dfn data-dfn-for=
"top-level traversable">[[\PostureOverride]]</dfn>
</td>
<td>
Overrides the [=current posture=] provided by the hardware.
Possible values:
<ul>
<li>"{{DevicePostureType/continuous}}"
</li>
<li>"{{DevicePostureType/folded}}"
</li>
<li>
<code>null</code>: Not overriding. The hardware-provided
value will be used instead.
</li>
</ul>
These values are not exposed directly to script.
</td>
</tr>
</tbody>
</table>
<h3>
Extension Commands
</h3>
Expand Down

0 comments on commit c85b998

Please sign in to comment.