#+title: Eless - A Better Less #+author: Kaushal Modi [[https://github.com/kaushalmodi/eless/actions][https://github.com/kaushalmodi/eless/actions/workflows/test.yml/badge.svg]] [[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 *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 #[[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.