Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kaushalmodi/eless

A Better 'less' - A bash script that loads emacs with minimal view-mode config - Created with Org mode
https://github.com/kaushalmodi/eless

bash-script emacs emacs-lisp less literate-programming org-babel org-mode org-tangle

Last synced: 8 days ago
JSON representation

A Better 'less' - A bash script that loads emacs with minimal view-mode config - Created with Org mode

Lists

README 

        
#+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.