Add mdbook documentation

README.md

@@ -1,6 +1,6 @@
 # tealdeer
 
-![teal deer](deer.png)
+![teal deer](docs/src/deer.png)
 
 |Crate|CI (Linux/macOS/Windows)|
 |:---:|:---:|
@@ -56,83 +56,17 @@ These are the clients I tried but failed to compile or run:
 [PHP client](https://github.com/BrainMaestro/tldr-php).
 
 
-## Usage
+## Docs (Installing, Usage, Configuration)
 
-    tldr [options] <command>
+User documentation is available at <https://dbrgn.github.io/tealdeer/>!
-    tldr [options]
 
-    Options:
+The docs are generated using [mdbook](https://rust-lang.github.io/mdBook/index.html).
-
+They can be edited through the markdown files in the `docs/src/` directory.
-        -h --help            Show this screen
-        -v --version         Show version information
-        -l --list            List all commands in the cache
-        -f --render <file>   Render a specific markdown file
-        -o --os <type>       Override the operating system [linux, osx, sunos, windows]
-        -u --update          Update the local cache
-        -c --clear-cache     Clear the local cache
-        -p --pager           Use a pager to page output
-        -m --markdown        Display the raw markdown instead of rendering it
-        -q --quiet           Suppress informational messages
-        --config-path        Show config file path
-        --seed-config        Create a basic config
-        --color <when>       Control when to use color [always, auto, never] [default: auto]
-
-    Examples:
-
-        $ tldr tar
-        $ tldr --list
-
-    To control the cache:
-
-        $ tldr --update
-        $ tldr --clear-cache
-
-    To render a local file (for testing):
-
-        $ tldr --render /path/to/file.md
 
 
-## Installing
+## Development
 
-### Static Binaries (Linux)
+Creating a debug build with logging enabled:
-
-Static binary builds (currently for Linux only) are available on the
-[GitHub releases page](https://github.com/dbrgn/tealdeer/releases).
-Simply download the binary for your platform and run it!
-
-Builds for other platforms are planned.
-
-### Cargo Install (any platform)
-
-Build and install the tool via cargo...
-
-    $ cargo install tealdeer
-
-*(Note: You might need to install OpenSSL development headers, otherwise you get
-a "failed to run custom build command for openssl-sys" error message. The
-package is called `libssl-dev` on Ubuntu.)*
-
-### From Package Manager
-
-tealdeer has been added to a few package managers:
-
-- Arch Linux AUR: [`tealdeer`](https://aur.archlinux.org/packages/tealdeer/),
-  [`tealdeer-bin`](https://aur.archlinux.org/packages/tealdeer-bin/) or
-  [`tealdeer-git`](https://aur.archlinux.org/packages/tealdeer-git/)
-- Fedora: [`tealdeer`](https://src.fedoraproject.org/rpms/rust-tealdeer)
-- FreeBSD: [`sysutils/tealdeer`](https://www.freshports.org/sysutils/tealdeer/)
-- macOS Homebrew: [`tealdeer`](https://formulae.brew.sh/formula/tealdeer)
-- NetBSD: [`sysutils/tealdeer`](https://pkgsrc.se/sysutils/tealdeer)
-- Nix: [`tealdeer`](https://nixos.org/nixos/packages.html#tealdeer)
-- openSUSE: [`tealdeer`](https://software.opensuse.org/package/tealdeer?search_term=tealdeer)
-- Solus: [`tealdeer`](https://packages.getsol.us/shannon/t/tealdeer/)
-- Void Linux: [`tealdeer`](https://github.com/void-linux/void-packages/tree/master/srcpkgs/tealdeer)
-
-### From Source (any platform)
-
-tealdeer requires at least Rust 1.39.
-
-Debug build with logging enabled:
 
     $ cargo build --features logging
 
@@ -144,110 +78,6 @@ To enable the log output, set the `RUST_LOG` env variable:
 
     $ export RUST_LOG=tldr=debug
 
-
-## Configuration
-
-The tldr command can be customized with a config file called `config.toml`.
-Creating the config file can be done manually or with the help of tldr:
-
-    $ tldr --seed-config
-
-The configuration file path follows OS conventions. It can be queried with the following command:
-
-    $ tldr --config-path
-
-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.
-
-### Style
-
-Using the config file, the style (e.g. colors or underlines) can be customized.
-
-Possible styles:
-
-- `description`: The initial description text
-- `command_name`: The command name as part of the example code
-- `example_text`: The text that describes an example
-- `example_code`: The example itself, except the `command_name` and `example_variable`
-- `example_variable`: The variables in the example
-
-Currently supported attributes:
-
-- `foreground` (color string, ANSI code, or RGB, see below)
-- `background` (color string, ANSI code, or RGB, see below)
-- `underline` (`true` or `false`)
-- `bold` (`true` or `false`)
-
-Colors can be specified in one of three ways:
-
-- Color string (`black`, `red`, `green`, `yellow`, `blue`, `purple`, `cyan`, `white`)
-- 256 color ANSI code (e.g. `foreground = { ansi = 4 }`)
-- 24-bit RGB color (e.g. `background = { rgb = { r = 255, g = 255, b = 255 } }`)
-
-Example customization:
-
-<img src="screenshot-custom.png" alt="Screenshot of customized version" width="600">
-
-### Display
-
-In the `display` section you can configure the output format.
-
-#### `use_pager`
-
-Specifies whether the pager should be used by default or not (default `false`).
-
-    [display]
-    use_pager = true
-
-When enabled, `less -R` is used as pager. To override the pager command used,
-set the `PAGER` environment variable.
-
-NOTE: This feature is not available on Windows.
-
-#### `compact`
-
-Set this to enforce more compact output, where empty lines are stripped out
-(default `false`).
-
-    [display]
-    compact = true
-
-
-### Automatic updates
-
-tealdeer can refresh the cache automatically when it is outdated. This
-behavior can be configured in the `updates` section and is disabled by
-default.
-
-#### `auto_update`
-
-Specifies whether the auto-update feature should be enabled (defaults to
-`false`).
-
-    [updates]
-    auto_update = true
-
-#### `auto_update_interval_hours`
-
-Duration, since the last cache update, after which the cache will be
-refreshed (defaults to 720 hours). This parameter is ignored if `auto_update`
-is set to `false`.
-
-    [updates]
-    auto_update = true
-    auto_update_interval_hours = 24
-
-
-## Autocompletion
-
-- *Bash*: copy `bash_tealdeer` to `/usr/share/bash-completion/completions/tldr`
-- *Fish*: copy `fish_tealdeer` to `~/.config/fish/completions/tldr.fish`
-- *Zsh*: copy `zsh_tealdeer` to `/usr/share/zsh/site-functions/_tldr`
-
-
-## Development
-
 To run tests:
 
     $ cargo test

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Danilo Bargen"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Tealdeer User Manual"

docs/src/SUMMARY.md

@@ -0,0 +1,10 @@
+# Summary
+
+[Introduction](./intro.md)
+
+- [Installing](./installing.md)
+- [Usage](./usage.md)
+- [Configuration](./config.md)
+  - [display](./config_display.md)
+  - [style](./config_style.md)
+  - [updates](./config_updates.md)

docs/src/config.md

@@ -0,0 +1,43 @@
+# 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`:
+
+    $ tldr --seed-config
+
+The configuration file path follows OS conventions. It can be queried with the
+following command:
+
+    $ tldr --config-path
+
+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.
+
+## Example
+
+```toml
+[display]
+compact = false
+use_pager = true
+
+[style.command_name]
+foreground = "red"
+
+[style.example_text]
+foreground = "green"
+
+[style.example_code]
+foreground = "blue"
+
+[style.example_variable]
+foreground = "blue"
+underline = true
+
+[updates]
+auto_update = true
+```

docs/src/config_display.md

@@ -0,0 +1,23 @@
+# display
+
+In the `display` section you can configure the output format.
+
+## `use_pager`
+
+Specifies whether the pager should be used by default or not (default `false`).
+
+    [display]
+    use_pager = true
+
+When enabled, `less -R` is used as pager. To override the pager command used,
+set the `PAGER` environment variable.
+
+NOTE: This feature is not available on Windows.
+
+## `compact`
+
+Set this to enforce more compact output, where empty lines are stripped out
+(default `false`).
+
+    [display]
+    compact = true

docs/src/config_style.md

@@ -0,0 +1,40 @@
+# style
+
+Using the config file, the style (e.g. colors or underlines) can be customized.
+
+<img src="screenshot-custom.png" alt="Screenshot of customized version" width="600">
+
+## Style Targets
+
+- `description`: The initial description text
+- `command_name`: The command name as part of the example code
+- `example_text`: The text that describes an example
+- `example_code`: The example itself (except the `command_name` and `example_variable`)
+- `example_variable`: The variables in the example
+
+## Attributes
+
+- `foreground` (color string, ANSI code, or RGB, see below)
+- `background` (color string, ANSI code, or RGB, see below)
+- `underline` (`true` or `false`)
+- `bold` (`true` or `false`)
+
+Colors can be specified in one of three ways:
+
+- Color string (`black`, `red`, `green`, `yellow`, `blue`, `purple`, `cyan`, `white`):
+
+  Example:
+
+      foreground = "green"
+
+- 256 color ANSI code (*Tealdeer v1.5.0+*)
+
+  Example:
+
+      foreground = { ansi = 4 }
+
+- 24-bit RGB color (*Tealdeer v1.5.0+*)
+
+  Example:
+
+      background = { rgb = { r = 255, g = 255, b = 255 } }

docs/src/config_updates.md

@@ -0,0 +1,26 @@
+# updates
+
+## Automatic updates
+
+tealdeer can refresh the cache automatically when it is outdated. This
+behavior can be configured in the `updates` section and is disabled by
+default.
+
+### `auto_update`
+
+Specifies whether the auto-update feature should be enabled (defaults to
+`false`).
+
+    [updates]
+    auto_update = true
+
+### `auto_update_interval_hours`
+
+Duration, since the last cache update, after which the cache will be
+refreshed (defaults to 720 hours). This parameter is ignored if `auto_update`
+is set to `false`.
+
+    [updates]
+    auto_update = true
+    auto_update_interval_hours = 24
+

docs/src/installing.md

@@ -0,0 +1,63 @@
+# Installing
+
+There are a few different ways to install Tealdeer:
+
+- Through [packet managers](#packet-managers)
+- Through [static binaries](#static-binaries-linux)
+- Through [cargo install](#through-cargo-install)
+- By [building from source](#build-from-source)
+
+Additionally, when not using system packages, you can [manually install
+autocompletions](#autocompletion).
+
+## Packet Managers
+
+Tealdeer has been added to a few package managers:
+
+- Arch Linux AUR: [`tealdeer`](https://aur.archlinux.org/packages/tealdeer/),
+  [`tealdeer-bin`](https://aur.archlinux.org/packages/tealdeer-bin/) or
+  [`tealdeer-git`](https://aur.archlinux.org/packages/tealdeer-git/)
+- Fedora: [`tealdeer`](https://src.fedoraproject.org/rpms/rust-tealdeer)
+- FreeBSD: [`sysutils/tealdeer`](https://www.freshports.org/sysutils/tealdeer/)
+- macOS Homebrew: [`tealdeer`](https://formulae.brew.sh/formula/tealdeer)
+- NetBSD: [`sysutils/tealdeer`](https://pkgsrc.se/sysutils/tealdeer)
+- Nix: [`tealdeer`](https://nixos.org/nixos/packages.html#tealdeer)
+- openSUSE: [`tealdeer`](https://software.opensuse.org/package/tealdeer?search_term=tealdeer)
+- Solus: [`tealdeer`](https://packages.getsol.us/shannon/t/tealdeer/)
+- Void Linux: [`tealdeer`](https://github.com/void-linux/void-packages/tree/master/srcpkgs/tealdeer)
+
+## Static Binaries (Linux)
+
+Static binary builds (currently for Linux only) are available on the
+[GitHub releases page](https://github.com/dbrgn/tealdeer/releases).
+Simply download the binary for your platform and run it!
+
+## Through `cargo install`
+
+Build and install the tool via cargo...
+
+    $ cargo install tealdeer
+
+*(Note: You might need to install OpenSSL development headers, otherwise you get
+a "failed to run custom build command for openssl-sys" error message. The
+package is called `libssl-dev` on Ubuntu.)*
+
+## Build From Source
+
+Debug build with logging enabled:
+
+    $ cargo build --features logging
+
+Release build without logging:
+
+    $ cargo build --release
+
+To enable the log output, set the `RUST_LOG` env variable:
+
+    $ export RUST_LOG=tldr=debug
+
+## Autocompletion
+
+- *Bash*: copy `bash_tealdeer` to `/usr/share/bash-completion/completions/tldr`
+- *Fish*: copy `fish_tealdeer` to `~/.config/fish/completions/tldr.fish`
+- *Zsh*: copy `zsh_tealdeer` to `/usr/share/zsh/site-functions/_tldr`

docs/src/intro.md

@@ -0,0 +1,13 @@
+# Tealdeer: Introduction
+
+![teal deer](deer.png)
+
+Tealdeer very fast implementation of [tldr](https://github.com/tldr-pages/tldr)
+in Rust: Simplified, example based and community-driven man pages.
+
+This documentation shows how to install, use and configure Tealdeer.
+
+## Links
+
+- [GitHub Project Page](https://github.com/dbrgn/tealdeer)
+- [TLDR Pages Project](https://tldr.sh/)

docs/src/usage.md

@@ -0,0 +1,9 @@
+# Usage
+
+Tealdeer is straightforward to use, through the binary named `tldr`.
+
+You can view the available options using `tldr --help`:
+
+```
+{{#include ../../src/usage.docopt}}
+```

src/main.rs

@@ -52,42 +52,7 @@ const APP_INFO: AppInfo = AppInfo {
     author: NAME,
 };
 const VERSION: &str = env!("CARGO_PKG_VERSION");
-const USAGE: &str = "
+const USAGE: &str = include_str!("usage.docopt");
-Usage:
-
-    tldr [options] <command>...
-    tldr [options]
-
-Options:
-
-    -h --help           Show this screen
-    -v --version        Show version information
-    -l --list           List all commands in the cache
-    -f --render <file>  Render a specific markdown file
-    -o --os <type>      Override the operating system [linux, osx, sunos, windows]
-    -u --update         Update the local cache
-    -c --clear-cache    Clear the local cache
-    -p --pager          Use a pager to page output
-    -m --markdown       Display the raw markdown instead of rendering it
-    -q --quiet          Suppress informational messages
-    --config-path       Show config file path
-    --seed-config       Create a basic config
-    --color <when>      Control when to use color [always, auto, never] [default: auto]
-
-Examples:
-
-    $ tldr tar
-    $ tldr --list
-
-To control the cache:
-
-    $ tldr --update
-    $ tldr --clear-cache
-
-To render a local file (for testing):
-
-    $ tldr --render /path/to/file.md
-";
 const ARCHIVE_URL: &str = "https://github.com/tldr-pages/tldr/archive/master.tar.gz";
 #[cfg(not(target_os = "windows"))]
 const PAGER_COMMAND: &str = "less -R";

src/usage.docopt

@@ -0,0 +1,34 @@
+Usage:
+
+    tldr [options] <command>...
+    tldr [options]
+
+Options:
+
+    -h --help           Show this screen
+    -v --version        Show version information
+    -l --list           List all commands in the cache
+    -f --render <file>  Render a specific markdown file
+    -o --os <type>      Override the operating system [linux, osx, sunos, windows]
+    -u --update         Update the local cache
+    -c --clear-cache    Clear the local cache
+    -p --pager          Use a pager to page output
+    -m --markdown       Display the raw markdown instead of rendering it
+    -q --quiet          Suppress informational messages
+    --config-path       Show config file path
+    --seed-config       Create a basic config
+    --color <when>      Control when to use color [always, auto, never] [default: auto]
+
+Examples:
+
+    $ tldr tar
+    $ tldr --list
+
+To control the cache:
+
+    $ tldr --update
+    $ tldr --clear-cache
+
+To render a local file (for testing):
+
+    $ tldr --render /path/to/file.md