Expand installation instructions for Linux.

README.md

@@ -33,20 +33,125 @@ ThunderLinks are durable even if you file the message. They are based on the uni
 
    These .reg files were generously provided by @mobileartur - please feel free to provide others or open pull requests to help other windows users. Note that 32bit Thunderbird is the current recommendation for Windows. For this reason we don't have registry files for 64-bit Thunderbird.
 
-   Linux (Tested on Ubuntu 18.04LTS):
-   ------------------------------------------
-   1. Install the desktop launcher that opens ThunderLinks in Thunderbird
-      - Manually
-         - Download the thunderlink launcher from  https://github.com/mikehardy/thunderlink/blob/master/integration/thunderbird-tl.desktop
-         - Copy it to `~/.local/share/applications/thunderbird-tl.desktop`
-      - Command line
-      - : `wget -P ~/.local/share/applications/ https://raw.githubusercontent.com/mikehardy/thunderlink/master/integration/thunderbird-tl.desktop`
-   2. Connect the "thunderlink" URL type to the launcher file
-      - Run the command `touch ~/.local/share/applications/mimeapps.list` to make sure you have a local MIME handler registry
-      - Add the handler: `echo "x-scheme-handler/thunderlink=thunderbird-tl.desktop" >> ~/.local/share/applications/mimeapps.list`
-      - Make the handler available: `update-desktop-database`
-
-   `mimeapps.list` might be placed here: `~/.config/mimeapps.list`
+Linux (Tested on Ubuntu 18.04LTS):
+----------------------------------
+
+1. Get an example Thunderlink and test it directly.
+
+   Right-click an email and choose "ThunderLink..." > "thunderlink". This will save it to the clipboard. It should look something like this:
+
+       thunderlink://[email protected]
+
+   Next, test the thunderlink URL directly from the command line like this:
+
+       $ thunderbird -thunderlink 'thunderlink://[email protected]'
+
+   If nothing happens, the addon is either not installed or not functioning. If the message ID is wrong, this will result in an error pop-up that says "Couldn't find an email message for ThunderLink". If it works, it will open the corresponding message. Proceed to the next step to start registering the `thunderlink://` URL scheme.
+
+2. Check if the `thunderlink://` protocol is already registered:
+
+       $ gio mime x-scheme-handler/thunderlink
+       No default applications for “x-scheme-handler/thunderlink”
+
+   If you don't have `gio`, use `xdg-mime` instead:
+
+       $ xdg-mime query default x-scheme-handler/thunderlink
+       $ echo $?
+       4
+
+   Blank output and a non-zero error code from `xdg-mime` mean it's not registered.
+
+3. Install the desktop file.
+
+   - Manually:
+      - Download the thunderlink launcher from  <https://github.com/mikehardy/thunderlink/blob/master/integration/thunderbird-tl.desktop>
+      - Copy it to `~/.local/share/applications/thunderbird-tl.desktop`
+
+   - Command line:
+     - `wget -P ~/.local/share/applications/ https://raw.githubusercontent.com/mikehardy/thunderlink/master/integration/thunderbird-tl.desktop`
+
+   These are the important lines in the desktop file:
+
+       Exec=thunderbird -thunderlink %u
+       MimeType=x-scheme-handler/thunderlink
+
+4. Make the desktop file executable.
+
+       $ chmod +x $HOME/.local/share/applications/thunderbird-tl.desktop
+
+   This is necessary [because of security precautions](https://askubuntu.com/questions/419610/permission-of-a-desktop-file)
+
+5. Register the `x-scheme-handler/thunderlink` mimetype to the desktop file.
+
+   Using `gio`:
+
+       $ gio mime x-scheme-handler/thunderlink thunderbird-tl.desktop
+       Set thunderbird-tl.desktop as the default for x-scheme-handler/thunderlink
+
+   Using `xdg-mime`:
+
+       $ XDG_UTILS_DEBUG_LEVEL=2 xdg-mime default 'thunderbird-tl.desktop' 'x-scheme-handler/thunderlink'
+
+   On most Linux distributions, these commands add this line:
+
+       x-scheme-handler/thunderlink=thunderbird-tl.desktop
+
+   to the configuration file `~/.config/mimeapps.list` under the `[Added Associations]` section.
+
+6. Check if it was successfully registered:
+
+       $ gio mime x-scheme-handler/thunderlink
+       Default application for “x-scheme-handler/thunderlink”: thunderbird-tl.desktop
+       Registered applications:
+           thunderbird-tl.desktop
+       Recommended applications:
+           thunderbird-tl.desktop
+
+   If you don't have `gio`, use `xdg-mime` instead:
+
+       $ xdg-mime query default x-scheme-handler/thunderlink
+       thunderbird-tl.desktop
+       $ echo $?
+       0
+
+7. Try opening a thunderlink directly with Thunderbird again:
+
+        $ thunderbird -thunderlink 'thunderlink://[email protected]'
+
+    and then with `xdg-open` to test the desktop file:
+
+        $ xdg-open 'thunderlink://[email protected]'
+
+   If the `xdg-open` command succeeds, then Thunderlink is installed properly.
+
+8. If `xdg-open` works but some applications do not, they may be using older configuration files.
+
+   For example, some applications use the old location for `mimeapps.list` instead of
+`~/.config/`. To fix this, edit this file with a text editor:
+
+       $ edit ~/.local/share/applications/mimeapps.list
+
+   and manually add this line:
+
+       x-scheme-handler/thunderlink=thunderbird-tl.desktop
+
+   under the "\[Default Applications\]" group. (This location is listed as "[for compatibility, deprecated](https://standards.freedesktop.org/mime-apps-spec/1.0.1/ar01s02.html)" by the FreeDesktop standard.)
+
+   Some applications read `mimeinfo.cache` instead of `mimeapps.list`, so regenerate the cache with `update-desktop-database`.
+
+        $ update-desktop-database ~/.local/share/applications
+
+   Note that this will not read the file at `~/.config/mimeapps.list`, it will read the file at `~/.local/share/applications/mimeapps.list`.
+
+   There is also an [even older deprecated file](https://lists.freedesktop.org/archives/xdg/2014-February/013177.html) called `defaults.list` that is still used by some applications. Handle this in the same way; edit this file with a text editor:
+
+       $ edit ~/.local/share/applications/defaults.list
+
+   and manually add this line:
+
+       x-scheme-handler/thunderlink=thunderbird-tl.desktop
+
+   under the "\[Default Applications\]" group.
 
    <b>Mac:</b>
    ----------