Re: [w3c/manifest] Add shortcuts feature to the explainer and spec (#768)

mgiuca approved this pull request.

Thanks for the hard work on this @aarongustafson . Just left a few more comments, mostly relating to being clear about normative vs non-normative sentences.

Feel free to merge this after making those changes.

> @@ -2403,6 +2408,98 @@ <h3>
           can get their games and apps rated with IARC</a>.
         </p>
       </section>
+      <section>
+        <h3>
+          <code>shortcuts</code> member
+        </h3>
+        <p>
+          The <dfn>shortcuts</dfn> member is an <a>array</a> of
+          <a>ShortcutItem</a>s that provide access to key tasks within a web
+          application. For example, they can be used to link directly to a

The "for example" sentence should be in a note paragraph as it is non-normative.

> @@ -2403,6 +2408,98 @@ <h3>
           can get their games and apps rated with IARC</a>.
         </p>
       </section>
+      <section>
+        <h3>
+          <code>shortcuts</code> member
+        </h3>
+        <p>
+          The <dfn>shortcuts</dfn> member is an <a>array</a> of
+          <a>ShortcutItem</a>s that provide access to key tasks within a web
+          application. For example, they can be used to link directly to a
+          user's timeline within a social media application or their recent
+          orders in an e-commerce context.
+        </p>
+        <p>
+          A developer may provide as many shortcuts as they like, but the user

Shouldn't use the keyword "may" when this is not a normative requirement.

I would just drop the first clause and rewrite this sentence. Suggestion: "How shortcuts are presented, and how many of them are shown to the user, is at the discretion of the user agent and/or operating system."

> @@ -2403,6 +2408,98 @@ <h3>
           can get their games and apps rated with IARC</a>.
         </p>
       </section>
+      <section>
+        <h3>
+          <code>shortcuts</code> member
+        </h3>
+        <p>
+          The <dfn>shortcuts</dfn> member is an <a>array</a> of
+          <a>ShortcutItem</a>s that provide access to key tasks within a web
+          application. For example, they can be used to link directly to a
+          user's timeline within a social media application or their recent
+          orders in an e-commerce context.
+        </p>
+        <p>
+          A developer may provide as many shortcuts as they like, but the user
+          agent and operating system will decide how many are presented to the
+          user. For this reason, it is recommended that developers order their

This sentence is non-normative and should be in a note. Also you can't use the keyword "recommended" when giving instructions to the developer (since this spec governs how UAs work, not how developers should behave). Reword as "Developers are encouraged to order their ...".

> +          <var>shortcut.icons</var> to the result of running <a>processing
+          `ImageResource` members</a> given <var>shortcut.icons</var> and
+          <var>manifest URL</var>. For each <var>shortcut</var>
+          (<a>ShortcutItem</a>) in the sequence, parse
+          <var>shortcut</var>["<a>url</a>"] using <var>manifest URL</var> as
+          the base URL.
+        </p>
+        <p>
+          A user agent SHOULD expose shortcuts via interactions that are
+          consistent with exposure of an application icon's context menu in the
+          host operating system (e.g., right click, long press). A user agent
+          SHOULD render the shortcuts in the same order as they are provided in
+          the manifest. A user agent SHOULD represent the shortcuts in a manner
+          consistent with exposure of an application icon's context menu in the
+          host operating system. A user agent MAY truncate the list of
+          shortcuts presented in order to remain consistent with conventions of

Perhaps add "... with conventions **or limitations** of  ..." (since it may not just be conventions that constrain the UA, but a hard limit).

> +        };
+      </pre>
+      <p>
+        Each <a>ShortcutItem</a> represents a link to a key task or page within
+        a web app. A user agent can use these values to assemble a context menu
+        to be displayed by the operating system when a user engages with the
+        web app's icon.
+      </p>
+      <section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
+        <h3>
+          <code>name</code> member
+        </h3>
+        <p>
+          The <dfn>name</dfn> member of a <a>ShortcutItem</a> is a
+          <a>string</a> that represents the name of the shortcut as it is
+          usually displayed to the user in a context menu

Period.

> +        </h3>
+        <p>
+          The <dfn>short_name</dfn> member of a <a>ShortcutItem</a> is a
+          <a>string</a> that represents a short version of the name of the
+          shortcut. It is intended to be used where there is insufficient space
+          to display the full name of the shortcut.
+        </p>
+      </section>
+      <section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
+        <h3>
+          <code>description</code> member
+        </h3>
+        <p>
+          The <dfn>description</dfn> member of a <a>ShortcutItem</a> is a
+          <a>string</a> that allows the developer to describe the purpose of
+          the shortcut. User agents may choose to expose this information to

Replace "may choose to" with "MAY". (i.e., make this a normative requirement)

> +          activated.
+        </p>
+      </section>
+      <section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
+        <h3>
+          <dfn>icons</dfn> member
+        </h3>
+        <p>
+          The <a>icons</a> member of an <a>ShortcutItem</a> member is an
+          <a>array</a> of <a>ImageResource</a>s that can serve as iconic
+          representations of the shortcut in various contexts.
+        </p>
+      </section>
+      <section>
+        <h3>
+          <dfn>Launching a shortcut</dfn>

This isn't linked from anywhere.

I think it would be good if the main paragraph above that introduces all the normative requirements had a sentence to the effect of "When the user invokes a shortcut from the operating system menu, the user agent SHOULD run **Launching a shortcut**".

> +          <code>description</code> member
+        </h3>
+        <p>
+          The <dfn>description</dfn> member of a <a>ShortcutItem</a> is a
+          <a>string</a> that allows the developer to describe the purpose of
+          the shortcut. User agents may choose to expose this information to
+          assistive technology.
+        </p>
+      </section>
+      <section data-dfn-for="ShortcutItem" data-link-for="ShortcutItem">
+        <h3>
+          <code>url</code> member
+        </h3>
+        <p>
+          The <dfn>url</dfn> member of a <a>ShortcutItem</a> is a <a>URL</a> to
+          which a user agent should navigate when the associated shortcut is

You can't use the keyword "should" here, unless you want to introduce a normative requirement. (But since you already give normative text for this in the algorithm below, I think just reword this.) "the URL that opens when the shortcut is activated."

-- 
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/manifest/pull/768#pullrequestreview-310861835