| Crate | CI (Linux/macOS/Windows) |
|---|---|
 |
 |
A very fast implementation of tldr in Rust: Simplified, example based and community-driven man pages.
If you pronounce "tldr" in English, it sounds somewhat like "tealdeer". Hence the project name :)
In case you're in a hurry and just want to quickly try tealdeer, you can find static binaries on the GitHub releases page!
User documentation is available at https://dbrgn.github.io/tealdeer/!
The docs are generated using mdbook.
They can be edited through the markdown files in the docs/src/ directory.
High level project goals:
- Download and cache pages
- Don't require a network connection for anything besides updating the cache
- Command line interface similar or equivalent to the NodeJS client
- Be fast
A tool like tldr should be as frictionless as possible to use. It should be
easy to invoke (just tldr tar, not using another subcommand like tldr find tar) and it should show the output as fast as possible.
tealdeer reaches these goals. During a (highly non-scientific) test (see
#38 for details), I tested the
invocation speed of tldr <command> for a few of the existing clients:
| Client | Times (ms) | Avg of 5 (ms) |
|---|---|---|
| Tealdeer | 15/11/5/5/11 |
9.4 (100%) |
| C client | 11/5/12/11/15 |
10.8 (115%) |
| Bash client | 15/19/22/25/24 |
21.0 (223%) |
| Go client by k3mist | 98/96/100/95/101 |
98.8 (1'051%) |
| Python client | 152/148/151/158/140 |
149.8 (1'594%) |
| NodeJS client | 169/171/170/170/170 |
170.0 (1'809%) |
tealdeer was the winner here, although the C client and the Bash client are in the same speed class. Interpreted languages are clearly much slower to invoke, a delay of 170 milliseconds is definitely noticeable and increases friction for the user.
These are the clients I tried but failed to compile or run: Haskell client, Ruby client, Perl client, Go client by anoopengineer, PHP client.
Creating a 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
To run tests:
$ cargo test
To run lints:
$ rustup component add clippy
$ cargo clean && cargo clippy
Tealdeer will not bump the MSRV requirement in patch versions, but it may increase it in minor versions. The reason is that many important libraries (e.g. the Tokio ecosystem, which is a dependency of reqwest, which is used for downloading the cache) do not follow a static MSRV, but instead follow a "stable + last n releases" approach. Trying to guarantee the same MSRV across all minor releases would be a futile attempt.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Thanks to @SShrike for coming up with the name "tealdeer"!