== Some notes on how _xdg-open_ picks which web browser to use

Let's start with [[my tweet
https://twitter.com/thatcks/status/742425024590708736]]:

> It sure would be convenient if xdg-open documented how it picked which
> browser to use, so you could maybe change that to one you like.

XDG here is what used to be called the 'X Desktop Group' and is now
[[freedesktop.org https://www.freedesktop.org/]] ([[per wikipedia
https://en.wikipedia.org/wiki/Freedesktop.org]]). As you might then
guess, _xdg-open_ the program is the canonical KDE/GNOME/etc agnostic
way of opening (among other things) an URL in whatever is nominally
your preferred browser. Since providing a web interface as your
package's UI is an increasingly common thing to do these days, there
are any number of programs and scripts and so on that want to do
this and do it by just running _xdg-open_, which gives you whatever
[[strange browser https://en.wikipedia.org/wiki/Arora_(web_browser)]]
_xdg-open_ decided to inflict on you today.

If you read [[the _xdg-open_ manpage
https://portland.freedesktop.org/doc/xdg-open.html]], it's remarkably
uninformative about how it decides what your default or preferred
web browser is. On the one hand _xdg-open_ is currently a shell
script so you could just read it to find this out; on the other
hand, it's a 900+ line shell script full of stuff, which makes it
not exactly clear 'documentation'. So here are some notes on the
current behavior, boiled down to the useful bits.

(Because none of this is documented, [[freedesktop.org]] is free
to change it at any time if they feel like it. They probably won't,
though.)

Broadly, _xdg-open_ does the following when you ask it to open an
URL:

* first, it tries to figure out if you're running a desktop
  environment that it knows about. If you are, it uses the
  desktop's own mechanism to open URLs if there is one (these
  are things like _kde-open_, _gvfs-open_, and _exo-open_).
  The important thing here is that this should automatically
  respect your normal desktop browser preference, since it's
  using the same mechanism.

* if _$BROWSER_ is set, it's used immediately. I'll discuss
  what it can be set to later.

* in some but not all versions of _xdg-open_, it will attempt
  to determine the correct program to handle the nominal MIME
  type of 'x-scheme-handler/http' (or https, or ftp, or whatever)
  and then run this program. This determination is made by
  _xdg-mime_; how it works is complicated enough to require
  [[another entry XdgMimeTypeSearching]].

  In versions of _xdg-open_ that support this, it's extremely
  likely that this will produce a result and _xdg-open_ will
  never go on to its final option.

* if all else fails, _xdg-open_ tries to run a whole bunch of possible
  browsers (via the _$BROWSER_ mechanism). The most important thing
  about this is that ~~the first default browser _xdg-open_ tries
  is _x-www-browser_~~.

Some but not all Linux distributions have a _/usr/bin/x-www-browser_.
If yours has one, it may or may not point to something useful or
what you want, and it may vary from version to version (and on what
packages you wind up installing). For example, on our Ubuntu 12.04
and 14.04 machines _x-www-browser_ points to [[arora
https://en.wikipedia.org/wiki/Arora_(web_browser)]] by default,
which is not what I consider a particularly good choice on machines
with Firefox installed (it's certainly likely to puzzle users who
wind up running it). On 16.04 it points to Chromium, which is at
least a plausible default choice.

On current Fedora and Ubuntu 16.04, the full list of (graphical)
browsers, in order, is:

> x-www-browser firefox iceweasel seamonkey mozilla epiphany
> konqueror chromium-browser google-chrome

The useful thing here is that _xdg-open_ searches for all of these
using your _$PATH_, so you can create a personal _x-www-browser_
symlink that points to whatever you want without having to risk
unintended side effects from eg setting _$BROWSER_.

If your _xdg-open_ uses _xdg-mime_, you can determine what
program it will use (more or less) by running eg:

.pn prewrap on

 $ xdg-mime query default x-scheme-handler/http
 firefox.desktop

Xdg-mime will let you set this stuff as well as query it, but of
course doing so may have more consequences than just changing
_xdg-open_'s behavior. However at that point there is no really
good solution; if _xdg-open_ is consulting _xdg-mime_, I think all
you can do is either set _$BROWSER_ or set _xdg-mime_'s defaults.

(If you're setting scheme handlers in _xdg-mime_, remember to get
at least _http_ and _https_, and perhaps _ftp_ as well.)

While the _xdg-open_ manpage will refer you to [[the _xdg-settings_
manpage https://portland.freedesktop.org/doc/xdg-settings.html]],
this is potentially quite misleading. If you aren't using a desktop
environment, there's no guarantee that what _xdg-settings_ reports
as your default browser is what _xdg-open_ will necessarily run.
The two scripts use different code and as far as I can tell, neither
makes any particular attempt to carefully duplicate each other's
logic.

(If you are running a desktop environment that _xdg-settings_
knows about, well, you're at the mercy of how well it can read
out your DE's default browser. I wouldn't hold my breath there.)

=== Sidebar: What _$BROWSER_ can be set to

As _xdg-open_ interprets it, _$BROWSER_ is a colon separated list
of *commands*, not just program names (ie you can include things
like command line switches). A command may contain a _%s_, which
will be substituted with the URL to be opened; otherwise the URL
is just tacked on the end of the command. Xdg-open does not exactly
have sophisticated handling of quoting and argument splitting or
anything, so I would do nothing tricky here; I wouldn't even really
trust the _%s_ substitution. If you think you need it, use a cover
shell script.