- From: Joshua Bell <notifications@github.com>
- Date: Tue, 14 Sep 2021 09:23:03 -0700
- To: w3c/manifest <manifest@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <w3c/manifest/pull/1005/review/754140403@github.com>
@inexorabletash commented on this pull request.
Initial feedback. I didn't get all the way to the end, LMK when it's ready for another look.
> @@ -1012,6 +1012,92 @@ <h3>
conventions or limitations of the host operating system.
</p>
</section>
+ <section>
+ <h3>
+ `file_handlers` member
+ </h3>
+ <p>
+ The [=manifest's=] <code><dfn data-export="" data-dfn-for=
+ "manifest">`file_handlers`</dfn></code> member is a [=list=] that
+ represents urls within the app that can handle launches of a given
+ file type (TODO: link to definition of file type).
Does ReSpec have an actual TODO styling mechanism, or is the intent to define this before merging?
> + <h3>
+ `file_handlers` member
+ </h3>
+ <p>
+ The [=manifest's=] <code><dfn data-export="" data-dfn-for=
+ "manifest">`file_handlers`</dfn></code> member is a [=list=] that
+ represents urls within the app that can handle launches of a given
+ file type (TODO: link to definition of file type).
+ </p>
+ <p>
+ How file handlers are registered and disambiguated are at the
+ discretion of the operating system.
+ </p>
+ <p>
+ To <dfn>process the `file_handlers` member</dfn>, given [=ordered
+ map=] |json:ordered map|, [=ordered map=] |manifest:ordered map|:
nit: ", and" or just "and"
> + </li>
+ <li>[=list/For each=] |entry:ordered map| of |json|["file_handlers"]:
+ <ol>
+ <li>Let |file_handler:ordered map| be [=process a file handler
+ item=] with |entry|.
+ </li>
+ <li>If |file_handler| is failure, continue.
+ </li>
+ <li>[=list/Append=] |file_handler| to |processedFileHandlers|.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ A user agent SHOULD register the file handlers with the operating
+ system via interactions that are consistent with:
While I like lists, this phrasing makes the bullets into sentence fragments. Can you reword the bullets so they're more complete sentences?
> + <li>Let |file_handler:ordered map| be [=process a file handler
+ item=] with |entry|.
+ </li>
+ <li>If |file_handler| is failure, continue.
+ </li>
+ <li>[=list/Append=] |file_handler| to |processedFileHandlers|.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ A user agent SHOULD register the file handlers with the operating
+ system via interactions that are consistent with:
+ </p>
+ <ul>
+ <li>The [=file handler/icon=] and [=file handler/name=] appearing in
It's more spec-like to describe the abstract concept, then give examples. e.g.
"The icon and name appear in the host operating system surfaces presenting options for opening files, for example within "Open with..." context menus for associated file types."
> + <li>File types with multiple possible handlers can be disambiguated
+ by UX provided by the operating system.
+ </li>
+ </ul>
+ <p>
+ A user agent MAY (TODO: should?) prevent registered file handlers
+ from registering as the 'default' file handler for a give type if the
+ operating system allows.
+ </p>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Default [=file handler=].
+ </h3>
+ <p>
+ Depending on the operating system capabilities that the
Grammar: I think you want: "Depending on the operating system capabilities, the file handler could..."
> + <p>
+ A user agent MAY (TODO: should?) prevent registered file handlers
+ from registering as the 'default' file handler for a give type if the
+ operating system allows.
+ </p>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Default [=file handler=].
+ </h3>
+ <p>
+ Depending on the operating system capabilities that the
+ [=manifest/file handler=] could become a 'default' handler (e.g.
+ handling launches of a given file type automatically) of a given file
+ type (todo define? link?) or [=mime type=] without the explicit
+ knowledge of the user, depending on the operating system. To protect
... and don't also end the sentence with "depending on the operating system."
> + </ul>
+ <p>
+ A user agent MAY (TODO: should?) prevent registered file handlers
+ from registering as the 'default' file handler for a give type if the
+ operating system allows.
+ </p>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Default [=file handler=].
+ </h3>
+ <p>
+ Depending on the operating system capabilities that the
+ [=manifest/file handler=] could become a 'default' handler (e.g.
+ handling launches of a given file type automatically) of a given file
+ type (todo define? link?) or [=mime type=] without the explicit
Maybe go ahead and create a stub definition for "file type" in this doc, and put a TODO there, then have these links point at it?
> + Privacy consideration: Default [=file handler=].
+ </h3>
+ <p>
+ Depending on the operating system capabilities that the
+ [=manifest/file handler=] could become a 'default' handler (e.g.
+ handling launches of a given file type automatically) of a given file
+ type (todo define? link?) or [=mime type=] without the explicit
+ knowledge of the user, depending on the operating system. To protect
+ against possible mis-use, user agents MAY choose to offer the user
+ the functionality to not launch the web application, or even
+ unregister a given file handler for a web application.
+ </p>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Name & icon.
nit: I'd spell out "and"
> + [=manifest/file handler=] could become a 'default' handler (e.g.
+ handling launches of a given file type automatically) of a given file
+ type (todo define? link?) or [=mime type=] without the explicit
+ knowledge of the user, depending on the operating system. To protect
+ against possible mis-use, user agents MAY choose to offer the user
+ the functionality to not launch the web application, or even
+ unregister a given file handler for a web application.
+ </p>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Name & icon.
+ </h3>
+ <p>
+ The name and icon of each file handler can be sensitive to privacy
+ and security, as there isn't a specified way for the user to see &
nit: spell out "and"
> + type (todo define? link?) or [=mime type=] without the explicit
+ knowledge of the user, depending on the operating system. To protect
+ against possible mis-use, user agents MAY choose to offer the user
+ the functionality to not launch the web application, or even
+ unregister a given file handler for a web application.
+ </p>
+ </section>
+ <section>
+ <h3>
+ Privacy consideration: Name & icon.
+ </h3>
+ <p>
+ The name and icon of each file handler can be sensitive to privacy
+ and security, as there isn't a specified way for the user to see &
+ confirm these. Due to this, user agents MAY choose to replace these
+ with name and icons derived from the application's icon and name in
consistency: "icon" above vs. "icons" here.
> @@ -1118,6 +1204,9 @@ <h3>
<li>[=Process the `shortcuts` member=] passing |json|, |manifest|,
and |manifest URL|.
</li>
+ <li>[=Process the `file_handlers` member=] passing |json|,
nit: ", and" or just "and"
> @@ -1787,6 +1876,172 @@ <h2>
</ol>
</section>
</section>
+ <section>
+ <h2>
+ File Handler Items
+ </h2>
+ <p>
+ Each <dfn data-local-lt="file handler's">file handler</dfn> represents
Does ReSpec require the lt? Can you put the `'s` outside the link where used instead?
> @@ -1787,6 +1876,172 @@ <h2>
</ol>
</section>
</section>
+ <section>
+ <h2>
+ File Handler Items
+ </h2>
+ <p>
+ Each <dfn data-local-lt="file handler's">file handler</dfn> represents
+ a url in the scope of the application that can handle launches with
nit: URL
> @@ -1787,6 +1876,172 @@ <h2>
</ol>
</section>
</section>
+ <section>
+ <h2>
+ File Handler Items
+ </h2>
+ <p>
+ Each <dfn data-local-lt="file handler's">file handler</dfn> represents
+ a url in the scope of the application that can handle launches with
Maybe just "handles launches" instead of "can handle launches" ? Less passive voice, I think.
> + </p>
+ <ul>
+ <li>[=file handler/action=]
+ </li>
+ <li>[=file handler/name=]
+ </li>
+ <li>[=file handler/accepts=]
+ </li>
+ <li>[=file handler/icons=]
+ </li>
+ </ul>
+ <p>
+ A user agent can use these members to associate the web application
+ with specific file extensions or [=mime types=] on the operating
+ system. When a user launches this association When a user launches a
+ file that is associated with A user agent can use these members to
Looks like the first sentence doesn't get finished?
> + a url in the scope of the application that can handle launches with
+ file types it accepts. It has the following members:
+ </p>
+ <ul>
+ <li>[=file handler/action=]
+ </li>
+ <li>[=file handler/name=]
+ </li>
+ <li>[=file handler/accepts=]
+ </li>
+ <li>[=file handler/icons=]
+ </li>
+ </ul>
+ <p>
+ A user agent can use these members to associate the web application
+ with specific file extensions or [=mime types=] on the operating
This might be a good candidate to hoist into a definition of "file type" (covering extensions + mime types) and then linking from here and elsewhere.
> + "file handler">accept</dfn></code> member is a <a>dictionary</a>
+ mapping MIME types to extensions. This ensures applications will work
+ on operating systems that only support one of the two (example:
+ Linux, which only supports MIME types). This also allows applications
+ to register custom file types. See steps to [=associate a file
+ handler=] for more information. (TODO fix this?)
+ </p>
+ </section>
+ <section>
+ <h3>
+ `icons` member
+ </h3>
+ <p>
+ The <a>file handler</a>'s <code><dfn data-dfn-for=
+ "file handler">icons</dfn></code> member lists images that serve as
+ iconic representations of file. This MAY be replaced by the user
"files" or "file types"
Also, maybe replace "iconic" with "graphical" or "visual" ?
> + <h2>
+ Processing file handler items
+ </h2>
+ <p>
+ To <dfn>process a file handler item</dfn>, given [=ordered map=]
+ |item:ordered map|, [=URL=] |start_url:URL|, [=URL=] |scope:URL|, and
+ [=URL=] |manifest URL:URL|.
+ </p>
+ <ol class="algorithm">
+ <li>Return failure if it's the case that:
+ <ul>
+ <li>|item| is not [=ordered map=].
+ </li>
+ <li>|item|["action"] doesn't [=map/exist=].
+ </li>
+ <li>|item|["action"] is not a [=string=].
WDYT about combining these pairs, e.g. "item["action"] exists and is a string" ?
> + <ul>
+ <li>|item| is not [=ordered map=].
+ </li>
+ <li>|item|["action"] doesn't [=map/exist=].
+ </li>
+ <li>|item|["action"] is not a [=string=].
+ </li>
+ <li>|item|["name"] doesn't [=map/exist=].
+ </li>
+ <li>|item|["name"] is the empty string.
+ </li>
+ <li>|item|["accepts"] doesn't [=map/exist=].
+ </li>
+ <li>|item|["accepts"] is not a [=sequence=].
+ </li>
+ <li>|item|["accepts"] is an empty [=sequence=].
Linkify empty
> + item=] with |entry|.
+ </li>
+ <li>If |file_handler| is failure, continue.
+ </li>
+ <li>[=list/Append=] |file_handler| to |processedFileHandlers|.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ A user agent SHOULD register the file handlers with the operating
+ system via interactions that are consistent with:
+ </p>
+ <ul>
+ <li>The [=file handler/icon=] and [=file handler/name=] appearing in
+ an "Open with.." menu in the context menu of associated files.
FWIW, GitHub is rendering @tomayac's suggestion as a skinny ellipsis character (`…`) rather than just three periods (`...`). I'm not sure which was intended.
> + item=] with |entry|.
+ </li>
+ <li>If |file_handler| is failure, continue.
+ </li>
+ <li>[=list/Append=] |file_handler| to |processedFileHandlers|.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ A user agent SHOULD register the file handlers with the operating
+ system via interactions that are consistent with:
+ </p>
+ <ul>
+ <li>The [=file handler/icon=] and [=file handler/name=] appearing in
+ an "Open with.." menu in the context menu of associated files.
... but be consistent in the doc.
--
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/1005#pullrequestreview-754140403
Received on Tuesday, 14 September 2021 16:23:17 UTC