*Documentation*

*eless* is a combination of Bash script and a minimal emacs view-mode config.

This script is designed to:

• Be portable – Just one bash script to download to run
• Be independent of a user’s emacs config
  • You can still customize the =eless= config if you like.
• Not require an emacs server to be already running

It was created out of a need to have something like less (in the sense of launch quickly, do, and quit), but better in these ways:

• Syntax highlighting
• Org-mode file rendering
• A better navigable man page viewer
• A better Info viewer
• Dired, especially wdired (batch edit symbolic links, for example?)
• Colored diffs, git diff, git log, ls, etc. (auto ANSI detection)
• Filter log files to only show (or not show) lines matching a regexp
• Auto-revert log files when I want (like tail -f)
• Quickly change frame and font sizes
• .. and more; basically everything that emacs has to offer!

I call it eless and here’s a little taste of what it looks like:

Shown above, starting from top left image and proceeding clock-wise..

• eless eless.org
• rg --color=ansi 'man pages' | eless (rg?)
• man grep (I have set my PAGER env var to eless.)
• info eless (I have aliased info to '\info \!* | eless' in my tcsh shell.)
• eless . (Shows the current directory contents in dired.)
• diff of eless.org with an older saved version and piping the result to eless

Meta Features

• [X] This script passes ShellCheck, and
• [X] Unofficial Bash /strict mode/[fn:1] is enabled.
• [X] Always-in-sync documentation as the eless script and documentation are generated using Org Babel from one file (even this README).
• [X] The documentation site is generated on-the-fly on Netlify using that same one file.
• [X] This bash script has tests too!

[fn:1] http://redsymbol.net/articles/unofficial-bash-strict-mode/

NOTE 1

If the environment variable EMACS is set, eless uses that as the emacs binary, else it defaults to using emacs as emacs binary.

NOTE 2

eless is known to not work with info (texinfo) 6.1 (see eless issue #35). If you want to use eless to view Info manuals, ensure that it is at least version 6.5.

For the following instructions, let’s assume that you clone this repo to ~/downloads/eless.

git clone https://github.com/kaushalmodi/eless ~/downloads/eless

cd ~/downloads/eless
make install PREFIX=~/.local

The above make install will install the eless script and documentation in a directory structure like this:

<PREFIX>
    ├── bin/
    │    └── eless
    └── share/
         └── eless/
              ├── eless.org
              └── info/
                   ├── eless.info
                   └── dir

NOTE

Make sure that you add <PREFIX>/bin/ directory to your PATH environment variable and <PREFIX>/share/eless/info/ to INFOPATH.

Assuming that you used PREFIX=~/.local in the Run =make= step above, uninstall it using the same PREFIX:

cd ~/downloads/eless
make uninstall PREFIX=~/.local

Homebrew users can install eless using:

brew install eless

Here are some usage examples:

eless foo.txt                         # Open foo.txt in eless in terminal (-nw) mode by default.
eless foo.txt --gui                   # Open foo.txt in eless in GUI mode.
echo 'foo' | eless                    #
echo 'foo' | eless -                  # Same as above. The hyphen after eless does not matter; is anyways discarded.
grep 'bar' foo.txt | eless            #
diff foo bar | eless                  # Colored diff!
diff -u foo bar | eless               # Colored diff for unified diff format
eless .                               # Open dired in the current directory (enhanced 'ls')
ls --color=always | eless             # Auto-detect ANSI color codes and convert those to colors
PAGER=eless git diff                  # Show git diff with ANSI coded colors
eless -h | eless                      # See eless help ;-)
info emacs | eless                    # Read emacs Info manual in eless
eless foo.tar.xz                      # Read the contents of archives; emacs does the unarchiving automatically
PAGER=eless python3; help('def')      # Read (I)Python keyword help pages (example: help for 'def' keyword)
PAGER=eless python3; help('shlex')    # Read (I)Python module help pages (example: help for 'shlex' module)
PAGER=eless python3; help('TYPES')    # Read (I)Python topic help pages (example: help for 'TYPES' topic)
PAGER=eless man grep                  # Launches man pages in eless (terminal mode), if the env var PAGER is set to eless (does not work on macOS).
PAGER=less man -P eless grep          # Launches man pages in eless (terminal mode), if the env var PAGER is *not* set to eless (works on macOS).
PAGER="eless --gui" man grep          # Launches man pages in eless (GUI mode), if the env var PAGER is set to "eless --gui" (does not work on macOS).
PAGER=less man -P "eless --gui" grep  # Launches man pages in eless (GUI mode), if the env var PAGER is *not* set to eless (works on macOS).

NOTE

Above examples are tested to work in a =bash= shell. Specifically, examples like PAGER=eless man grep might need to be adapted for the shell you are using, and also the OS.

• Thanks to Skye Shaw for helping improving eless so that it can run on macOS and emacs 22.1, and suggesting Bash trap.
• Thanks to Iqbal Ansari for adding support to read piped data in emacs -Q -nw.
• Thanks to Adam Porter for adding a bash collapsing function for debug statements, and testing out and providing suggestions on improving the eless build flow.