1 | # tldr-node-client
|
2 |
|
3 | [![NPM version][npm-image]][npm-url]
|
4 | [![Travs CI Build Status][travis-image]][travis-url]
|
5 | [![AppVeyor CI Build status][appveyor-image]][appveyor-url]
|
6 | [![Gitter chat][gitter-image]][gitter-url]
|
7 | [![Snap Status](https://build.snapcraft.io/badge/tldr-pages/tldr-node-client.svg)](https://build.snapcraft.io/user/tldr-pages/tldr-node-client)
|
8 |
|
9 | A `Node.js` based command-line client for [tldr](https://github.com/tldr-pages/tldr).
|
10 |
|
11 | ![tldr screenshot](screenshot.png)
|
12 | *tldr-node-client's output for the `tar` page, using a custom color theme*
|
13 |
|
14 | ## Installing
|
15 |
|
16 | ```bash
|
17 | npm install -g tldr
|
18 | ```
|
19 |
|
20 | ## Install from the snap store
|
21 |
|
22 | In any of the [supported Linux distros](https://snapcraft.io/docs/core/install):
|
23 |
|
24 | ```bash
|
25 | sudo snap install tldr
|
26 | ```
|
27 |
|
28 | If you want to help testing the latest changes, and get the newer features earlier, you can install the snap from the edge channel:
|
29 |
|
30 | ```bash
|
31 | sudo snap install tldr --edge
|
32 | ```
|
33 |
|
34 | ## Usage
|
35 |
|
36 | To see tldr pages:
|
37 |
|
38 | - `tldr <command>` show examples for this command
|
39 | - `tldr <command> --os=<platform>` show command page for the given platform (`linux`, `osx`, `sunos`)
|
40 | - `tldr --search "<query>"` search all pages for the query
|
41 | - `tldr --linux <command>` show command page for Linux
|
42 | - `tldr --osx <command>` show command page for OSX
|
43 | - `tldr --sunos <command>` show command page for SunOS
|
44 | - `tldr --list` show all pages for current platform
|
45 | - `tldr --list-all` show all available pages
|
46 | - `tldr --random` show a page at random
|
47 | - `tldr --random-example` show a single random example
|
48 | - `tldr --markdown` show the original markdown format page
|
49 |
|
50 | The client caches a copy of all pages locally, in `~/.tldr`.
|
51 | There are more commands to control the local cache:
|
52 |
|
53 | - `tldr --update` download the latest pages and generate search index
|
54 | - `tldr --clear-cache` delete the entire local cache
|
55 |
|
56 | As a contributor, you might also need the following commands:
|
57 |
|
58 | - `tldr --render <path>` render a local page for testing purposes
|
59 |
|
60 | ## Configuration
|
61 |
|
62 | You can configure the `tldr` client by adding a `.tldrrc` file in your HOME directory. You can copy the contents of the `config.json` file from the repo to get the basic structure to start with, and modify it to suit your needs.
|
63 |
|
64 | The default color theme is the one named `"simple"`. You can change the theme by assigning a different value to the `"theme"` variable -- either to one of the pre-configured themes, or to a new theme that you have previously created in the `"themes"` section. Note that the colors and text effects you can choose are limited. Refer to the [chalk documentation](https://github.com/chalk/chalk#styles) for all options.
|
65 |
|
66 | ```json
|
67 | {
|
68 | "themes": {
|
69 | "ocean": {
|
70 | "commandName": "bold, cyan",
|
71 | "mainDescription": "",
|
72 | "exampleDescription": "green",
|
73 | "exampleCode": "cyan",
|
74 | "exampleToken": "dim"
|
75 | },
|
76 | "myOwnCoolTheme": {
|
77 | "commandName": "bold, red",
|
78 | "mainDescription": "underline",
|
79 | "exampleDescription": "yellow",
|
80 | "exampleCode": "underline, green",
|
81 | "exampleToken": ""
|
82 | }
|
83 | },
|
84 | "theme": "ocean"
|
85 | }
|
86 | ```
|
87 |
|
88 | If you regularly need pages for a different platform (e.g. Linux),
|
89 | you can put it in the config file:
|
90 |
|
91 | ```json
|
92 | {
|
93 | "platform": "linux"
|
94 | }
|
95 | ```
|
96 |
|
97 | The default platform value can be overwritten with command-line option:
|
98 |
|
99 | ```shell
|
100 | tldr du --os=osx
|
101 | ```
|
102 |
|
103 | As a contributor, you can also point to your own fork containing the `tldr.zip` file. The file is just a zipped version of the entire tldr repo:
|
104 |
|
105 | ```js
|
106 | {
|
107 | "repository" : "http://myrepo/assets/tldr.zip",
|
108 | }
|
109 | ```
|
110 |
|
111 | ## Command-line Autocompletion
|
112 |
|
113 | Currently we only support command-line autocompletion for zsh.
|
114 | Pull requests for other shells are most welcome!
|
115 |
|
116 | ### zsh
|
117 |
|
118 | It's easiest for
|
119 | [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh)
|
120 | users, so let's start with that.
|
121 |
|
122 | ```
|
123 | mkdir -p $ZSH_CUSTOM/plugins/tldr
|
124 | ln -s bin/autocompletion.zsh $ZSH_CUSTOM/plugins/tldr/_tldr
|
125 | ```
|
126 |
|
127 | Then add tldr to your oh-my-zsh plugins,
|
128 | usually defined in `~/.zshrc`,
|
129 | resulting in something looking like this:
|
130 |
|
131 | ```
|
132 | plugins=(git tmux tldr)
|
133 | ```
|
134 |
|
135 | Fret not regular zsh user!
|
136 | Copy or symlink `bin/autocompletion.zsh` to
|
137 | `my/completions/_tldr`
|
138 | (note the filename).
|
139 | Then add the containing directory to your fpath:
|
140 | ```
|
141 | fpath = (my/completions $fpath)
|
142 | ```
|
143 |
|
144 | ## FAQ
|
145 |
|
146 | #### Installation Issues
|
147 |
|
148 | - If you are trying to install as non-root user (`npm install -g tldr`) and get something like -
|
149 |
|
150 | ```
|
151 | Error: EACCES: permission denied, access '/usr/local/lib/node_modules/tldr'
|
152 | ```
|
153 |
|
154 | Then most probably your npm's default installation directory has improper permissions. You can resolve it by clicking [here](https://docs.npmjs.com/getting-started/fixing-npm-permissions)
|
155 |
|
156 | - If you are trying to install as a root user (`sudo npm install -g tldr`) and get something like -
|
157 |
|
158 | ```
|
159 | as root ->
|
160 | gyp WARN EACCES attempting to reinstall using temporary dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp"
|
161 | gyp WARN EACCES user "root" does not have permission to access the dev dir "/usr/local/lib/node_modules/tldr/node_modules/webworker-threads/.node-gyp/8.9.1"
|
162 | ```
|
163 |
|
164 | You need to add the option `--unsafe-perm` to your command. This is because when npm goes to the postinstall step, it downgrades the permission levels to "nobody". Probably you should fix your installation directory permissions and install as a non-root user in the first place.
|
165 |
|
166 | - If you see an error related to `webworker-threads` like -
|
167 |
|
168 | ```
|
169 | /usr/local/lib/node_modules/tldr/node_modules/natural/lib/natural/classifiers/classifier.js:32
|
170 | if (e.code !== 'MODULE_NOT_FOUND') throw e;
|
171 | ```
|
172 | Most probably you need to reinstall `node-gyp` and `webworker-threads`. Try this -
|
173 |
|
174 | ```
|
175 | sudo -H npm uninstall -g tldr
|
176 | sudo -H npm uninstall -g webworker-threads
|
177 | npm install -g node-gyp
|
178 | npm install -g webworker-threads
|
179 | npm install -g tldr
|
180 | ```
|
181 | For further context, take a look at this [issue](https://github.com/tldr-pages/tldr-node-client/issues/179)
|
182 |
|
183 | #### Colors under Cygwin
|
184 |
|
185 | Colors can't be shown under Mintty or PuTTY, because the dependency `colors.js` has a bug.
|
186 | Please show support to [this pull request](https://github.com/Marak/colors.js/pull/154), so it can be merged.
|
187 |
|
188 | Meanwhile, you can do one of the following to fix this issue:
|
189 |
|
190 | * Add the following script to your shell's rc file (`.zshrc`, `.bashrc`, etc.): (RECOMMENDED)
|
191 |
|
192 | ```bash
|
193 | tldr_path="$(which tldr)"
|
194 | function tldr() {
|
195 | eval "$tldr_path" $@ "--color"
|
196 | }
|
197 | ```
|
198 | * Add `alias tldr="tldr --color=true"` to your shell's rc file.
|
199 | * Prepend `process.stdout.isTTY = true;` to `tldr.js` (NOT RECOMMENDED)
|
200 | * Fix `colors.js`'s logic (NOT RECOMMENDED)
|
201 | * Go to `%appdata%\npm\node_modules\tldr\node_modules\colors\lib\system\`
|
202 | * Overwrite `supports-colors.js` with [supports-colors.js](https://raw.githubusercontent.com/RShadowhand/colors.js/master/lib/system/supports-colors.js) from my repo.
|
203 | * Use `CMD.exe`.
|
204 |
|
205 | ## Contributing
|
206 |
|
207 | Contribution are most welcome!
|
208 | Have a look [over here](https://github.com/tldr-pages/tldr-node-client/blob/master/.github/CONTRIBUTING.md)
|
209 | for a few rough guidelines.
|
210 |
|
211 | [npm-url]: https://www.npmjs.com/package/tldr
|
212 | [npm-image]: https://img.shields.io/npm/v/tldr.svg
|
213 |
|
214 | [travis-url]: https://travis-ci.org/tldr-pages/tldr-node-client
|
215 | [travis-image]: https://img.shields.io/travis/tldr-pages/tldr-node-client.svg?label=linux
|
216 |
|
217 | [appveyor-image]: https://img.shields.io/appveyor/ci/igorshubovych/tldr-node-client-bnut4.svg?label=windows
|
218 | [appveyor-url]: https://ci.appveyor.com/project/igorshubovych/tldr-node-client-bnut4
|
219 |
|
220 | [dep-url]: https://david-dm.org/tldr-pages/tldr-node-client
|
221 | [dep-image]: https://david-dm.org/tldr-pages/tldr-node-client.svg?theme=shields.io
|
222 |
|
223 | [dev-dep-url]: https://david-dm.org/tldr-pages/tldr-node-client#info=devDependencies
|
224 | [dev-dep-image]: https://david-dm.org/tldr-pages/tldr-node-client/dev-status.svg?theme=shields.io
|
225 |
|
226 | [gitter-url]: https://gitter.im/tldr-pages/tldr
|
227 | [gitter-image]: https://badges.gitter.im/tldr-pages/tldr.png
|