README edits

- Replaced the broken PyPi badges with new ones
- Moved some content out of the README and into new wiki pages
- Applied syntax highlighting to shell examples
- Trivial content edits
This commit is contained in:
Chris Lane 2016-02-18 15:09:02 -05:00
parent c1d4c768de
commit 8ffeaa4211

108
README.md
View file

@ -1,3 +1,6 @@
[![PyPI](https://img.shields.io/pypi/v/cheat.svg)](https://pypi.python.org/pypi/cheat/)
[![PyPI](https://img.shields.io/pypi/dm/cheat.svg)](https://pypi.python.org/pypi/cheat/)
cheat cheat
===== =====
`cheat` allows you to create and view interactive cheatsheets on the `cheat` allows you to create and view interactive cheatsheets on the
@ -7,66 +10,51 @@ remember.
![The obligatory xkcd](http://imgs.xkcd.com/comics/tar.png 'The obligatory xkcd') ![The obligatory xkcd](http://imgs.xkcd.com/comics/tar.png 'The obligatory xkcd')
`cheat` depends only on `python` and `pip`.
PyPI status:
[![Latest Version](https://pypip.in/version/cheat/badge.png)](https://pypi.python.org/pypi/cheat/)
[![Downloads](https://pypip.in/download/cheat/badge.png)](https://pypi.python.org/pypi/cheat/)
Example Example
------- -------
The next time you're forced to disarm a nuclear weapon without consulting The next time you're forced to disarm a nuclear weapon without consulting
Google, you may run: Google, you may run:
cheat tar ```sh
cheat tar
```
You will be presented with a cheatsheet resembling: You will be presented with a cheatsheet resembling:
``` ```sh
# To extract an uncompressed archive: # To extract an uncompressed archive:
tar -xvf /path/to/foo.tar tar -xvf '/path/to/foo.tar'
# To extract a .gz archive: # To extract a .gz archive:
tar -xzvf /path/to/foo.tgz tar -xzvf '/path/to/foo.tgz'
# To create a .gz archive: # To create a .gz archive:
tar -czvf /path/to/foo.tgz /path/to/foo/ tar -czvf '/path/to/foo.tgz' '/path/to/foo/'
# To extract a .bz2 archive: # To extract a .bz2 archive:
tar -xjvf /path/to/foo.tgz tar -xjvf '/path/to/foo.tgz'
# To create a .bz2 archive: # To create a .bz2 archive:
tar -cjvf /path/to/foo.tgz /path/to/foo/ tar -cjvf '/path/to/foo.tgz' '/path/to/foo/'
``` ```
To see what cheatsheets are availble, run `cheat -l`. To see what cheatsheets are availble, run `cheat -l`.
Note that, while `cheat` was designed primarily for *nix system administrators, Note that, while `cheat` was designed primarily for \*nix system administrators,
it is agnostic as to what content it stores. If you would like to use `cheat` it is agnostic as to what content it stores. If you would like to use `cheat`
to store notes on your favorite cookie recipes, feel free. to store notes on your favorite cookie recipes, feel free.
Installing Installing
---------- ----------
It is recommended to install `cheat` with `pip`:
### Using pip ###
sudo pip install cheat ```sh
[sudo] pip install cheat
```
### Using homebrew ### [Other installation methods are available][installing].
brew install cheat
### Manually ###
First install the required python dependencies with:
sudo pip install docopt pygments
Then, clone this repository, `cd` into it, and run:
sudo python setup.py install
Modifying Cheatsheets Modifying Cheatsheets
@ -82,7 +70,9 @@ in the `~/.cheat/tar` file.
Provided that you have an `EDITOR` environment variable set, you may edit Provided that you have an `EDITOR` environment variable set, you may edit
cheatsheets with: cheatsheets with:
cheat -e foo ```sh
cheat -e foo
```
If the 'foo' cheatsheet already exists, it will be opened for editing. If the 'foo' cheatsheet already exists, it will be opened for editing.
Otherwise, it will be created automatically. Otherwise, it will be created automatically.
@ -99,17 +89,23 @@ Personal cheatsheets are saved in the `~/.cheat` directory by default, but you
can specify a different default by exporting a `DEFAULT_CHEAT_DIR` environment can specify a different default by exporting a `DEFAULT_CHEAT_DIR` environment
variable: variable:
export DEFAULT_CHEAT_DIR=/path/to/my/cheats ```sh
export DEFAULT_CHEAT_DIR='/path/to/my/cheats'
```
### Setting a CHEATPATH ### ### Setting a CHEATPATH ###
You can additionally instruct `cheat` to look for cheatsheets in other You can additionally instruct `cheat` to look for cheatsheets in other
directories by exporting a `CHEATPATH` environment variable: directories by exporting a `CHEATPATH` environment variable:
export CHEATPATH=/path/to/my/cheats ```sh
export CHEATPATH='/path/to/my/cheats'
```
You may, of course, append multiple directories to your `CHEATPATH`: You may, of course, append multiple directories to your `CHEATPATH`:
export CHEATPATH=$CHEATPATH:/path/to/more/cheats ```sh
export CHEATPATH=$CHEATPATH:/path/to/more/cheats
```
You may view which directories are on your `CHEATPATH` with `cheat -d`. You may view which directories are on your `CHEATPATH` with `cheat -d`.
@ -117,39 +113,17 @@ You may view which directories are on your `CHEATPATH` with `cheat -d`.
`cheat` can apply syntax highlighting to your cheatsheets if so desired. To `cheat` can apply syntax highlighting to your cheatsheets if so desired. To
enable this feature, set a `CHEATCOLORS` environment variable: enable this feature, set a `CHEATCOLORS` environment variable:
export CHEATCOLORS=true ```sh
export CHEATCOLORS=true
```
### Enabling Command-line Autocompletion ### See Also:
The `cheat/autocompletion` directory contains scripts to enable command-line ---------
autocompletion for various shells. To activate autocompletion, simply copy the - [Enabling Command-line Autocompletion][autocompletion]
appropriate script to the appropriate path on your system. (The "appropriate - [Related Projects][related-projects]
path" will vary on a per-platform basis, so this documentation shall not
speculate as to where that may be.)
Related Projects [autocompletion]: https://github.com/chrisallenlane/cheat/wiki/Enabling-Command-line-Autocompletion
---------------- [dotfiles]: http://dotfiles.github.io/
[installing]: https://github.com/chrisallenlane/cheat/wiki/Installing
- [lucaswerkmeister/cheats][1]: An implementation of this concept in pure bash [related-projects]: https://github.com/chrisallenlane/cheat/wiki/Related-Projects
that also allows not only for numerical indexing of subcomands but also
supports running commands interactively.
- [jahendrie/cheat][2]: A bash-only implementation that additionally allows for
cheatsheets to be created and `grep` searched from the command-line.
([jahendrie][] contributed key ideas to this project as well.)
- [`cheat` RubyGem][3]: A clever gem from 2006 that clearly had similar
motivations. It is unclear whether or not it is currently maintained.
- [`tldr`][tldr]: "Simplified and community-driven man pages".
- [dufferzafar/cheat][5]: An implementation in golang that has syntax highlighting and allows to copy cheats directly to clipboard.
[dotfiles]: http://dotfiles.github.io/
[jahendrie]: https://github.com/jahendrie
[1]: https://github.com/lucaswerkmeister/cheats
[2]: https://github.com/jahendrie/cheat
[3]: http://errtheblog.com/posts/21-cheat
[4]: https://github.com/chrisallenlane/cheat/pull/77
[5]: https://github.com/dufferzafar/cheat
[tldr]: https://github.com/tldr-pages/tldr