Skip to content

Latest commit

 

History

History
302 lines (199 loc) · 9.94 KB

README.md

File metadata and controls

302 lines (199 loc) · 9.94 KB
Raw

eg

Useful examples at the command line.

Build Status

Overview

eg provides examples of common uses of command line tools.

Man pages are great. How does find work, again? man find will tell you, but you'll have to pore through all the flags and options just to figure out a basic usage. And what about using tar? Even with the man pages tar is famously inscrutable without the googling for examples.

No more!

eg will give you useful examples right at the command line. Think of it as a companion tool for man.

eg comes from exempli gratia, and is pronounced like the letters: "ee gee".

eg Demo

Installation

With pip

pip install eg

Without pip

Clone the repo and create a symlink to eg_exec.py. Make sure the location you choose for the symlink is on your path:

git clone https://github.com/srsudar/eg ./
ln -s ./eg/eg_exec.py /usr/local/bin/eg

eg doesn't ship with a binary. You'll have to have python 2.x installed on your machine. Dependencies are very modest and should not require you to install anything (other than Nose if you want to run the tests). If you find otherwise, open an issue.

Usage

eg <program>

eg takes an argument that is the name of a program for which it contains examples.

eg find will provide examples for the find command.

eg --list will show all the commands for which eg has examples.

How it Works

Files full of examples live in examples/. A naming convention is followed such that the file is the name of the tool with .md. E.g. the examples for find are in find.md.

eg find will pipe the contents of find.md through the less (although it tries to respect the PAGER environment variable.

Configuration and Extension

eg works out of the box, no configuration required.

If you want to get fancy, however, eg can be fancy.

For example, maybe a team member always sends you bzipped tarballs and you can never remember the flag for bzipping--why can't that guy just use gzip like everybody else? You can create an example for untarring and unzipping bzipped tarballs, stick it in a file called tar.md, and tell eg where to find it.

The way to think about what eg does is just that it takes a program name, for example find, and looks for two files named find.md in the default directory and a custom directory. If it finds them, it pipes them through less, with the custom file at the top. Easy.

The default and custom directories can be specified at the command line like so:

eg --examples-dir='the/default/dir' --custom-dir='my/fancy/dir' find

Instead of doing this every time, you can define a configuration file. By default it is expected to live in ~/.egrc. It must begin with a section called eg-config and can contain two keys: custom-dir and examples-dir. Here is an example of a valid config file:

[eg-config]
examples-dir = ~/examples-dir
custom-dir = ~/my/fancy/custom/dir

Although by default the file is looked for at ~/.egrc, you can also specify a different location at the command line like so:

eg --config-file=myfile find

Color

eg is colorful. The default colors were chosen to be pretty-ish while boring enough to not create problems for basic terminals. If you want to override these colors, you can do so in the egrc in a color section.

Things that can be colored are:

  • pound: pound sign before headings
  • heading: the text of headings
  • code: anything indented four spaces other than a leading $
  • prompt: a $ that is indented four spaces
  • backticks: anything between two backticks

Values passed to these options must be string literals. This allows escape characters to be inserted as needed. An egrc with heading text a nice burnt orange might look like this:

[eg-config]
custom-dir = ~/my/fancy/custom/dir

[color]
heading = '\x1b[38;5;172m'

To remove color altogether, for example if the color formatting is messing up your output somehow, you can either pass the --no-color flag to eg, or you can add an option to your egrc under the eg-config section like so:

[eg-config]
color = false

Paging

By default, eg pages using less -R. The -R switch tells less to interpret ANSI escape sequences like color rather than showing them raw. If you don't have less installed, eg will try to detect this and page using the pydoc.pager() function instead. In this case you might want to turn off color.

You can specify a different pager using the --pager-cmd option at the command line or the pager-cmd option in the egrc. If specified in the egrc, the value must be a string literal. For example, this egrc would use cat to page:

[eg-config]
pager-cmd = 'cat'

pydoc.pager() does a lot of friendly error checking, so it might still be useful in some situations. If you want to use pydoc.pager() to page, you can pass the pydoc.pager flag to the pager-cmd.

Format and Content of Examples

Example documents are written in markdown. Documents in markdown are easily read at the command line as well as online. They all follow the same basic format.

This section explains the format so that you better understand how to quickly grok the examples.

Contributors should also pay close attention to these guidelines to keep examples consistent.

Overview

Anything indented four spaces or surrounded by backticks `like this` are meant to be input or output at the command line. A single line indented four spaces is a user-entered command. If a block is indented four spaces, only the lines beginning with $ are user-entered--anything else is output.

Name of the Command

The first section heading should be simply the name of the tool. It should be followed by the most rudimentary examples. Users that are familiar with the command but just forget the precise syntax should be able to see what they need without scrolling. Example commands should be as real-world as possible, with file names and arguments as illustrative as possible. Examples for the cp command, for instance, might be:

cp original.txt copy.txt

Here the .txt extensions indicate that these are file names, while the names themselves make clear which is the already existing file and which will be the newly created copy.

This section shouldn't show output and should not include the $ to indicate that we are at the command line.

This section should be a quick glance for users that know what the tool does, know a basic usage is what they are trying to do, and are just looking for a reminder.

Basic Usage

Next a Basic Usage section explains the most basic usage without using real file names. This section gives users that might not know the usual syntax a more abstract example than the first section. It is intended to provide a more useful explanation than the first entry in the man page, which typically shows all possible flags and arguments in a way that is not immediately obvious to new users of the command. The SYNOPSIS section of the man page for cp, for example, shows:

cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ... target_directory

The Basic Usage is intended to provide less verbose, more immediately practical versions of the man page's SYNOPSIS section.

Commands and flags that will affect the behavior are shown as would be entered in the command line, while user-entered filenames and arguments that do not alter the command's behaviors are shown in < >. Examples in the Basic Usage section for the cp command, for instance, might be:

cp -R <original_directory> <copied_directory>

In this command the cp -R indicate the command and behavior and thus are not given in < >. Case-dependent components of the command, in this case the directory to be copied and the name of the copy, are surrounded with < >. Each is wrapped in separate < > to make clear that it is in fact two distinct arguments.

Additional Sections

Subsequent subsections can be added for common uses of the tools, as appropriate.

Formatting

Although markdown is readable, it can still be tricky without syntax highlighting. We use spacing to help the eye.

  1. All code snippets are followed by at two blank lines, unless overruled by 2.

  2. Each line beginning a section (i.e. the first character on the line is #) should be preceded by exactly three lines.

  3. Files should end with two blank lines.

  4. Lines should not exceed 80 characters, unless to accommodate a necessarily long command or long output.

Contributing

Additions of new tools and new or more useful examples are welcome. eg should be something that people want to have on their machines. If it has a man page, it should be included in eg.

Please read the Format of Examples section and review existing example files to get a feel for how eg pages should be structured.

If you find yourself turning to the internet for the same command again and again, consider adding it to the examples.

eg examples do not intend to replace man pages! man is useful in its own right. eg should provide quick examples in practice. Do not list all the flags for the sake of listing them. Assume that users will have man available.

Building and Running Tests

eg depends only on standard libraries and Python 2.x, so building should be a simple matter of cloning the repo and running the executable eg/eg.py.

eg uses Nose for testing, so you'll have to have Nose installed to run tests. Once you have Nose, run nosetests from the root directory of the repo.

Tests should always be expected to pass. If they fail, please open an issue, even if only so that we can better elucidate eg's dependencies.

Grace Hopper Approves

Alias eg to woman for something that is like man but a little more practical:

$ alias woman=eg
$ man find
$ woman find

TODO

  • file