From 66255219fa65f3466bd7db275afa7db0dd494009 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 20 Dec 2021 00:43:40 +0100 Subject: [PATCH 1/3] Docs: Improve structure of config docs --- docs/src/SUMMARY.md | 6 ++--- docs/src/config.md | 49 +++++++++++++++++++++++--------------- docs/src/config_display.md | 2 +- docs/src/config_style.md | 2 +- docs/src/config_updates.md | 2 +- 5 files changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 6201678..e2455c4 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -5,6 +5,6 @@ - [Installing](./installing.md) - [Usage](./usage.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) diff --git a/docs/src/config.md b/docs/src/config.md index 79afcdf..9052210 100644 --- a/docs/src/config.md +++ b/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 +Creating the config file can be done manually or with the help of `tldr`: + + $ tldr --seed-config + 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. - -## 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. - ## 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) or +[updates](config_updates.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. diff --git a/docs/src/config_display.md b/docs/src/config_display.md index 6d16805..36d5f23 100644 --- a/docs/src/config_display.md +++ b/docs/src/config_display.md @@ -1,4 +1,4 @@ -# display +# Section: \[display\] In the `display` section you can configure the output format. diff --git a/docs/src/config_style.md b/docs/src/config_style.md index 38709ee..be2a4cc 100644 --- a/docs/src/config_style.md +++ b/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. diff --git a/docs/src/config_updates.md b/docs/src/config_updates.md index ac9a59b..5eb8f95 100644 --- a/docs/src/config_updates.md +++ b/docs/src/config_updates.md @@ -1,4 +1,4 @@ -# updates +# Section: \[updates\] ## Automatic updates From abeb5c37576d6f47b19fdd321411a24a40c12110 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 20 Dec 2021 00:48:39 +0100 Subject: [PATCH 2/3] Docs: Add directories config section --- docs/src/SUMMARY.md | 1 + docs/src/config.md | 4 ++-- docs/src/config_directories.md | 11 +++++++++++ 3 files changed, 14 insertions(+), 2 deletions(-) create mode 100644 docs/src/config_directories.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index e2455c4..eb628c2 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -8,3 +8,4 @@ - [Section: \[display\]](./config_display.md) - [Section: \[style\]](./config_style.md) - [Section: \[updates\]](./config_updates.md) + - [Section: \[directories\]](./config_directories.md) diff --git a/docs/src/config.md b/docs/src/config.md index 9052210..020687e 100644 --- a/docs/src/config.md +++ b/docs/src/config.md @@ -22,8 +22,8 @@ On Linux, this will usually be `~/.config/tealdeer/config.toml`. 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) or -[updates](config_updates.html)). +([display](config_display.html), [style](config_style.html), +[updates](config_updates.html) or [directories](config_directories.html)). ```toml [display] diff --git a/docs/src/config_directories.md b/docs/src/config_directories.md new file mode 100644 index 0000000..8340ad9 --- /dev/null +++ b/docs/src/config_directories.md @@ -0,0 +1,11 @@ +# Section: \[directories\] + +This section allows overriding some directory paths. + +## `custom_pages_dir` + +Set the directory to be used to look up custom pages. Remember to use an +absolute path. Variable expansion will not be performed on the path. + + [directories] + custom_pages_dir = "/home/myuser/custom-tldr-pages/" From ca844b35e93bb32d43ce433f650b1dbf9378891a Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 20 Dec 2021 01:04:57 +0100 Subject: [PATCH 3/3] Docs: Document custom pages and patches --- docs/src/SUMMARY.md | 1 + docs/src/config_directories.md | 5 ++-- docs/src/usage_custom_pages.md | 42 ++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 docs/src/usage_custom_pages.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index eb628c2..8aaac31 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -4,6 +4,7 @@ - [Installing](./installing.md) - [Usage](./usage.md) + - [Custom Pages](./usage_custom_pages.md) - [Configuration](./config.md) - [Section: \[display\]](./config_display.md) - [Section: \[style\]](./config_style.md) diff --git a/docs/src/config_directories.md b/docs/src/config_directories.md index 8340ad9..d894e90 100644 --- a/docs/src/config_directories.md +++ b/docs/src/config_directories.md @@ -4,8 +4,9 @@ This section allows overriding some directory paths. ## `custom_pages_dir` -Set the directory to be used to look up custom pages. Remember to use an -absolute path. Variable expansion will not be performed on the path. +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/" diff --git a/docs/src/usage_custom_pages.md b/docs/src/usage_custom_pages.md new file mode 100644 index 0000000..589479f --- /dev/null +++ b/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 +`.page` in the custom pages directory. When calling `tldr `, +your custom page will be shown instead of the upstream version in the cache. + +Path: + + $CUSTOM_PAGES_DIR/.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 `.patch`, it will be appended to existing +pages. + +Path: + + $CUSTOM_PAGES_DIR/.patch + +Example: + + ~/.local/share/tealdeer/pages/ufw.patch