Skip to content

Latest commit

 

History

History
132 lines (88 loc) · 5.37 KB

README.md

File metadata and controls

132 lines (88 loc) · 5.37 KB
Raw

tealdeer

teal deer

Crate CI (Linux/macOS/Windows)
Crates.io GitHub CI

A very fast implementation of tldr in Rust: Simplified, example based and community-driven man pages.

Screenshot of tldr command

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!

Docs (Installing, Usage, Configuration)

User documentation is available at https://tealdeer-rs.github.io/tealdeer/!

The docs are generated using mdbook. They can be edited through the markdown files in the docs/src/ directory.

Goals

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
  • Comply with the tldr client specification
  • Advanced highlighting and configuration
  • Be fast

A tool like tldr should be as frictionless as possible to use and show the output as fast as possible.

We think that tealdeer reaches these goals. We put together a (more or less) reproducible benchmark that compiles a handful of clients from source and measures the execution times on a cold disk cache. The benchmarking is run in a Docker container using sharkdp's hyperfine (Dockerfile).

Client (50 runs, 17.10.2021) Programming Language Mean in ms Deviation in ms Comments
outfieldr Zig 9.1 0.5 no user configuration
tealdeer Rust 13.2 0.5
fast-tldr Haskell 17.0 0.6 no example highlighting
tldr-hs Haskell 25.1 0.5 no example highlighting
tldr-bash Bash 30.0 0.8
tldr-c C 38.4 1.0
tldr-python-client Python 87.0 2.4
tldr-node-client JavaScript / NodeJS 407.1 12.9

As you can see, tealdeer is one of the fastest of the tested clients. However, we strive for useful features and code quality over raw performance, even if that means that we don't come out on top in this friendly competition. That said, we are still optimizing the code, for example when the outfieldr developers suggested to switch to a native TLS implementation instead of the native libraries.

Development

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

MSRV (Minimally Supported Rust Version)

When publishing a tealdeer release, the Rust version required to build it should be stable for at least a month.

License

Licensed under either of

Contribution

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 @severen for coming up with the name "tealdeer"!