VLM

Just another Emacs configuration written in org that has a simple goal: be just a configuration file, i.e, set custom values and hooks for the libraries of interest.

Some people have started to refer to Emacs as a LISP MACHINE. It is not strictly a lisp machine because, clearly, it is a software program and not a physical computer, but as that line starts to blur it seems like a useful epithet for Emacs, because these days it looks more and more like an OS.

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/vlm.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 elisp developer (the user developer concept), there’s no way around it.

Unfortunately some people find this overwhelming, but others find it formidable - myself included!

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, a virtualized LISP MACHINE on top of your operating system.

LISP MACHINE is a generic term. A Lisp Machine is a computer whose operating system and applications are written in Lisp.

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

Finally, Org-mode is used to write and organize the configuration (src/vlm.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 library 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 library or external programs.

Goal

Use EMACS as a VIRTUAL LISP MACHINE, i.e, the main dynamic interface to perform data transformations, the only bridge between the human mind and the machine resources.

Mantras

Data driven/oriented design: is all about the data and how its organized to do less transformations as possible when solving a given problem, resulting in a great degree of optimization and simplicity.
No late time decisions are allowed.
Always go in the opposite direction: SCALE DOWN, i.e, use less resource as possible!
Simple is better.
Less is more.
For the LISP MACHINE everything is a just data to be s-expressed and evaluated.
Lazy load (autoloads) everywhere.
Byte-compile warnings are equal to errors: not allowed!
Use as few libraries as possible and always try to use libraries already installed on Emacs to meet your needs. If you can withdraw a library, 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 libraries (builtin) over third-party ones. If any demand comes to light, try to solve it with these libraries first, then third-party ones already installed and finally (maybe, A HUGE ONE) the internet! Sometimes a little extension on these blotted-code-base is everything that’s needed to bring a new feature to life or solve an issue.
If something is bothering you, fix it, right now!
Few mapped keybinds as possible! Implies the constant usage of the minibuffer to eval less often used commands, but a huge pain relief, dwim style!
Use the same action flow logic, for the same class of commands.
Global behavior always available, do not change states (erase this silly idea), we have just one state and its very dynamic!
Successive refinements: in constant refactoring! Always improve, never fear the winds of change!
I must not fear. Fear is the mind killer…

Conclusions

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 libraries and the resources available:
- Libraries
- Applications
- Buffers/Windows/Frames
- Processes
- Sockets
- Files
- Etc …

Dependencies

Emacs >= 27
Elisp Libraries
- TODO: List Libraries!
Elf Binaries
- Ag, The Silver Searcher
- Global
- Etags
- Aspell (or Ispell)
- Compton
- Transset

Tested on

EMACS : 26.3, 28.0.50
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/lambdart/vlm/master/scripts/install.sh)"

Steps performed by the script:

Check dependencies
Clone vlm and sub-module repositories (TODO!)
Backup .emacs.d directory
Byte compile third-party Elisp packages (TODO!)
Tangle source code from src/vlm.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/vlm.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

vlm-files-map	C-x f	Files
vlm-window-map	C-x w	Windows
vlm-pm-map	C-x p	Projects
vlm-sc-map	C-x e	Errors
vlm-tags-maps	C-x t	Tags
vlm-docs-maps	C-x l	Library/Docs
vlm-utils-map	C-x c	Utilities
vlm-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
…	…	…

Libraries

TODO: List the libraries in libraries.org file.

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 disturbing the desired transformation to properly occur, and I prefer a more direct/effective approach. Remember that’s the way I think, you can add these libraries 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

ercdude/eos

VLM