Re: [w3c/screen-orientation] Editorial: new algorithms section (#131) from Marcos Cáceres on 2019-01-10 (public-webapps-github@w3.org from January 2019)

From: Marcos Cáceres <notifications@github.com>
Date: Wed, 09 Jan 2019 18:03:18 -0800
To: w3c/screen-orientation <screen-orientation@noreply.github.com>
Cc: Subscribed <subscribed@noreply.github.com>
Message-ID: <w3c/screen-orientation/pull/131/review/191020910@github.com>
marcoscaceres approved this pull request.

Bunch of little suggestions/nits to apply. You'll probably need to tidy up again after they are applied. 

> +      </section>
+    </section>
+    <section>
+      <h2>
+        Interactions with other specifications
+      </h2>
+      <p>
+        This section explains how this specification interacts with other
+        related specifications of the platform.
+      </p>
+      <section>
+        <h2>
+          Interaction with Fullscreen API
+        </h2>
+        <p>
+          As a <a data-lt="security conditions">security condition</a>, a user

Ah, I'd forgotten that we now support automatic pluralization detection support in ReSpec. I just sent at pull request to enable it by default: https://github.com/w3c/respec/pull/2020


```suggestion
          As a <a>security condition</a>, a user
```


> +          <a>current orientation angle</a> is <code>0</code>. With the help of
+          the APIs described in this specification, the developer can <a>apply
+          an orientation lock</a> to a <a>document</a> using
+          <code>natural</code> to make that assumption a certitude. Otherwise,
+          reading the <a>document</a>'s <a>current orientation angle</a> via
+          <code>screen.orientation.angle</code> and listening to the
+          <code>"change"</code> event can help the developer to compensate the
+          screen orientation angle.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Application Manifest
+        </h2>
+        <p>
+          The Web Application Manifest specification [[appmanifest]] allows web

```suggestion
          The <a data-cite="appmanifest">Web Application Manifest</a> specification allows web
```

> +      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Application Manifest
+        </h2>
+        <p>
+          The Web Application Manifest specification [[appmanifest]] allows web
+          applications to set the <a>document</a>'s <a>default orientation</a>.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with CSS Device Adaptation
+        </h2>
+        <p>
+          The CSS Device Adaptation specification [[CSS-ADAPTATION]] defines,

```suggestion
          The <a data-cite="CSS-ADAPTATION">CSS Device Adaptation</a> specification defines,
```

> +      <section class='informative'>
+        <h2>
+          Interaction with CSS Device Adaptation
+        </h2>
+        <p>
+          The CSS Device Adaptation specification [[CSS-ADAPTATION]] defines,
+          independently of this document, a way to lock the screen orientation
+          for a web page using CSS.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Content Accessibility Guidelines
+        </h2>
+        <p>
+          The Web Content Accessibility Guidelines 2.1 specification [[WCAG21]]

```suggestion
          The <a data-cite="WCAG21">Web Content Accessibility Guidelines</a>
```
(as they are guidelines, we can drop the word "specification")

> +        <h2>
+          Interaction with CSS Device Adaptation
+        </h2>
+        <p>
+          The CSS Device Adaptation specification [[CSS-ADAPTATION]] defines,
+          independently of this document, a way to lock the screen orientation
+          for a web page using CSS.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Content Accessibility Guidelines
+        </h2>
+        <p>
+          The Web Content Accessibility Guidelines 2.1 specification [[WCAG21]]
+          includes a Success Criterion (<a href=

```suggestion
          includes a Success Criterion (<a
```

> +          Interaction with CSS Device Adaptation
+        </h2>
+        <p>
+          The CSS Device Adaptation specification [[CSS-ADAPTATION]] defines,
+          independently of this document, a way to lock the screen orientation
+          for a web page using CSS.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Content Accessibility Guidelines
+        </h2>
+        <p>
+          The Web Content Accessibility Guidelines 2.1 specification [[WCAG21]]
+          includes a Success Criterion (<a href=
+          "https://www.w3.org/TR/WCAG21/#orientation">SC 1.3.4</a>) related to

It's safer to just ommit the section numbers, as they often change. 

```suggestion
          data-cite="WCAG21#orientation">Success Criterion Orientation</a>) related to
```

> +          independently of this document, a way to lock the screen orientation
+          for a web page using CSS.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Content Accessibility Guidelines
+        </h2>
+        <p>
+          The Web Content Accessibility Guidelines 2.1 specification [[WCAG21]]
+          includes a Success Criterion (<a href=
+          "https://www.w3.org/TR/WCAG21/#orientation">SC 1.3.4</a>) related to
+          screen orientation.
+        </p>
+        <p>
+          The intent of this Success Criterion is to ensure that all <a href=

```suggestion
          The intent of this Success Criterion is to ensure that all <a
```

> +          for a web page using CSS.
+        </p>
+      </section>
+      <section class='informative'>
+        <h2>
+          Interaction with Web Content Accessibility Guidelines
+        </h2>
+        <p>
+          The Web Content Accessibility Guidelines 2.1 specification [[WCAG21]]
+          includes a Success Criterion (<a href=
+          "https://www.w3.org/TR/WCAG21/#orientation">SC 1.3.4</a>) related to
+          screen orientation.
+        </p>
+        <p>
+          The intent of this Success Criterion is to ensure that all <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content

```suggestion
          data-cite"WCAG21#dfn-essential">essential</a> content
```

> +          "https://www.w3.org/TR/WCAG21/#orientation">SC 1.3.4</a>) related to
+          screen orientation.
+        </p>
+        <p>
+          The intent of this Success Criterion is to ensure that all <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content
+          and functionality is available regardless of the display orientation
+          (portrait or landscape). Some websites and applications automatically
+          set the screen to a particular display orientation and expect that
+          users will respond by rotating their device to match.
+        </p>
+        <p>
+          However, some users may have their devices mounted in a fixed
+          orientation (e.g. on the arm of a power wheelchair). Therefore,
+          websites and applications need to support both orientations by making
+          sure <a href=

```suggestion
          sure <a
```

> +          screen orientation.
+        </p>
+        <p>
+          The intent of this Success Criterion is to ensure that all <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content
+          and functionality is available regardless of the display orientation
+          (portrait or landscape). Some websites and applications automatically
+          set the screen to a particular display orientation and expect that
+          users will respond by rotating their device to match.
+        </p>
+        <p>
+          However, some users may have their devices mounted in a fixed
+          orientation (e.g. on the arm of a power wheelchair). Therefore,
+          websites and applications need to support both orientations by making
+          sure <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content

```suggestion
          data-cite="WCAG21#dfn-essential">essential</a> content
```

> +          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content
+          and functionality is available regardless of the display orientation
+          (portrait or landscape). Some websites and applications automatically
+          set the screen to a particular display orientation and expect that
+          users will respond by rotating their device to match.
+        </p>
+        <p>
+          However, some users may have their devices mounted in a fixed
+          orientation (e.g. on the arm of a power wheelchair). Therefore,
+          websites and applications need to support both orientations by making
+          sure <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content
+          and functionality is available in each orientation. While the order
+          of content and method of functionality may have differences the
+          content and functionality must always be available. When a particular
+          orientation is <a href=

```suggestion
          orientation is <a
```

> +          and functionality is available regardless of the display orientation
+          (portrait or landscape). Some websites and applications automatically
+          set the screen to a particular display orientation and expect that
+          users will respond by rotating their device to match.
+        </p>
+        <p>
+          However, some users may have their devices mounted in a fixed
+          orientation (e.g. on the arm of a power wheelchair). Therefore,
+          websites and applications need to support both orientations by making
+          sure <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a> content
+          and functionality is available in each orientation. While the order
+          of content and method of functionality may have differences the
+          content and functionality must always be available. When a particular
+          orientation is <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a>, the user

```suggestion
          data-cite="WCAG21#dfn-essential">essential</a>, the user
```

> +          content and functionality must always be available. When a particular
+          orientation is <a href=
+          "https://www.w3.org/TR/WCAG21/#dfn-essential">essential</a>, the user
+          needs to be advised of the orientation requirements.
+        </p>
+      </section>
+    </section>
+    <section class='informative'>
+      <h2>
+        Examples
+      </h2>
+      <p>
+        This example shows the current screen orientation to the console every
+        time the screen orientation state changes.
+      </p>
+      <pre class='example highlight'>

As a few version ago, ReSpec automatically highlights... we can hint that it's HTML tho. 

```suggestion
      <pre class='example html'>
```

> +
+&lt;button onclick='screen.orientation.unlock()'&gt;
+  Unlock
+&lt;/button&gt;
+&lt;button onclick="screen.orientation.lock('portrait')"&gt;
+  Lock to portrait
+&lt;/button&gt;
+&lt;button onclick="screen.orientation.lock('landscape')"&gt;
+  Lock to landscape
+&lt;/button&gt;
+</pre>
+      <p>
+        This example waits to be fullscreen before locking the screen
+        orientation and starting.
+      </p>
+      <pre class='example highlight'>

```suggestion
      <pre class='example html'>
```

> +    document.onfullscreenchange = function() {
+      screen.orientation.lock('natural').then(startInternal);
+    }
+    document.documentElement.requestFullscreen();
+  }
+&lt;/script&gt;
+&lt;button onclick='start();'&gt;
+  Start
+&lt;/button&gt;
+
+</pre>
+      <p>
+        This example asks the user to manually rotate the device if the Screen
+        Orientation API is not available.
+      </p>
+      <pre class='example highlight'>

```suggestion
      <pre class='example js'>
```

> @@ -532,8 +747,8 @@ <h2>
           If locking the orientation results in an orientation change, the
           promise will be resolved when the orientation will change as
           described in the <a href=

```suggestion
          described in the <a
```

> @@ -532,8 +747,8 @@ <h2>
           If locking the orientation results in an orientation change, the
           promise will be resolved when the orientation will change as
           described in the <a href=
-          '#handling-screen-orientation-changes'>Handling screen orientation
-          changes</a> section.
+          '#screen-orientation-change-algorithm'>Screen orientation change

```suggestion
          >Screen orientation change
```

Just a note: if you see `<a href="#whatever">` in a ReSpec document, that is usually an Editor bug. In ReSpec, all internal linking should occur automatically unless there is a really good reason not to.  

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/screen-orientation/pull/131#pullrequestreview-191020910
Received on Thursday, 10 January 2019 02:03:40 UTC