Rephrase some of the media galleries permission information.

chrome/common/extensions/docs/static/mediaGalleries.html

 <div id="pageData-name" class="pageData">Media Galleries</div>
 
 <!-- BEGIN AUTHORED CONTENT -->
 <p>
 The media galleries API allows you to access media files (images,
 video, audio) from the user's local disks (with the user's consent).
 </p>
 
 <p>
 Using the API, you can prompt the user for permission to access the media
 galleries. The permission dialog will contain common media locations for
 the platform and will allow the user to add additional locations. From those
 locations, only media files will be present in the file system objects.
 </P>
 
 <h2 id="manifest">Manifest</h2>
 <p>You must declare the type of access to the media gallery you require
-in your extension's manifest to use the API.  Currently only the
-"mediaGalleriesRead" permission is allowed.  This permission does not
-currently trigger an install time permission prompt because it requires
-the user to grant permission at runtime.</p>
+in your extension's manifest to use the API.  Currently the only access
+type permission is "mediaGalleriesRead," which will allow your extension
+to read from the media galleries.  This permission does not trigger an
+install time permission prompt because the user must still grant access
+to particular galleries at runtime unless the "mediaGalleriesAllGalleries"
+permission is used.</p>

[battre, 2012/07/31 21:34:15]

So do you need to request both "mediaGalleriesRead" and
"mediaGalleriesAllGalleries"?

[vandebo (ex-Chrome), 2012/07/31 21:36:06]

To get default access to all well known galleries, yes.  If you only request
"mediaGalleriesRead" then you will start with no access to galleries and will
have to use the runtime dialog to have the user grant permission.

[battre, 2012/07/31 21:47:18]

Sorry, let me phrase this differently. Do you have read access if you specify
*only* "mediaGalleriesAllGalleries"? Or "Does mediaGalleriesAllGalleries subsume
mediaGalleriesRead"?

 
 <p>
 You may also specify the "mediaGalleriesAllGalleries" permission to get
 access to all auto-detected media galleries on the user's computer.  This
 permission displays an install time prompt indicating that the extension
 will have access to all of the user's media files.
 </p>

[battre, 2012/08/01 09:35:47]

Here is my proposal:
<h2 id="manifest">Manifest</h2>
<p>The media galleries API distinguishes two orthogonal permissions; the access
type (reading, writing, appending files) and the locations in which your
extension may access files. For example:</p>
<pre>{
  "name": "My extension",
  ...
  <b>"permissions": [
    "mediaGalleriesRead",
    "mediaGalleriesAllGalleries"
  ]</b>,
  ...
}</pre>

<p>The "mediaGalleriesRead" permission grants your extension the right to read
files. This permissison does not trigger an install time permission prompt
because the user must still grant access to particular galleries at runtime by
using a directory or file selector dialog.</p>

<p>You may also specify the "mediaGalleriesAllGalleries" permission to get
location access to all auto-detected media galleries on the user's computer. In
this case, access to the all known media galleries does not trigger a file or
directory selector dialog and permission is automatically granted to the degree
specified by the access type (e.g. "mediaGalleriesRead" grants read access). The
"mediaGalleriesAllGalleries" permission displays an install time prompt
indicating that the extension will have access to all of the user's media
files.</p>

<p>Currently "mediaGalleriesRead" is the only access type supported by this API.
Write and append access with be implemented soon.</p>

 
 <!-- END AUTHORED CONTENT -->