EOS

A simple literate programmed Emacs configuration that relies on org-mode, or an Elisp interpreter desktop distribution.

Wait… What!?

In other words, an Emacs configuration well designed and integrated that provides a generic computer environment for everyday use.

Disclaimer

I don’t recommend anyone to install or use this directly, due to its lack of support and high volatility, although this is probably the final structure, it’s advisable to view this README only as a reference/guide for the author himself (and some crazy friends, thanks guys, I really appreciate all the suggestions and criticism, much love and freedom upon your lives)!

So, here goes a little bit of advice for everyone: read Emacs/Elisp manual (RTFM), and use as an exercise writing your own init.el, but feel free to fork or copy anything from src/eos.org that you like or find useful.

Learning Elisp may be tricky at first, compared to other languages, but once you understated the evaluation process, everything else turns out to be a piece of cake.

d(-_-)b, nice song!

It’s better to understand, once and for all, that as an Emacs user you automatically become a developer of it, this is the user developer concept, and there’s no way around it. Unfortunately some people find this overwhelming, but others find it formidable - myself included!

Knowing that, maybe you should consider Emacs isn’t for you. No problem, just move on :)

Screenshot

Present Day, heh… Present Time

Introduction

Emacs is not only a text editor, but a complete programmable platform capable of transforming any data of interest.

Emacs can be extended and twisted using the Elisp interpreter which is also the main interface to interact with its resources.

The same interface is used to program and evaluate.

ELISP is a functional programming language - a dialect of LISP, and all we do (inside Emacs) is related to the Elisp interpreter, i.e, lists are evaluated one after another, and as a side effect, data transformations are performed resulting in the desired feature.

To take things out of the realm of abstraction, let’s see an example:

When (move-beginning-of-line 1) list is evaluated, the cursor will be brought back to the beginning of the current line. Note the desired feature is to move the cursor to the beginning of the line and, after evaluating the list, the data transformation that occurs is related to displaying the cursor in a different position.

Features are side effects of data transformations and, sometimes, the computation to perform a particular transformation has almost nothing to do with the desired outcome.

To summarize everything in a single statement:

Emacs is a programmable platform with builtin libraries that provide editing and data visualization functionalities. Its core - the interpreter and basic features - is written using the C programming language, and all the other packages that extend it use a LISP dialect called Emacs Lisp, usually abbreviated as Elisp. The interpreter is the main interface to interact with its components and lists are evaluated to do so.

We live inside the Elisp interpreter triggering actions that are simply lists evaluations.

This train of thought makes it clearer to the reader that Emacs is not a mere text editor. It offers a much richer environment as a huge organic ecosystem capable of interacting in a very dynamic way with any resource of interest provided by the operating system.

That’s why this configuration can be seen (IMHO) as an Emacs/Elisp distribution.

Finally, Org-mode is used to write and organize the configuration (src/eos.org) in a literate programming format, meaning it contains Elisp source code blocks - that will be tangled generating the src/init.el final script - and the referent documentation.

Note: Throughout this document the word application refers to any elisp package or external program.

It’s important to understand that all applications with different purposes, made in Elisp or not, pass, in a way or another, through the interpreter.

So again, application(s) implies Elisp packages or external programs.

Goal

Provide a generic INPUT-TRANSFORM-OUPUT bridge between the human mind and the machine resources.

Features:

Just one major language (Elisp) to conquer them all!
Information comes to you as required and not the other way around.
The same keybinds are used everywhere (learn once, use forever and ever).
The same editing capabilities are used for all applications.
The same GUI Interface (frames/window/buffers) are used for all applications.
Just one integrated development environment for all projects (independent of the programming language and tools needed to construct it):
- Appearance
- Editing
- Documentation
- Communication
- Navigation
- Completion
- Syntax/Spell Checking
- Interpretation
- Compilation
- Debugging
- Testing
- Rationalization
- Versioning
- And more, much more …
Understand that data is generic (in computer science we deal with idealized components) and can be manipulated, i.e, transformed through different paths.
Huge productivity improvements by:
- Staying focused, surfing all the time in the same pleasant/comfortable mood.
- Avoiding useless/annoying distractions.
- Being precise: Just do what was asked and nothing more.
- Decreasing the gap between a prof of concept and the final release.
- Providing tools to easily investigate any process/procedure of interest.
Intern communication (pipes, IPCs, data streams, sockets, you name it) between peers are transparent, resulting in a very practical, very convenient integration for all modules and resources available:
- Packages
- Applications
- Buffers/Windows/Frames
- Processes
- Sockets
- Files
- Etc …

Dependencies

Cask
Emacs >= 26.3
Elisp Packages
- Listed on: .gitmodules
Non-elisp Packages
- Ag, The Silver Searcher
- Global
- Etags
- Aspell (or Ispell)
- Compton
- Transset

Tested on

FreeBSD 12.1 RELEASE
Debian GNU/Linux 10

Installation

NOTE: The installation script is incomplete and broken do not use it!

Download and execute the installation shell script (SH POSIX), the example below uses curl.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/esac-io/eos/master/scripts/install.sh)"

Steps performed by the script:

Check dependencies
Clone eos and sub-module repositories (TODO!)
Backup .emacs.d directory
Byte compile third-party Elisp packages (TODO!)
Tangle source code from src/eos.org to init.el
Byte compile init.el script
- Call make passing the right Makefile to it.

Usage

Using this Emacs configuration isn’t different from using vanilla Emacs itself with a “few” reforms. As such, the official Emacs tutorial is a great way to understand a little bit of its universe.

So, open Emacs and press C-h (the help map prefix) and press t to evaluate help-with-tutorial function that will start the interactive tutorial.

Enjoy your late nights :)
Note: The main purpose of the Emacs tutorial is teaching you

the most important standard Emacs commands (or functions) and the mapped keybinds used to trigger then.

Keybinds

Basically, new prefix maps are created for the most commonly used minor modes and their functions are mapped within their respective maps.

After that, the prefix maps will be placed in the Ctl-x-map prefix, resulting in the standardization of commands (functions) access sequences - keybinds or chords.

For the sake of sanity a lot of keybinds have been cleaned up, It’s preferable (IMO) to have a small set of keybinds, consisting only of the most used ones, providing a more stable and less error prone overall usability.

When ‘exotic’ functions must to be called, just use execute-extended-command binded to M-x, also known as the minibuffer.

Note: The minor-mode-map-alist was completely erased, this was proven to be a huge pain relief resulting in a considerable productivity gain.

For more information checkout the Cleanup section at src/eos.org.

Basic

If you do not understand the terminology of the tables below, it is advisable to read the emacs keybinds manual.

Fundamental

Keyboard	Emacs Notation	Description

Alt	M-	Meta Key
Crtl	C-	Command Key

Keymaps

Keymaps are data structures that hold key sequences (chords) and map/trigger commands (elisp functions).

Keymap	Prefix Key	Available	Description

Global-map	C- and M-	Always	Generic Actions
Ctl-x-map	C-x	Always	Generic Actions
<Minor-mode>-map	C-x <key>	Always	Minor Mode Actions
<Major-mode>-map	C-c	Maybe	Major Mode Actions

Help

To verify what keys are mapped use M-x describe-bindings RET or C-h b. It’s possible to restrict the search using C-h or ? post-fix for a specific map, e.g:

Keybind	Description
C-h C-h	help-map help
C-c C-h	<major>-mode-map help
C-x C-h	ctl-x-map help
C-x l ?	<minor>-mode-map help

C-x

New keymaps are defined to hold the most common/used commands (elisp functions). They are divided according to their behavior classification:

Prefix Keymap	Prefix	Description

eos-files-map	C-x f	Files
eos-window-map	C-x w	Windows
eos-pm-map	C-x p	Projects
eos-sc-map	C-x e	Errors
eos-tags-maps	C-x t	Tags
eos-docs-maps	C-x l	Library/Docs
eos-utils-map	C-x c	Utilities
eos-ac-map	C-x TAB	Completion

C-c

Some maps will be only used in specific modes, e.g, cc-mode:

Mode	Keymap	Prefix	Description

C/C++	rtags-map	C-c r	Rtags

Global

Not all keybinds will be listed here, just the keybinds that have changed from the standard and the most used ones.

Remember that you can always call the functions C-h k (describe-key) and C-h b (describe-bindings) to inquire this information.

Keymap	Keybind	Function
Global	C-a	back-to-indent-or-line
Global	C-M-v	scroll-other-window
Global	C-M-y	scroll-other-window-down
Global	M-i	indent-region-or-buffer
Global	M-c	comment-or-uncomment-region
Global	M-j	clone-current-line-or-region
Global	M-n	transpose-lines-up
Global	M-p	transpose-lines-down
…	…	…

Packages

Packages are installed as git sub-modules (see gitsubmodules(7) - man pages for more information) and they are listed on .gitmodules file.

Adapt

If you want to modify any aspects (or extend) this configuration without touching the /src/eos.org, just edit/add your own Elisp code inside /src/trash.el.

Note: src/trash.el will be the last script loaded by /src/trash.el.

Advices

Do one thing and do it well (Unix philosophy).
If something is bothering you, fix it!
Global behavior aways available and static.
Few keybinds sets.
Repeat keybinds postfix for mode-specific commands according to their logical classification.
Use the same action flow logic, for the same class of commands.
Use as few modules (packages) as possible and always try to use modules already installed on Emacs to meet your needs. If you can withdraw a module, do so! Most of the time it takes little or no effort, and the gain is considerable. So, be alert to identify these situations!
Prioritize Emacs’s native packages (builtin) over third-party ones. If any demand comes to light, try to solve it with these packages first, then third-party packages already installed and finally (if it’s a huge one) the internet. Sometimes a little extension on these blotted-packages sets is everything that’s needed to bring a new feature to life or solve an issue.
Successive refinements: in constant refactoring! Always improve, never fear the winds of change!
Have fun!

FAQ

Q: Mac/Windows will be supported any time soon?
A: Nope.
Q: Why don’t you use evil/hydra/which-key/use-package/etc?
A: It is not just a matter of taste, it is simply because they get in the way and disturb the desired transformation from properly occurring, and I prefer a more direct/effective approach. Remember that’s the way I think, you can add these modules on your own and make your life a little more miserable, be my guest!
Q: And what about helm/ivy/counsel/swiper?
A: Well, Icomplete is minimal (works very similar to the beloved dmenu), builtin, generic, fast, less intrusive, and fulfill all my needs. Thanks, Prot, for bringing this forgotten package to light!
Q: Do you think Emacs has a future?
A: Maybe, the concept of the lisp machine as the main interface to be used to do any task is great, however the execution side of it, is in a complete mess state, open the info buffer and you will see what I mean. This lack of organization makes everything more difficult than it has to be, and one day - if we don’t do anything - the whole project may become unmanageable. Sad, dudes! Let’s DO SOMETHING about it!
Q: Why won’t just use Doom/Centaur/Spacemacs or any other distribution?
A: Because they are bloated with a lot of useless packages. It’s easier (IMHO) to adapt vanilla Emacs and learn Elisp - once and for all (a work in progress)!
Q: Do you think that everyone who uses Emacs should write their own configuration file (init.el)?
A: For sure! It’s fun like exploring mystical dungeons and fearlessly slaying some dragons. The reward? Walking over the rotten and stinky carrion of your enemies defeated by your will, and contemplating the symphony formed by the cry of despair whispered by their widows.
Q: Pull requests will be accepted in this repository?
A: Probably not, Emacs configurations are too personal. Fork it or copy any snippet of code that you like: MIT License, mate!

References

LICENSE

MIT

EOF

And you don't seem to understand
A shame you seemed an honest man
And all the fears you hold so dear
Will turn to whisper in your ear

Duvet, Boa

yagossc/eos

EOS