diff --git a/README.md b/README.md index 50a9e65..4015047 100644 --- a/README.md +++ b/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] - tldr [options] +User documentation is available at ! - Options: - - -h --help Show this screen - -v --version Show version information - -l --list List all commands in the cache - -f --render Render a specific markdown file - -o --os 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 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 +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. -## Installing +## Development -### 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! - -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: +Creating a 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: - -Screenshot of customized version - -### 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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..ae63f23 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Danilo Bargen"] +language = "en" +multilingual = false +src = "src" +title = "Tealdeer User Manual" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..6201678 --- /dev/null +++ b/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) diff --git a/docs/src/config.md b/docs/src/config.md new file mode 100644 index 0000000..3aee010 --- /dev/null +++ b/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 +``` diff --git a/docs/src/config_display.md b/docs/src/config_display.md new file mode 100644 index 0000000..6d16805 --- /dev/null +++ b/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 diff --git a/docs/src/config_style.md b/docs/src/config_style.md new file mode 100644 index 0000000..255a44b --- /dev/null +++ b/docs/src/config_style.md @@ -0,0 +1,40 @@ +# style + +Using the config file, the style (e.g. colors or underlines) can be customized. + +Screenshot of customized version + +## 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 } } diff --git a/docs/src/config_updates.md b/docs/src/config_updates.md new file mode 100644 index 0000000..ac9a59b --- /dev/null +++ b/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 + diff --git a/docs/src/deer.png b/docs/src/deer.png new file mode 100644 index 0000000..ebc9c9d Binary files /dev/null and b/docs/src/deer.png differ diff --git a/docs/src/deer.svg b/docs/src/deer.svg new file mode 100644 index 0000000..b686b4b --- /dev/null +++ b/docs/src/deer.svg @@ -0,0 +1,52 @@ + + + + + + image/svg+xml + + + + + + + + diff --git a/docs/src/installing.md b/docs/src/installing.md new file mode 100644 index 0000000..8f98b62 --- /dev/null +++ b/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` diff --git a/docs/src/intro.md b/docs/src/intro.md new file mode 100644 index 0000000..fcacfe3 --- /dev/null +++ b/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/) diff --git a/screenshot-custom.png b/docs/src/screenshot-custom.png similarity index 100% rename from screenshot-custom.png rename to docs/src/screenshot-custom.png diff --git a/docs/src/usage.md b/docs/src/usage.md new file mode 100644 index 0000000..c8fa308 --- /dev/null +++ b/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}} +``` diff --git a/src/main.rs b/src/main.rs index 532c678..cf4d130 100644 --- a/src/main.rs +++ b/src/main.rs @@ -52,42 +52,7 @@ const APP_INFO: AppInfo = AppInfo { author: NAME, }; const VERSION: &str = env!("CARGO_PKG_VERSION"); -const USAGE: &str = " -Usage: - - tldr [options] ... - tldr [options] - -Options: - - -h --help Show this screen - -v --version Show version information - -l --list List all commands in the cache - -f --render Render a specific markdown file - -o --os 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 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 USAGE: &str = include_str!("usage.docopt"); 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"; diff --git a/src/usage.docopt b/src/usage.docopt new file mode 100644 index 0000000..d2ad807 --- /dev/null +++ b/src/usage.docopt @@ -0,0 +1,34 @@ +Usage: + + tldr [options] ... + tldr [options] + +Options: + + -h --help Show this screen + -v --version Show version information + -l --list List all commands in the cache + -f --render Render a specific markdown file + -o --os 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 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