PEL -- Pragmatic Emacs Library

• Tired of writing Emacs configuration code? 🤯
• Afraid of or ever declared .emacs bankruptcy? 😰
• Don't want to spend your time writing Emacs Lisp code? 😳 [1]
• Need to quickly access help now and later on specific topic? 🤔
• Want to learn Emacs and try several built-in and external packages? 😇
• Want a fast single process startup even with a large number of external packages installed? 😃
• And also want to run an Emacs daemon(s) with text and graphics clients on linux and macOS like a pro? 🥳

PEL might be for you! Then go ahead, install it [2] or update it [3] !

➣ Supports Launching Emacs from GUI and Shell

• PEL supports terminal Emacs launched from a shell and graphics Emacs launched from a shell or a GUI program like Windows Explorer, macOS Finder, Linux file managers, etc...

➣ Short Emacs and Emacs Client Launcher Scripts

• Want to start Emacs as an independent process or a text or GUI client to the Emacs daemon? PEL provides simple shell scripts for all of that (for macOS and Linux). See Using the Emacs daemon and clients for more info and the related quick shortcut installation script.

➣ Emacs Fast Startup

• Speed Emacs startup further with PEL fast startup mode command (see also ⅀ Fast Startup PDF [5]). PEL supports 2 different Emacs startup operation modes:
  • The normal startup mode, using Emacs' standard package.el package manager with PEL's extensions that provide customization-driven package management built on Emacs easy customization to pick and chose packages and behaviours, all without having to write Emacs Lisp code. PEL enhances Emacs customization system: PEL provides keys to quickly access customization groups of Emacs built-in and external Emacs Lisp libraries even if they are not even loaded.
  • The fast startup mode. It can achieve 0.1 second startup with over 230 external packages, see [7]. In fast startup you can use all external packages you have already installed in normal startup mode but now Emacs starts much faster. In fast startup PEL does not support download and installation of new external packages but just return to normal mode to do so. PEL provides 2 commands to switch modes:
    • The pel-setup-fast (<f11> M-S f) activates the fast startup mode. It bundles all external packages that use a single directory inside a single directory to reduce Emacs load-path and sets up your Elpa directory for a fast startup.
    • The pel-setup-normal (<f11> M-S n) restores the normal Emacs setup with package management capabilities and PEL's automatic package installation via customization.
• PEL supports Emacs 26 and later.
  • For Emacs 27 and later the pel-early-init-template user-option (which defaults to example/init/early-init.el) allows you to identify a PEL-compatible early-init.el file that PEL edits to control whether fast startup and package-quickstart feature are used.
    • PEL provides the pel-setup-with-quickstart command (<f11> M-S q) to create and refresh all the package-quickstart files [8] and pel-setup-no-quickstart (<f11> M-S M-q) to disable it.

➣ Customization Driven Package Management & Configuration

• PEL uses Emacs customization facility to control everything:
  • the selection,
  • installation and
  • configuration of packages,
  • the activation of various major and minor modes,
  • the improvement of behaviour of various major and minor modes,
  • the use of various features provided by PEL.
• PEL saves your customization data inside a file separate from your init.el file, providing an extra degree of freedom and control. This also gives you the ability to easily revision and clone your Emacs environment to other computers.
• PEL provides enhanced and easy access to relevant customization buffers for your specific context. Each supported topic or major mode context has a PEL prefix key and each supported major mode uses the <f12> key as the main prefix key. For instance in a C buffer, use <f12> <f1> to access the C-specific PEL PDF, <f12> <f2> to access the PEL customization buffer to activate C features, and f12> <f3> to the customization buffers controlling the major mode and related features.
  • Unlike default Emacs behaviour, PEL can open customization buffer for a group even if it is not yet loaded. If they are not loaded PEL will load them for you after prompting. Even if the package's code was not written to support auto-loading of customization variables.
• The classical way to control Emacs behaviour has been to write Emacs Lisp code to set variables. Although you can still do it with PEL you will benefit from PEL's integration better if you control all via the customization buffers and customization files. You can modify the behaviour by applying customization modification to test your changes and then save them to a file once you are happy with it.
• PEL supports the ability to have 2 independent customization files: one for Emacs running in terminal mode and another for Emacs running in graphics mode. PEL supports two sets of elpa directories to store the packages used for each mode when this independent dual customization mode is used. PEL provides the pel-setup-dual-environment command to activate this. Follow the installation instructions and see the ⅀ Customize PDF for more details.
  • A PEL compatible Emacs init.el is available for you to use right from the beginning. Instructions are inside. You can use it as is or modify some of the options.
  • For Emacs ≥ 27, PEL also provides a PEL compatible early-init.el. Instructions are inside. PEL will automatically install it if you want to use Emacs package quickstart feature available on Emacs ≥ 27. You can also modify it and add your own code. Instructions are located in the file.
  • PEL comes with samples of Emacs custom files you can use with PEL to quickly activate features. After following the PEL installation steps, Copy one of these files into your ~/.emacs.d/emacs-customization.el file then start Emacs and watch PEL download, install and activates the packages identified in the file you selected.
  • If you want to manage 2 set of customization files and package directory, one for Emacs in terminal mode and another for Emacs in graphics mode, use the pel-setup-dual-environment command (or <f11> <f2> M-d) to activate dual independent customization. It will create the required customization files.

➣ PEL Package Integration and Enhancements

Emacs gets its power from the large set of built-in and external packages available for it. A large number of external packages are available from package repositories like GNU Elpa, MELPA. There are also Emacs Lisp files available on Github and Gitlab. PEL provides access to a growing number of these packages as described in the next section.

One of PEL's goals is to enhance the cohesion and the integration of these packages to provide a more pleasant and customizable user experience. PEL implements various convenience commands, easy-to-remember key bindings and glue control code to enhance several minor and major modes, allowing behaviour selection through customization and PEL use-option variables.

Some of the improvements created for PEL are fed back to the original project(s) but it's available inside PEL if the code has not yet been merged in the original project.

PEL also implements various template-driven text insertion for various programming and markup languages.

As PEL evolves the goal is to support for programming languages will increase and each fully supported programming language will come with a topic-oriented help PDF, enhanced electric key behaviours, enhanced navigation integrating various packages, etc...

➣ Automatic Download, Installation and Setup of External Packages

• In normal mode, PEL controls the download, installation, configuration and activation of 262 top-level [4] external packages through the use of easy-to-setup customization user-options that have a name that start with the "pel-use-" prefix.
  • Once activated by a PEL user option, PEL installs the newly activated packages on initialization (or when Emacs starts) from GNU Elpa, MELPA, and simple GitHub or Gitlab repositories even when the files have not been setup as an elpa-compliant package. PEL provides configuration logic and hooks where needed.
  • Use the pel-cleanup command to remove deactivated packages not requested by PEL user-options, moving those packages from the elpa or utils directory to the corresponding attic directories for backup and later re-activation.
  • PEL controls the activation and loading of selected packages, with emphasis on:
    • reducing Emacs initialization time to a minimum [7] in all modes,
    • providing key bindings when Emacs is running in both graphics mode and terminal mode,
    • adding extra commands that complement Emacs and external packages.
• PEL integrates these packages and adds a large number of key bindings that mostly do not interfere with the standard Emacs key bindings (except for a very small few documented ones).

➣ Extends Emacs Documentation

• PEL provides 167 PDF topic-oriented reference sheets [6] packed with symbol annotated, colour coded key bindings and command descriptions, with hyperlinks to Emacs manuals, external packages, articles and other useful references.

  • See the PEL Index PDF [5] as a starting point. For the best user experience, use a browser, like Firefox, that can render the PDF inline (as opposed to downloading it) so you can use the links quickly. Inside Emacs use <f11> <f1> to open the PEL Index PDF and then navigate from it, or use <f12> <f1> to open the PDF describing the major mode of the current buffer and its key bindings.
    • Some major modes also support the opening of a language-specific PDF. This is done by using a key prefix: C-u <f12> <f1>. For example this now opens a PDF on zsh when the command is issued from a buffer editing a zsh script, or a GNU Make PDF from a buffer editing a make file in GNU Make mode.

• PEL's Manual describes PEL features in more details. See:

  • How to install PEL,
  • How to setup GUI Emacs environment to control GUI launched Emacs PATH and other environment variables easily with a fast starting Emacs,
  • PEL setup commands for dual customization and fast startup mode,
  • PEL initialization command and PEL cleanup command,
  • PEL Customization,
  • PEL Key Bindings,
  • PEL convenience features with PEL commands that extend several aspects of Emacs.

  Warning

  GitHub presently fails to render several reStructuredText files to HTML. They are currently working to resolve this issue.

➣ PEL Convenience Commands

• PEL provides over 628 extra commands. PEL commands extend the packages it supports and provides some of its own features. Some commands are only available for a given OS, most are accessible in every OS.
• PEL provides 10 specialized Hydra key bindings when the pel-use-hydra and the topic specific user-options are activated.

➣ Credits

PEL would not exist without the great software available for Emacs. Some of them are listed in the Credits section of the manual but the list is unfortunately incomplete as it grows continuously when PEL supports new packages. The external packages are identified in the PDF tables with the box symbol: 📦 with hyper-links to the author's project.

➣ What's New

PEL is still evolving, with new packages being integrated, new documentation created and new features developed. The evolution is described in the NEWS file.

Questions, comments, constructive criticism, suggestions and requests are always welcome. Drop me a note in the wiki or in the discussion board!

Notes

[1]

Writing Emacs Lisp code is actually quite fun and rewarding. Lisp is a powerful programming language and Emacs opens up the door to that world if it's foreign to you. PEL should ease the introduction and you may decide to go your own way later. For those that prefer to stay away from Emacs Lisp and concentrate on other tasks you can use PEL and configure Emacs using its powerful customization system.

[2]

Unfortunately PEL installation is manual but it's not difficult. Detailed instructions for installing PEL are located inside section 2 of PEL manual. You essentially have to clone PEL's repo, start with a fresh ~/.emacs.d directory, open Emacs twice and run make in the PEL directory to byte compile PEL's files. You will have to update the init.el and early-init.el if you want to modify some options. And you may want to use some canned customization files. PEL installs and configure what you activate through customization. See PEL manual table of contents to move around the manual.

[3]	The instructions for updating PEL are located inside the Updating PEL section of the PEL manual. Essentially what's required is to get the latest changes using Git (with git pull) and then run make again.

[4]

An external package may have dependencies. The dependencies are also installed. PEL currently provides access to 262 top-level external packages. The actual number of packages is larger when counting their dependencies (currently 48 extra packages installed as dependencies). From within PEL execute the pel-package-info command with prefix argument to get a full report (or just type C-u <f11> ? e ?). Also notice the short report printed at the end the make-driven build of PEL.

[5]

(1, 2) All PEL PDF files have a large number of hyperlinks to other PDF files, Emacs manual pages, external packages and articles. Use a browser that is capable of rendering PDF files for the best user experience. The Mozilla Firefox browser does an excellent job at it since its version 78, under all operating system and is highly recommended.

[6]	The source of the PEL PDF files is a single macOS Number spreadsheet file. It's also available in the Git pel-pdf-spreadsheet repo. I would have liked to find a way to create this with a markup flexible enough but I did not find one. Let me know if you know one that can build the same output.

[7]

(1, 2) Fast initialization: PEL code uses all the techniques to improve initialization speed. By default it starts quickly, delaying code as much as possible. On my 2014 iMac running macOS Mojave in terminal mode running Emacs 26.3 I get the following startup time in normal startup mode (and without package-quickstart): with 182 packages, benchmark-init reports about 0.4 second startup-time, with 239 packages, benchmark-init reports about 0.6 second startup-time, see the benchmark-init report for it Activate PEL fast startup mode to experience much faster initialization times: with 239 packages, in fast startup operation mode, benchmark-init reports about 0.1 second startup-time, see the benchmark-init report for that. The time reduction of fast startup mode depends on the number of packages that can be bundled by PEL. Those that have all their files in the same directory can be bundled. With PEL it's possible to reduce this further by removing packages you do not need, without loosing their configuration: go to normal startup mode, disable un-required packages by setting their corresponding pel-use- user-option to nil, run the pel-cleanup command (with M-x pel-cleanup). It will disable those packages by putting their packages inside an attic directory where you can retrieve them later. If the removed packages are multi-directory package their removal will speed-up initialization in normal and fast-startup mode, otherwise it will only speed it up in normal mode.

[8]

Package Quickstart Support: The pel-setup-with-quickstart command creates the package quickstart files and the early-init.el file if it's not already present. Emacs package-quickstart-file user-option identifies the name of your package quickstart file. When using PEL's independent customization for terminal/TTY and graphics Emacs PEL manages 2 package quickstart files: one for the terminal/TTY mode with that name and one for the graphics mode which has "-graphics" appended to its name.

[9]

PEL Commands: PEL implements its own commands. These complements the packages PEL supports and also provide a layer that unifies mechanisms implemented by several built-in and external packages. Some PEL commands act according to the key sequences that invoked them. For example, the pel-help-pdf command is bound to <f11> a <f1>, <f11> b <f1> and several others and the <f12> <f1> key sequences of several major modes. The command detects the key sequence and the context to identify which PEL PDF to open. PEL currently implements 628 interactive commands. Some are always loaded. Several are auto-loaded when needed. This count excludes the number of template commands that are dynamically constructed and loaded only for major modes, such as Erlang, that support extensive tempo skeleton templates. Navigate the PDF files starting from the PEL Index PDF to get more information.