From 1db943f8310a1fa264742868b675115f05340ecd Mon Sep 17 00:00:00 2001
From: Federico Terzi <federicoterzi96@gmail.com>
Date: Sun, 29 Sep 2019 17:43:09 +0200
Subject: [PATCH] Improve configuration docs

---
 _sass/_docs.scss      | 21 +++++++++++
 docs/configuration.md | 83 +++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 101 insertions(+), 3 deletions(-)

diff --git a/_sass/_docs.scss b/_sass/_docs.scss
index c7fac2f..c3fba9a 100644
--- a/_sass/_docs.scss
+++ b/_sass/_docs.scss
@@ -32,6 +32,27 @@
             margin: 0 0 15px 0;
         }
     }
+    
+    table {
+        border-collapse: collapse;
+
+        @media screen and (max-width: $screen-phone) {
+            display: block;
+            overflow-x: auto;
+            white-space: nowrap;
+        }
+       
+    }
+
+    td, th {
+        border: 1px solid #ddd;
+        padding: 8px;
+    }
+
+    th {
+        background-color: $lightGrayColor;
+    }
+      
 }
 
 .doc-col {
diff --git a/docs/configuration.md b/docs/configuration.md
index b1ba3f7..7b7f5d0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -24,9 +24,86 @@ After installing espanso, the `.espanso` directory will contain the following fi
 ```
 
 The `default.yml` file contains the **main configurations** and for a basic usage, this is the only file
-you will be working with. 
+you will be working with. You can find a list of all the possible options in the [Options](#options) section. 
 
-The `user` folder is used to store more advanced user configurations, such as [Application-specific](#application-specific-config) configs.
+The `user` folder is used to store more advanced user configurations, such as [Application-specific](#application-specific-configurations) configs.
 
 The `packages` folder stores packages installed using the *package manager* and should not be directly modified
-by the user. For more information, check out the [Packages](/docs/packages) section of the documentation.
\ No newline at end of file
+by the user. For more information, check out the [Packages](/docs/packages) section of the documentation.
+
+### Application-Specific Configurations
+
+Sometimes you may need to make espanso behave **differently** in some applications. For example, you may want to have
+a different set of Matches for an application, or you may need to change the `backend` option for compatibility
+purposes.
+
+For such cases, espanso offers the **Application Specific** configurations, that is configurations that are valid
+only for some applications which match specific **filters**.
+
+Let's say you want to add some Matches for emojis, but only when using the Telegram desktop app.
+
+You can create a `telegram.yml` file in the `.espanso/user` folder, with the following content:
+
+```yml
+filter_title: "Telegram"
+
+matches:
+  - trigger: ":ok"
+    replace: "👍"
+```
+
+After restarting espanso with `espanso restart`, you are ready to test the new configuration.
+
+Navigate to Telegram and type `:ok`, you should see your emoji appear. If you then move to another application
+and try again, you should not see it!
+
+The key here is the `filter_title` option, that basically means: "If the current application contains `Telegram`
+in the title, use this configuration instead of the `default.yml` one"
+
+**Note**: app-specific configurations don't support all options, refer to the [table](#options) below to find out more.
+
+#### Available Filters
+
+espanso supports varius filters, but their support depends on the Operating System used. You can refer to this table:
+
+Filter | Description | Windows Support | MacOS Support | Linux Support
+--- | --- | --- | --- | ---
+`filter_title` | Filter based on the current Window title | Full support | Uses the App identifier instead of the Window title | Full support
+`filter_exec` | Filter based on the current application executable path | Full support | Full support | Partial support
+`filter_class` | Filter based on the current Window class | Uses the application executable path instead | Uses the App identifier instead | Full support
+
+The `filter_title`, `filter_exec` and `filter_class` filters support a full **regex** as parameter.
+
+#### Finding the right filters
+
+To make it easier to find the right filters, espanso offers the `detect` subcommand. Open a terminal and type:
+
+```
+espanso detect
+```
+
+Now, while leaving it running, move to the desired application and then come back to the terminal. You should see
+an output like:
+
+```
+Detected change, current window has properties:
+==> Title: 'Telegram (1828)'
+==> Class: 'TelegramDesktop'
+==> Executable: '/snap/telegram-desktop/953/bin/Telegram'
+```
+
+These are the parameters espanso detected for your target application, so you can now use them to create the 
+perfect filter.
+
+### Options
+
+Here's a list of all options available for the configuration file:
+
+Option | Description | Possible Values | Default | App-Specific 
+--- | --- | --- | --- | ---
+`backend` | The typing engine used. `Inject` simulate keypresses, `Clipboard` simulates a copy/paste | `Clipboard` or `Inject` | `Inject` | Yes
+`backspace_limit` | How many backspace espanso tracks to correct mispelled keywords | int | `3` | No
+`disabled` | Set the current configuration as disabled | `True`/`False` | `False` | Yes
+`parent` | The target for the current configuration file, mainly used in packages | string | `self` | Yes
+`ipc_server_port` | Windows only. Set the daemon listening port | int | `34982` | No
+`exclude_default_matches` | Used in app-specific configs, avoid parent matches | `True`/`False` | `False` | Yes
\ No newline at end of file