tldrx 0.2.0

A tldr pages client support private pages.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

<h1>TLDRx</h1>

<p>
  <a href="https://github.com/tldrx/tldrx/actions/workflows/ci.yml"><img alt="GitHub CI" src="https://github.com/tldrx/tldrx/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/tldrx/tldrx#license"><img alt="License" src="https://img.shields.io/crates/l/tldrx"></a>
  <a href="https://crates.io/crates/tldrx"><img alt="License" src="https://img.shields.io/crates/v/tldrx"></a>
</p>

<p>English | <a href="README.zh.md">简体中文</a></p>

<p>
  <img src="docs/screenshot.png" alt="screenshot" width="582">
</p>


## Features

- [x] Support private tldr pages repo. 
- [x] Support editing private tldr pages.
- [x] Show pages with platform info attached.
- [x] Adheres to [tldr-pages client specification](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md).[^1]
- [x] Offline caching official tldr pages repo.
- [x] Configurable official tldr pages archive download link.
- [x] Honor `HTTP_PROXY` and `HTTPS_PROXY` system proxies (handy for regulation area).
- [x] Advanced configuration: color style, platform, editor...
- [x] Support [new tldr pages syntax](https://github.com/tldr-pages/tldr/pull/958).[^2]


## Usages

Show pages for `git commit`:

    tldrx git commit

Update local cache(Required for the first time before showing official pages):

    tldrx --update

Edit or create private page for `git commit`:

    tldrx -e git commit

For more:

    tldrx --help


## Installation

Assume you have rust cargo installed:

    cargo install tldrx

## Benchmarks

Benchmarked in a Docker container([Dockerfile](benches/Dockerfile)) on a GitHub Acions machine([2C-7GB-SSD]) 
using `hyperfine` with 100 round against each client. 

| Client [2022-10-05]                                          | Build Flags      |  Mean [ms] | Min [ms] | Max [ms] |    Relative |
| :----------------------------------------------------------- | :--------------- | ---------: | -------: | -------: | ----------: |
| [outfieldr](https://gitlab.com/ve-nt/outfieldr)              | `-Drelease-safe` | 23.0 ± 2.6 |     18.5 |     36.6 |        1.00 |
| [tldrx](https://github.com/tldrx/tldrx)                      | `--release`      | 30.2 ± 3.0 |     25.5 |     43.0 | 1.32 ± 0.20 |
| [tealdeer](https://github.com/dbrgn/tealdeer)                | `--release`      | 32.9 ± 3.5 |     27.3 |     45.4 | 1.43 ± 0.22 |
| [tldr c client](https://github.com/tldr-pages/tldr-c-client) | `-O3`            | 76.8 ± 5.8 |     63.8 |    106.4 | 3.34 ± 0.45 |

P.S. Studies shows that response within `100ms` time frame human brain would treat it as an instantaneous reaction[^3][^4].
Recommendation here is chose a client base on the provided features that suits you while the response time is within `100ms`.
If you want more performance, build `tldrx` as a static binary that would reduce the dynamic library load time.



## Configuration

The location of the configuration file `.tldrxrc` varies by platform

- Linux `~/.tldrxrc`
- MacOS `~/.tldrxrc`
- Windows `%USERPROFILE%\.tldrxrc`

Create one if not there.

### Template `.tldrxrc` 

- `[-]` option Optional.
- `<+>` option Required only if that feature you want.

```toml

# [-] Path to cache official tldr-pages
official_pages_dir = "/path/to/official/tldr-pages"

# <+> Path to private tldr-pages
private_pages_dir = "/path/to/private/tldr-pages"

# [-] Show pages for the given platform. Option: [osx | linux | ...]
platform = "linux"

# [-] Colorlize the output pages Choice: [auto | on | off]
sytled = "auto"

# [-] Editor to edit private tldr-pages
editor = "vi"

```


## License

This project is dual-licensed under [MIT](LICENSE-MIT) license and [MulanPSL-2.0](LICENSE-MulanPSL) license.
You can freely choose one or the other that suits you.



[^1]: Use `tldrx` instead of `tldr`.

[^2]: The new syntax for tldr-pages is an experimental RFC.

[^3]: https://www.nngroup.com/articles/response-times-3-important-limits
[^4]: https://en.wikipedia.org/wiki/Time_perception


[2C-7GB-SSD]: https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources
[2022-10-05]: https://github.com/tldrx/tldrx/actions/runs/3188985781/jobs/5202273436