various fixes

docs/common-tasks/opening-urls-in-vms.md

@@ -18,17 +18,20 @@ Opening files and URLs in other VMs rely on the `qubes.OpenInVM` and `qubes.Open
 
 Qubes [RPC policies](https://www.qubes-os.org/doc/rpc-policy/) allow to fine tune how those RPC services can be used between VMs.
 
-### The powerful 'ask' policy ###
+### The (powerful) `ask` policy ###
 
 A very powerful and convenient RPC policy rule is `ask`: in that case a dialog with the list of destination VMs pops up each time the RPC service is called, allowing the user to select a destination VM depending on his work's context (eg. the target URL's level of trust, protocol, file [MIME](https://en.wikipedia.org/wiki/Media_type) type, ...).
 
-It is impossible to overstate how flexible this is and how much security it can add to one's workflow: while opening things in dispVMs is the most secure approach the problem is starting a dispVM for every URL/file opened takes far too much time and resources, leading people to open files/URLs in persistent VMs instead.
+It is impossible to overstate how flexible this is and how much security it can add to one's workflow: while opening things in dispVMs is the most secure approach the problem is starting a dispVM for *each* URL/file takes far too much time and resources, leading people to open files/URLs in persistent VMs instead.
 
-With the `ask` policy the dialog allows one to either start a new dispVM (not only the default but any dispVM configured - see section FIXME below) or send the URL/file to an already running (disp)VM. So the first time an URL is clicked the (disp)VM will start if it wasn't running. The next time another URL/file is sent, there's no need start a new dispVM, one can instead select the already running (disp)VM. It is also possible to choose 'cancel' in the dialog and nothing launches.
+With the `ask` policy the VM selection dialog allows one to either start any new dispVM (not only default dispVMs but any other type of dispVM configured - see section "Considerations on dispVMs" below) or send the URL/file to an already running (disp)VM. So the first time an URL/file is open the (disp)VM will start if it wasn't running. The next time another URL/file is sent, there's no need start a new dispVM, one can instead select the already running (disp)VM. It is also possible to choose 'cancel' in the dialog and nothing will launch.
 
-This setup makes it possible to control if and on which network (eg. "clearnet" or TOR) an URL is requested - always.
+This setup makes it possible to control if and on which network (eg. "clearnet", TOR, VPN) an URL is requested - always.
 
-### The 'allow' policy ###
+Note: when using the `ask` policy, the destination VM specified in `srcVM` by `qvm-open-in-vm` is ignored if no `allow` match exists for that given `srcVM`/`dstVM` combo.
+
+
+### The `allow` policy ###
 
 If an `allow` policy is configured with a destination other than `$dispvm` it is obviously up to `srcVM` to provide the name of the destination VM. The RPC policies should then be configured accordingly.
 
@@ -49,7 +52,7 @@ $anyvm $dispvm allow
 $anyvm $anyvm ask
 ~~~
 
-`/etc/qubes-rpc/qubes.OpenInVM`
+`/etc/qubes-rpc/qubes.OpenInVM`:
 
 ~~~
 $anyvm $anyvm ask
@@ -59,7 +62,7 @@ $anyvm $anyvm ask
 Considerations on dispVMs
 -------------------------
 
-### 'ask' policy / security tradeoff ###
+### Security policy of the 'ask' RPC ###
 
 In the section above we've seen how using the 'ask' RPC policy allowed us to start a (disp)VM once and use it for opening subsequent URLs (or files). This effectively mitigates the the long starting times of dispVMs, at the price of a loss in compartmentalization. It is thus up to the user to manage the lifecycle of a dispVM, killing it when necessary when a a clean state is required.
 
@@ -75,7 +78,7 @@ When opening and modifying a document in a dispVM, the content is "sent" back to
 
 ### Using "named" dispVMs ###
 
-As of Qubes R4.0, it is impossible to "name" a dispVM - ie. opening a URL/file in a standard dispVMs will always start a VM with a 'dispXXXX' name (eg. 'disp1234').
+As of Qubes R4.0, it is impossible to "name" a dispVM: opening a URL/file in a standard dispVMs will always start a VM with a 'dispXXXX' name (eg. 'disp1234').
 
 If for some reason a user needs to have use a dispVM with a given name - which is for instance handy for 'allow' RPC policies - he/she can do like so (replace `fedora-28-dvm` with the dvm template you want to use):
 
@@ -88,7 +91,7 @@ This VM works like a regular VM, with the difference that its private disk is wi
 
 ### Sample real-world workflow ###
 
-Here's an example of a real-world setup/workflow:
+Here's an example of a real-world, thoroughly used setup/workflow:
 
 Disposable VMs are based on the following templates:
 
@@ -102,7 +105,7 @@ AppVMs are highly specialized: vault (offline), documents (offline), media (offl
 Configuring `srcVM`
 -------------------
 
-The subsections below list various approaches. A hassle-free but very powerful setup is to use the application-independent approach below with the `ask` RPC policy.
+The subsections below list various approaches on opening URLs/files from `srcVM` in destination VMs. A hassle-free but very powerful setup is to use the application-independent approach documented in the next subsection with the `ask` RPC policy.
 
 
 ### Application-independent setup ###
@@ -132,7 +135,7 @@ The same can be done with any Mime type (see `man xdg-mime` and `xdg-settings`);
 Notes:
 
 - for some reasons some applications may not honor the new xdg application/handler (eg. if you had previously configured default applications), in which case you'd have to manually select the xdg application (see section below).
-- `qvm-open-in-vm dstVM` can be replaced by a user written wrapper with custom logic for selecting a specific dstVM depending on the URL/file type, site level of trust, ... ; The RPC policies should be configured accordingly.
+- `qvm-open-in-vm dstVM` can be replaced by a user written wrapper with custom logic for selecting a specific `dstVM` depending on the URL/file type, site level of trust, ... ; The RPC policies should be configured accordingly.
 - very security conscious users should consider basing AppVMs on minimal templates; that way, unless the default handler is set, nothing else is usually there to open those files (little risk, plus the VMs are firewalled or offline).
 
 
@@ -143,6 +146,15 @@ Most applications provide a way to select a given program to use for opening spe
 The subsections below show how to configure popular applications.
 
 
+#### Firefox, Chrome/Chromium ####
+
+Those browsers have an option to define programs associated to a file (MIME) type. It is pretty straightforward to configure and is outside the scope of this document.
+
+An alternative is to use Raffaele Florio's [qubes-url-redirector](https://github.com/raffaeleflorio/qubes-url-redirector) add-on, which provides a lot of flexibility when opening links without the hassle of having to write custom shell wrappers to `qvm-open-in-vm`. For instance links can be opened with a context menu and the add-on's default behavior can be configured, even with whitelist regexes.
+
+Note: the qubes-url-redirector add-on will likely be included officialy in the next Qubes release (see [this](https://github.com/QubesOS/qubes-issues/issues/3152) issue). The addon may also support Thunderbird in the future.
+
+
 #### Thunderbird ####
 
 Opening attachements: "actions" must be defined for opening attachements; see [this document](http://kb.mozillazine.org/Actions_for_attachment_file_types), section "Download Actions" settings".
@@ -163,15 +175,6 @@ qvm-open-in-vm dstVM "$@"
 ~~~
 
 
-#### Firefox, Chrome/Chromium ####
-
-Those browsers have an option to define programs associated to a file (MIME) type. It is pretty straightforward to configure and is outside the scope of this document.
-
-An alternative is to use Raffaele Florio's [qubes-url-redirector](https://github.com/raffaeleflorio/qubes-url-redirector) add-on, which provides a lot of flexibility when opening links without the hassle of having to write custom shell wrappers to `qvm-open-in-vm`. For instance links can be opened with a context menu and the add-on's default behavior can be configured, even with whitelist regexes.
-
-Note: the qubes-url-redirector add-on will likely be included officialy in the next Qubes release (see [this](https://github.com/QubesOS/qubes-issues/issues/3152) issue). The addon may also support Thunderbird in the future.
-
-
 #### Vi ####
 
 Opening URLs: put the following in `$HOME/.vimrc`: