README.org

Eless - A Better Less

*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/

Requirements

Software	Details
emacs	If only running the eless script, the mininum required emacs version is 22.1 (manually tested). If developing (running make all html test), the minimum required version is 25.3.
bash	This is a bash script. So even if you don’t use bash shell, you need to have the bash binary discoverable through your environment variable PATH. Tested to work in =tcsh= shell on RHEL 6.6.
perl	Perl is used to replace grep -Po and case-insensitive sed based replacements (using /I) as those features are available only in GNU versions of grep and sed (which are not present by default on macOS systems). Tested with Perl v5.16.3 on RHEL 6.6.
texinfo	Required to generate the eless Info manual (when doing make install)

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.

Installation

Manual installation

Clone this rep

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

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

Run make

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

Installation Directory Structure

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.

Uninstallation

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

Homebrew users can install eless using:

brew install eless

Try it out

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.

Contributors

• 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.