lord63/tldr.py

A python client for tldr: simplified and community-driven man pages.

tldr.py

Yet another python client for tldr.

Intro

tldr.py is a python client for tldr: simplified and community-driven man pages. Instead of the long man pages:

tldr will give you several simple yet powerful examples:

The command examples are not good? Don't worry, you can set up your own 'tldr'! They are just markdown files and you can modify them at your ease. Don't forget to Share them with the community!

One more thing, tldr is just a simple version for the man page, it's NOT an alternative. Sometimes, you should read the man pages patiently ;)

Features highlight

• use local file, fast.
• support custom the output color.
• support fetch the latest tldr pages.
• support rebuild the index.

Install

$ (sudo) pip install tldr.py

Usage

Initialize with script

$ curl -s https://raw.githubusercontent.com/lord63/tldr.py/master/install.sh | bash

Or you can initialize by hand

• firstly, clone the tldr repo to somewhere(e.g. ~/code/tldr). We will use it when we look for a command usage.

  $ cd ~/code
  $ git clone https://github.com/tldr-pages/tldr.git
  

• then, init the configuration file, the default location for the configuration file is your home directory, you can use the TLDR_CONFIG_DIR environment variable to point it to another folder(e.g. $HOME/.config)

  $ tldr init
  Input the tldr repo path: (e.g. /home/lord63/code/tldr/)
  Input your platform(linux, osx or sunos): (e.g. linux)
  Initializing the config file at ~/.tldrrc
  

and you configuration file should look like this:

colors:
   command: cyan
   description: blue
   usage: green
platform: linux
repo_directory: /home/lord63/code/tldr

Don't worry about the colors option, it is for the output when you look for a command, you can custom it by yourself.(Note that the color should be in ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'])

• finally, build the index. Tldr.py will find the command via the index.json. After a new fresh clone or when you add some new pages, remember to rebuild the index.

  $ tldr reindex
  Rebuild the index.
  

Use tldr

look for a command usage:

$ tldr find {{command}}

check for updates(so that we can get the latest man pages):

$ tldr update

rebuild the index.json after you add some new pages:

$ tldr reindex

locate the command man page:

$ tldr locate {{command}}

Or you can use tldr --help to get the help message.

FAQ

Q: I want to add some custom command usages to a command, how to do it?

A: Find the location of the command page; add the command usages; done.

Q: I want to add some custom command pages, how?

A: Add the command pages to the right folder(e.g. /tldrrepo/pages/linux); rebuild the index; done.

Q: I want a short command like tldr COMMAND, not tldr find COMMAND.

A: I'm afraid not, but you can add an alias: alias howto='tldr find', then use howto tar.

Q: I want fuzzy find command usage.

A : Opition one: tldr list | grep KEYWORD, option two(suggested way): install fzf first, then use tldr list | fzf | xargs -I{} tldr find {}, you will love it.

Q: I don't like the default color theme, how to change it?

A: Edit the tldr configuration file at ~/.tldrrc; modify the color until you're happy with it.

Q: I faided to update the tldr pages, why?

A: Actually, tldr.py just tries to pull the latest tldr pages for you, no magic behinds it. So the reason why you faided to update is that tldr.py failed to pull the latest upstream, check the failing output and you may know the reason, e.g. you make some changes and haven't commit them yet. You can pull the pages by hand so you can have a better control on it.

Q: Why use the git repo instead of the assets packaged by the official?

A: In fact, you can use the offical assets if you want, download the assets and extract it somewhere, but tldr.py don't support update it using tldr update.

Use a git repo, you can:

• do the version control, yeah, use git.
• better for customization, just edit the pages and add new pages, they belongs to you. You can even maintain your own 'tldr'. If use the official assets, you'll always get the latest pages.

Contributing

• It sucks? Why not help me improve it? Let me know the bad things.
• Want a new feature? Feel free to file an issue for a feature request.
• Find a bug? Open an issue please, or it's better if you can send me a pull request.

Contributions are always welcome at any time! ✨ 🍰 ✨

License

MIT.

tldr.py's Issues

support fuzzy find

when user input a command with typo, maybe have a better suggestion, like ruby's did you mean.

refs:

• https://github.com/yuki24/did_you_mean
• https://github.com/amjith/fuzzyfinder

Installation process requires reading manual

Could you add some autoinstall mod, which clones tldr-pages, then makes install and reindex?
It's strange that tool for not reading long manuals require reading manual to work.

Support for Python 3.9

Now it errors on StopIteration against the tree_generator iteration when reindexing.

Support XDG base directory specification

It would be really cool if tldr supported the XDG base directory specification arch wikidebian wiki. In this case, the .tldrrc file would move to ~/.config/tldrrc (in linux). The tldr repo would probably go in .local/share/tldr. There is a python package called appdirs that will provide these values for you on at least osx or linux if you're interested!

Python 3.x support

Tab-completion and sanity check for path when using `tldr init'

For tldr init', it would be a polished feature enhancement not to have to manually enter an entire path, and risk a typo error. For example, the program could offer tab-completion of paths, and re-issue a prompt (with scrollable history) if the path entered either doesn't exist or isn't a valid root directory (maybe check for a legitimate package.json' file or other indication.

An alternative would be to explicitly warn the user that expansions are not performed or understood.

Just some user-friendly polish.

Support locate the command man page

If we want to custom our man pages, we need to find it in the command folder or in the platform folder, a little inconvenient. Maybe we should add a subcommand like this:

$ tldr locate tar
/tldr/repo/pages/linux/tar.md

so we can easily edit the man pages.

Any ideas?

tldr update failing

$tldr update

I get the following :

sorry , newb and not python wize , so not sure what these mean.

Check for updates...
fatal: ambiguous argument 'master': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git [...] -- [...]'
Traceback (most recent call last):
File "/usr/bin/tldr", line 11, in
load_entry_point('tldr.py==0.7.0', 'console_scripts', 'tldr')()
File "/usr/lib/python3/dist-packages/click/core.py", line 829, in call
return self.main(*args, **kwargs)
File "/usr/lib/python3/dist-packages/click/core.py", line 782, in main
rv = self.invoke(ctx)
File "/usr/lib/python3/dist-packages/click/core.py", line 1259, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/lib/python3/dist-packages/click/core.py", line 1066, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/lib/python3/dist-packages/click/core.py", line 610, in invoke
return callback(*args, **kwargs)
File "/usr/lib/python3/dist-packages/tldr/cli.py", line 114, in update
local = subprocess.check_output('git rev-parse master'.split()).strip()
File "/usr/lib/python3.9/subprocess.py", line 424, in check_output
return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
File "/usr/lib/python3.9/subprocess.py", line 528, in run
raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command '['git', 'rev-parse', 'master']' returned non-zero exit status 128.

tldr find command not working

❯ tldr find tar
Traceback (most recent call last):
  File "/home/sanket/.local/bin//tldr", line 11, in <module>
    sys.exit(cli())
  File "/home/sanket/.local/lib/python2.7/site-packages/click/core.py", line 716, in __call__
    return self.main(*args, **kwargs)
  File "/home/sanket/.local/lib/python2.7/site-packages/click/core.py", line 696, in main
    rv = self.invoke(ctx)
  File "/home/sanket/.local/lib/python2.7/site-packages/click/core.py", line 1060, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/sanket/.local/lib/python2.7/site-packages/click/core.py", line 889, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/sanket/.local/lib/python2.7/site-packages/click/core.py", line 534, in invoke
    return callback(*args, **kwargs)
  File "/home/sanket/.local/lib/python2.7/site-packages/tldr/cli.py", line 99, in find
    output_lines = parse_man_page(command)
  File "/home/sanket/.local/lib/python2.7/site-packages/tldr/cli.py", line 24, in parse_man_page
    page_path = find_page_location(command)
  File "/home/sanket/.local/lib/python2.7/site-packages/tldr/cli.py", line 35, in find_page_location
    encoding='utf-8') as f:
IOError: [Errno 2] No such file or directory: '/home/sanket/tldr/pages/index.json'

Support the tldr page syntax

Can I use the tldr <command> directly without adding the options `find`?

I find if I use tldr ssh, an error occured:

[user@hostname:~] tldr ssh
Usage: tldr [OPTIONS] COMMAND [ARGS]...

Error: No such command "ssh".

Is it necessary to add the find command? But the tldr find tldr command shows:

  Simplified man pages.

- Get typical usages of a command (hint: this is how you got here!):

  tldr {{command}}

- Update the local cache of tldr pages:

  tldr --update

Tests.

Support tilde and parameter expansion

A user should be able to use '~' or shell variables such as ${HOME} when setting $TLDR_CONFIG_DIR or when responding to queries in `tldr init'.

Improve the color theme

Currently, the default color theme is:

    colors = {
        "description": "blue",
        "usage": "green",
        "command": "cyan"
    }

tldr.py use click as the CLI package, the colors that click supports are:

• black (might be a gray)
• red
• green
• yellow (might be an orange)
• blue
• magenta
• cyan
• white (might be light gray)
• reset (reset the color code only)

you can find the documentation here.

parser.py shows how tldr.py parse the markdown file.

If you have a custom color theme and you want to share with us, you can leave your comment with the configuration and maybe with a screen shot here.

Any suggestions and feedback are welcome ❤️

tldr find command is dumb.

I don't want to type more than I have to.
Forked so I can fix this.

pip install tldr.py - errors

I decided to move this out of the previous thread for better visibility.
After successfully installing tldr.py (i.e. by performing pip install tldr.py), and creating the ~/.tldrcc (i.e. with tldr.py init. I attempt to execute tldr.py and receive the following errors:
.# tldr find sed
Traceback (most recent call last):
File "/usr/local/bin/tldr", line 11, in
sys.exit(cli())
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 716, in call
return self.main(_args, *_kwargs)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 696, in main
rv = self.invoke(ctx)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 1060, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 889, in invoke
return ctx.invoke(self.callback, *_ctx.params)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 534, in invoke
return callback(_args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/tldr/cli.py", line 93, in find
find_page(command)
File "/usr/local/lib/python2.7/dist-packages/tldr/cli.py", line 28, in find_page
encoding='utf-8') as f:
IOError: [Errno 2] No such file or directory: '/usr/local/lib/python2.7/dist-packages/tldr/pages/index.json'

My environment: I am using Debian 8, with Python 2.7. I have also tried this on the latest version of openSUSE tumbleweed and received the same error after performing the same steps.

Custom commands pages

Hi,

I have a few custom commands. Is it possible to have custom pages for these?

One could add a line in the config file:

custom_pages_directory: /home/lord63/code/custom_pages

And in cli.py we can just check if it exist a custom page for the current command:

(something like this:)

def find_page(command):
  ...
  custom_pages_directory = get_config()['custom_pages_directory']
  repo_directory = get_config()['repo_directory']
  default_platform = get_config()['platform']

  page_path = find_custom_page(custom_pages_directory, command)

  if not page_path:
    with io.open(path.join(repo_directory, 'pages/index.json'), encoding='utf-8') as f:
      index = json.load(f)
    ...

Or maybe better:

def render_page(command):
  page_path = find_page(command)
  output_lines = parse_page(page_path)
  click.echo(''.join(output_lines))

def find_page(command):
  custom_page = find_custom_page(command)
  return custom_page if custom_page else find_remote_page(command)

I can send you a pull request if you want.

Incorrect installation instruction

Installation instruction suggests using this command to clone repo.
git clone [email protected]:tldr-pages/tldr.git
It will throw Permission denied (publickey) error, if you have no github publickey installed.
I suggest change this command to git clone https://github.com/tldr-pages/tldr.git, because it would work everywhere.

Feature request: optional abbreviated output

Hey, I think a great addition would be an option to abbreviate output.
I for example never look at the description of the command. Also useful would be to omit the linebreak between the 'info' and the command like this and only keep the break to the next example:

• Find files by extension:
  find {{root_path}} -name '{{*.ext}}'

• Find files matching path pattern:
  ....

This is especially useful if you're using a smaller terminal window or a large lineheight.

Suggestion: syntax streamlining

This is a good client but following CLI syntax would IMO be an improvement.
Note: COMMAND refers to which command's tldr page user wants find.

Usage: tldr COMMAND [OPTIONS] [ARGS]...

Options:
  -i, --init     Init config file.
  -l, --locate   Locate the command's man page.
  -r, --reindex  Rebuild the index.
  -u, --update   Update to the latest pages.
  -V, --version  Show the version and exit.
  -h, --help     Show this message and exit.

So any argument that's not an option would be considered as a command user wants to find. Advantages: for majority of time I strongly suspect user wants to find a command's tldr page. This syntax is streamlined, shorter and more predictable (to guess/remember without reading help): instead of 'tldr find ls', 'tldr find ssh', 'tldr find tar' you can use 'tldr ls', 'tldr ssh', 'tldr tar'. Other functions than finding tldr page are much less used so they could be used as options like above. For example: rebuild index: 'tldr --rebuild' or 'tldr -r'.

• cheers.

Improve the tests

The current tests touches the users' configuration file. Not a good idea, need to drop this behaviour.

Support rebuild the index.

Tldr has remove the index build, so the updated pages may still can't be found since the index.json in not the latest. Also, when you add a custom page by yourself, you need to build the index yourself. Maybe we should add a subcommand to support building the index, for example:

$ tldr reindex

or something like this.

Unable to run on Python 2.7.11

I installed tldr.py using pip install tldr.py on Python 2.7.11, but the compiled version doesn't appear to work for me.

~
❯ pip2 install tldr.py
Collecting tldr.py
  Using cached tldr.py-0.2.0-py2.py3-none-any.whl
Requirement already satisfied (use --upgrade to upgrade): click>=5.0 in ./.pyenv/versions/2.7.11/lib/python2.7/site-packages (from tldr.py)
Requirement already satisfied (use --upgrade to upgrade): PyYAML>=3.11 in ./.pyenv/versions/2.7.11/lib/python2.7/site-packages (from tldr.py)
Installing collected packages: tldr.py
Successfully installed tldr.py-0.2.0

# I tried running the uncompiled binary using `pip install -e .` after cloning the repo
~
❯ tldr
Traceback (most recent call last):
  File "/Users/jjwon/.pyenv/versions/2.7.11/bin/tldr", line 9, in <module>
    load_entry_point('tldr.py==0.2.0', 'console_scripts', 'tldr')()
  File "/Users/jjwon/.pyenv/versions/2.7.11/lib/python2.7/site-packages/pkg_resources/__init__.py", line 558, in load_entry_point
    return get_distribution(dist).load_entry_point(group, name)
  File "/Users/jjwon/.pyenv/versions/2.7.11/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2682, in load_entry_point
    return ep.load()
  File "/Users/jjwon/.pyenv/versions/2.7.11/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2355, in load
    return self.resolve()
  File "/Users/jjwon/.pyenv/versions/2.7.11/lib/python2.7/site-packages/pkg_resources/__init__.py", line 2361, in resolve
    module = __import__(self.module_name, fromlist=['__name__'], level=0)
ImportError: No module named cli

It works on my computer with Python 2.7.10, Python 3.4, but not this version.

Support search commands in other platforms

upstream tldr mindlessly changed `master` to `main`

tldr.py/tldr/cli.py

Lines 139 to 145 in 4f8065a

	local = subprocess.check_output('git rev-parse master'.split()).strip()
	remote = subprocess.check_output(
	'git ls-remote https://github.com/tldr-pages/tldr/ HEAD'.split()
	).split()[0]
	if local != remote:
	click.echo("Updating...")
	subprocess.check_call('git checkout master'.split())

is now broken.

Update your code to participate in the performance.

May i clone the wrong repository or branch?

After initialize , when i run command
tldr find ls
there was an error :
IOError: [Errno 2] No such file or directory: '/***/tldr.py/pages/index.json'

Double braces on output

tldr.py leaves double braces on output. Shouldn't they be shown as underline or such?

For example:
$ tldr find find
Find files under the given directory tree, recursively.

• Find files by extension:
  find {{root_path}} -name '{{*.ext}}'

• Find files matching path pattern:
  find {{root_path}} -path '{{/lib//*.ext}}'

• Run a command for each file, use {} within the command to access the filename:
  find {{root_path}} -name '{{*.ext}}' -exec {{wc -l {} }};

tldr list does not exist

Hi again.

According to here(https://pypi.org/project/tldr.py/) I could use TLDR with FZF by piping tldr list. However, this list command don't exist according to the tldr man or even when I execute it $tldr list, I get the usage message instead, any idea ?

Set "find" as default command

Hi,

It would be nice if "find" can be default command and can be omitted.

So this:

onovy@sid~/tmp $ tldr tar
Usage: tldr [OPTIONS] COMMAND [ARGS]...

Error: No such command "tar".
onovy@sid~/tmp $

will show page for 'tar'.

Thanks.