kaushalmodi / Eless

#+TITLE: Eless - A Better Less #+AUTHOR: Kaushal Modi [[https://travis-ci.org/kaushalmodi/eless][https://travis-ci.org/kaushalmodi/eless.svg?branch=master]] | [[https://eless.scripter.co][Documentation]]

---

[[https://github.com/kaushalmodi/eless][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 [[https://eless.scripter.co/#user-config-override][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:

[[https://raw.githubusercontent.com/kaushalmodi/eless/master/docs/images/eless-examples.png][https://raw.githubusercontent.com/kaushalmodi/eless/master/docs/images/eless-examples.png]]

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

• =eless eless.org=
• =rg --color=ansi 'man pages' | eless= (rg[[https://github.com/BurntSushi/ripgrep][?]])
• =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 [[https://www.shellcheck.net][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 [[https://github.com/kaushalmodi/eless/blob/master/eless.org][one file]] (even this README).
• [X] The [[https://eless.scripter.co][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 24.4 (24.4 onwards versions are auto-tested on Travis). | | =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 #[[https://github.com/kaushalmodi/eless/issues/35][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=. #+begin_src shell git clone https://github.com/kaushalmodi/eless ~/downloads/eless #+end_src *** Run make #+begin_src shell cd /downloads/eless make install PREFIX=/.local #+end_src *** Installation Directory Structure The above make install will install the eless script and documentation in a directory structure like this: #+begin_example

├── bin/ │ └── eless └── share/ └── eless/ ├── eless.org └── info/ ├── eless.info └── dir #+end_example - NOTE :: Make sure that you add ~/bin/~ directory to your ~PATH~ environment variable and ~/share/eless/info/~ to ~INFOPATH~. *** Uninstallation Assuming that you used ~PREFIX=~/.local~ in the [[#installation-make][Run =make=]] step above, uninstall it using the same ~PREFIX~: #+begin_src shell cd ~/downloads/eless make uninstall PREFIX=~/.local #+end_src ** Homebrew users [[https://brew.sh/][Homebrew]] users can install ~eless~ using: #+begin_example brew install eless #+end_example * Try it out Here are some usage examples: #+begin_src shell 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). #+end_src - 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, [[#example-eless-config-in-bash][and also the OS]]. * Contributors - Thanks to [[https://github.com/sshaw][Skye Shaw]] for helping improving =eless= so that it can run on /macOS/ and emacs 22.1, and suggesting Bash =trap=. - Thanks to [[https://github.com/iqbalansari][Iqbal Ansari]] for adding support to read piped data in =emacs -Q -nw=. - Thanks to [[https://github.com/alphapapa][Adam Porter]] for adding a =bash= /collapsing function/ for debug statements, and testing out and providing suggestions on improving the =eless= build flow.