From 1c1a2bd9be0b065f1ee3965d491e992e103fe090 Mon Sep 17 00:00:00 2001
From: Raphael Kubo da Costa <raphael.kubo.da.costa@intel.com>
Date: Mon, 22 Jul 2024 15:52:43 +0200
Subject: [PATCH] editorial: Reorganize internal slots into different sections
 (#156)

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
---
 index.html | 82 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 42 insertions(+), 40 deletions(-)

diff --git a/index.html b/index.html
index 24dd034..3532bc0 100644
--- a/index.html
+++ b/index.html
@@ -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>
@@ -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>
@@ -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>