mstruebing / tldr

Golang command line client for tldr https://github.com/tldr-pages/tldr

tldr

This tool shows the most common used parameter to different CLI-tools. This prevents long reading of help-flag output and man pages.

Usage

usage: tldr [OPTION]... SEARCH

available commands:
    -v, --version           print version and exit
    -h, --help              print this help and exit
    -u, --update            update local database
    -p, --platform PLATFORM select platform, supported are linux / osx / sunos / common
    -a, --list-all          list all available commands for the current platform
    -f, --path PATH			render a local page(file) for testing purposes
    -r, --random			print a random page

Install

Just copy the executable anywhere on your system, preferably in some folder where your $PATH variable will find it.

Executables to every release can be found on the release page of this repository.

If you want to build it yourself see below.

On Arch Linux you can simply:

yaourt -S tldr-go-client-git or trizen -S tldr-go-client-git, or any other aur-helper. This also auto install bash and zsh completions.

Docker (mstruebing/tldr)

You can use a docker image:

docker pull mstruebing/tldr and execute it via: docker run -it mstruebing/tldr tldr tar for example. If you want to connect into the container and execute more commands you can use docker run -it mstruebing/tldr sh.

Dependencies

You don't need any runtime dependencies.

To build it yourself you just need golang(1.8 and 1.9 are currently tested) installed.

Building

If you want to build it yourself you can use the Makefile and type make build. This will put the tldr binary in a bin folder. If you want to compile it without it just do a go build in the root of this repository.

To install it on your system you can do a simple sudo make install in the root of this repository. This will build the executable file and install it to /usr/bin as well as zsh and bash autocompletions. You can install it into an other directory with:

INSTALL_DIR=/path/where/you/want/the/binary/to/live sudo make install

Make sure you have this directory in your $PATH. Otherwise you can build the executable yourself and copy it wherever you want. Or simply adjust the Makefile to your needs.

command	effect
make build	builds the binary for your current platform and places it in ./bin/
make install	runs build and copies the binary to ~/bin/
make test	runs tests
make build-all-binaries	builds all binaries for currently supported platforms
make compress-all-binaries	runs build-all-binaries and compresses them
make clean	cleans ./bin/ and cache folders

Autocompletion

Currently this tool provides autocompletion for zsh and bash.

Bash

In bash you simply need to source the file (source autocomplete.bash).

source autocompletion/autocomplete.bash

You can put this into your .bashrc:

source <path/to/repo>/autocompletion/autocomplete.bash

Zsh

Currently only tested with oh-my-zsh: In zsh you need to copy or symlink autocomplete.zsh to $ZSH_CUSTOM/plugins/tldr/_tldr.

copy:

mkdir -p $ZSH_CUSTOM/plugins/tldr && 
cp autocompletion/autocomplete.zsh $ZSH_CUSTOM/plugins/tldr/_tldr

symlink:

mkdir -p $ZSH_CUSTOM/plugins/tldr && 
ln -s autocompletion/autocomplete.zsh $ZSH_CUSTOM/plugins/tldr/_tldr

And then define it in your .zshrc as a plugin:

plugins=(git tldr otherPlug)

Contribution

Please read CONTRIBUTING.md

tldr's Issues

Add automatic releases on `main` push

This is dependent on #60 and #59 but if that has happened we could introduce automatic releases.

Adjust error handling

e.g.

$ ./bin/tldr update
2017/10/19 22:03:02 ERROR: getting markdown for 'update': open /home/maex/.tldr/pages/windows/update.md: no such file or directory

It should state that the page isn't found in any platform.
There are also some error message with start with err instead of ERROR: <message>

Add Issue and Pull Request Template

RFC: Which builds to release?

Do we need really this many different builds for every release?
Which ones should be included and which ones not?

I'm thinking that at least all 386 and amd64 builds should be included, but I'm not sure and I don't want to disadvantage certain systems.

Add Code of conduct

Introduce goreleaser

Instead of having an extensive Makefile we could introduce goreleaser: https://goreleaser.com/ to make releases more reliable and easier.

This could also be used to clean up the amount of binaries we build for different architectures. I believe most of them are never used.

`Repository.isReachable()` doesn't work as expected

This function seems to always return false right now
Which makes the tool annoying to use.

Autocompletion

The client should provide autocompletion for at least bash and zsh

shows index.json in `--list-all`

tldr shows an index.json in the --list-all view and also considered it as autocomplete option.

Go repositories should not contain the word "go" in it. It's an anti-pattern

Rename it to tldr

Use XDG variable for tldr cache

see: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

Remove unzip dependency

See: https://golangcode.com/unzip-files-in-go/

Let the tool act as a library

Feedback from @agnivade

A common convention when you are writing a binary is to have the main.go inside a "cmd/tldr/main.go" folder and import what you need. That way your entire codebase acts as a library. https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1

Check if update is needed

The client should check if an update is needed via commit hash.

This means to also introduce a force-flag to update.

Document how autocompletion can be used

Use the "flags" package

instead of manually parsing CLI arguments

Add Contributing.md

Introduce clear-cache flag

Reload cache: only remove old cache if new cache is finally downloaded

Currently the cache gets updated after a specified time to live.
This is fine, but when you are executing tldr and the ttl is over and you are not connected to the internet it fails to get the new cache and has no pages because the cache is already deleted.

Compress files automatically after build-all-platforms

To reduce size to upload releases.

To many open files

2017/10/20 09:23:57 ERROR: creating cache repository: ERROR: loading data from remote: ERROR: unzipping pages: err opening file '/Users/simon/.tldr/pages/common/mysql.md': open /Users/simon/.tldr/pages/common/mysql.md: too many open files

quick research: golang/go#3978

https://github.com/mstruebing/tldr/blob/master/cache/cache.go#L197

Reduce cyclomatic complexity

see: https://goreportcard.com/report/github.com/mstruebing/tldr-go-client#gocyclo

Implement random command

Your System:

What did I execute: tldr -r|--random

Expected behavior: Should output a random page

Actual behavior: Currently not implemented.

Add Homebrew formula for macOS users

Switch to `main` branch instead of `master`

Your System:

What did I execute:

Expected behavior:

Actual behavior:

Add different builds to makefile

See:

https://golang.org/doc/install/source#environment

If XDG_CACHE_HOME is not defined, I believe it will try to delete /tldr from root folder

It might not hurt anything, but no a good idea to do and it is not the code intention

tldr/Makefile

Line 65 in afe0c46

rm -Rf bin; rm -Rf $(XDG_CACHE_HOME)/tldr; rm -Rf ~/.cache/tldr

Foreground color not restored after rendering a page

Experiencing at ed57142 on Debian Stretch amd64 while running tldr from rxvt-unicode v 9.22 in 256 colors mode, that is, I have

~$ echo $TERM
rxvt-unicode-256color

The bug manifests itself in that the PS1 shell's prompt goes rendered in black color after tldr stack is run. Running reset gets the foreground color back to normal.

Two bits of information which might help:

• I use bash with no-frills PS1, that is, my PS1 does not use any ANSI color sequences in it.
• I have rxvt background set to #3f3f3f and foreground to #dcdccc (IOW my background it not exactly black).

Add govet and gofmt to travis

List only shows results from current OS

Your System:

What did I execute: tldr --lista-all

Expected behavior: This command should output ALL available pages.

Actual behavior: Currently the command just outputs the pages of the users current system.

Add code coverage and write tests

make test will execute tests now, just need to write some more

Use Github Actions

There is travis configured currently which is not running since quite a while.
We should migrate to Github actions.

Make autocompletion autoinstallable

I'm not sure if this is a good idea becuase that means to manipulate the users .zshrc or .bashrc.

If you have suggestions please let me know.