Merge pull request #237 from dbrgn/improved-docs

Improve docs.

Fixes #235, refs #218.

docs/src/SUMMARY.md

@@ -4,7 +4,9 @@
 
 - [Installing](./installing.md)
 - [Usage](./usage.md)
+  - [Custom Pages](./usage_custom_pages.md)
 - [Configuration](./config.md)
-  - [display](./config_display.md)
-  - [style](./config_style.md)
-  - [updates](./config_updates.md)
+  - [Section: \[display\]](./config_display.md)
+  - [Section: \[style\]](./config_style.md)
+  - [Section: \[updates\]](./config_updates.md)
+  - [Section: \[directories\]](./config_directories.md)

docs/src/config.md

@@ -1,33 +1,30 @@
 # Configuration
 
-Tealdeer can be customized with a config file called `config.toml`.  Creating
-the config file can be done manually or with the help of `tldr`:
+Tealdeer can be customized with a config file in [TOML
+format](https://toml.io/) called `config.toml`.
 
-    $ tldr --seed-config
+## Configfile Path
 
-The configuration file path follows OS conventions. It can be queried with the
-following command:
+The configuration file path follows OS conventions (e.g.
+`$XDG_CONFIG_HOME/tealdeer/config.toml` on Linux). The paths can be queried
+with the following command:
 
     $ tldr --show-paths
 
-On Linux, this will usually be `~/.config/tealdeer/config.toml`.
-
-## Override Config Directory
-
-The directory where the configuration file resides may be overwritten by the
-environment variable `TEALDEER_CONFIG_DIR`. Remember to use an absolute path.
-Variable expansion will not be performed on the path.
+Creating the config file can be done manually or with the help of `tldr`:
 
-## Override Cache Directory
+    $ tldr --seed-config
 
-Similarly, the cache directory where the pages are downloaded to, also follows
-OS conventions. On Linux, it will usually be at `~/.cache/tealdeer/`. The path
-can be overwritten using the environment variable `TEALDEER_CACHE_DIR`.
-Remember to use an absolute path. Variable expansion will not be performed on
-the path.
+On Linux, this will usually be `~/.config/tealdeer/config.toml`.
 
 ## Config Example
 
+Here's an example configuration file. Note that this example does not contain
+all possible config options. For details on the things that can be configured,
+please refer to the subsections of this documentation page
+([display](config_display.html), [style](config_style.html),
+[updates](config_updates.html) or [directories](config_directories.html)).
+
 ```toml
 [display]
 compact = false
@@ -49,3 +46,17 @@ underline = true
 [updates]
 auto_update = true
 ```
+
+## Override Config Directory
+
+The directory where the configuration file resides may be overwritten by the
+environment variable `TEALDEER_CONFIG_DIR`. Remember to use an absolute path.
+Variable expansion will not be performed on the path.
+
+## Override Cache Directory
+
+Similarly, the cache directory where the pages are downloaded to, also follows
+OS conventions. On Linux, it will usually be at `~/.cache/tealdeer/`. The path
+can be overwritten using the environment variable `TEALDEER_CACHE_DIR`.
+Remember to use an absolute path. Variable expansion will not be performed on
+the path.

docs/src/config_directories.md

@@ -0,0 +1,12 @@
+# Section: \[directories\]
+
+This section allows overriding some directory paths.
+
+## `custom_pages_dir`
+
+Set the directory to be used to look up [custom
+pages](usage_custom_pages.html). Remember to use an absolute path. Variable
+expansion will not be performed on the path.
+
+    [directories]
+    custom_pages_dir = "/home/myuser/custom-tldr-pages/"

docs/src/config_display.md

@@ -1,4 +1,4 @@
-# display
+# Section: \[display\]
 
 In the `display` section you can configure the output format.
 

docs/src/config_style.md

@@ -1,4 +1,4 @@
-# style
+# Section: \[style\]
 
 Using the config file, the style (e.g. colors or underlines) can be customized.
 

docs/src/config_updates.md

@@ -1,4 +1,4 @@
-# updates
+# Section: \[updates\]
 
 ## Automatic updates
 

docs/src/usage_custom_pages.md

@@ -0,0 +1,42 @@
+# Custom Pages and Patches
+
+Tealdeer allows creating new custom pages, overriding existing pages as well as
+extending existing pages.
+
+The directory, where these custom pages and patches can be placed, follows OS
+conventions. On Linux, for example, the default location is
+`~/.local/share/tealdeer/pages/`. To print the path used on your system, simply
+run `tldr --show-paths`.
+
+The custom pages directory can be [overridden by the config
+file](config_directories.html).
+
+## Custom Pages
+
+To document internal command line tools, or if you want to replace an existing
+tldr page with one that's better suited for you, place a file with the name
+`<command>.page` in the custom pages directory. When calling `tldr <command>`,
+your custom page will be shown instead of the upstream version in the cache.
+
+Path:
+
+    $CUSTOM_PAGES_DIR/<command>.page
+
+Example:
+
+    ~/.local/share/tealdeer/pages/ufw.page
+
+## Custom Patches
+
+Sometimes you don't want to fully replace an existing upstream page, but just
+want to extend it with your own examples that you frequently need. In this
+case, use a file called `<command>.patch`, it will be appended to existing
+pages.
+
+Path:
+
+    $CUSTOM_PAGES_DIR/<command>.patch
+
+Example:
+
+    ~/.local/share/tealdeer/pages/ufw.patch