Skip to content

Latest commit

 

History

History
8420 lines (6197 loc) · 345 KB

pel-manual.rst

File metadata and controls

8420 lines (6197 loc) · 345 KB

PEL -- Pragmatic Emacs Library

URL:https://github.com/pierre-rouleau/pel/blob/master/doc/pel-manual.rst
Project:PEL Project home page
Modified:2024-07-26 22:48:43 EDT, updated by Pierre Rouleau.
License:

Copyright (c) 2020, 2021, 2022, 2023, 2024 Pierre Rouleau <[email protected]>

You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Table Of Contents

1   Overview

PEL is an hybrid package. It is:

  • an Emacs key binding documentation project with over 130 PDF topic-oriented reference sheets packed with symbol annotated, colour coded key bindings and command descriptions, with hyperlinks to Emacs manuals, external packages, articles and other useful references.
    • access these PDF files directly from Emacs using the pel-help-pdf-select command bound to <f11> ? p, or with the <f12> <f1> key sequence of supported major modes. PEL can open the local PDF file or open them in your default web browser. See the Help PDF for more details.
    • You can also open the PEL Index PDF that lists all the PEL PDF files and provides a good overview of what is available and a good starting point. For the best user experience use a good web browser like Firefox [1] version 78 or later that can render the PDF files inline.
  • a collection of PEL convenience features which:
    • are implemented in several mostly independent files (which can be used independently if you want to use just a couple of PEL features),
    • have key bindings mostly using the function keys to provide key map trees that do not interfere with standard Emacs key bindings,
    • provides access to over 230 external Emacs packages via PEL Customization. You select what you want to use then let pel-init download, install and configure them, dealing with dependencies and key binding activation.
      • PEL conforms to the Emacs easy customization system and reduces your need to write custom Emacs Lisp configuration code,
      • PEL optionally supports two customization files: one for Emacs running in terminal/TTY mode and another one for Emacs running in graphics mode.
    • makes extensive use of auto-loading and deferred loading techniques to speed up Emacs initialization time.
    • provides dynamic control of several packages and their commands. For example, PEL support both auto-complete and company auto-completion packages, providing commands to activate one mode in a buffer and another mode inside another and while preventing dual use in a buffer.
    • PEL key bindings avoid modification of most Emacs key bindings. Instead PEL uses several function keys (F2, F5, F6, F11 and F12) as key prefixes as described in the section titled PEL Function Keys Bindings. It also uses the F9 key as a prefix to enter Greek letters when pel-activate-f9-for-greek is activated and for some external packages.
    • PEL features are implemented by a set of small Emacs Lisp files and that deal with several aspects of Emacs like windows and frame, scrolling control, buffer, navigation, opening files or web pages from file name or URL at point, numeric keypad handling, etc...
  • a mechanism that provides two Emacs startup modes:
    • the normal startup operation mode which corresponds to the normal way Emacs is used where the package.el package manager is used by PEL and where it is possible to:
      • use PEL's Emacs customization to select features and where the pel-init command downloads and installs the external packages required for those features,
      • disable features no longer needed and remove them by executing the pel-cleanup command, reducing startup time accordingly.
    • the fast-startup operation mode that does not allow installation of any new package but provides a much faster Emacs init startup time, even with Emacs 26.3. In this mode, PEL bundles all external Elpa packages that have files in a single directory, reducing the number of elpa directories which reduces Emacs init startup time furthermore. With it its possible to reduce Emacs startup time to 0.1 second even when using over 230 external packages with no loss of functionality (except ability to install new packages).
      • PEL also supports the package quickstart mechanism for Emacs 27 and later.
      • PEL use techniques similar to those used by use-package but goes further by providing the extra mode of operation. The use-package describes being able to use over 80 packages with a start time of 2 seconds. With PEL's fast startup of 0.15 second for 238 packages, on Emacs 26.3, that's about 40 times faster!

To use PEL you must set your Emacs initialization file appropriately. If you are using Emacs ≥ 27 with quick-startup you must also setup your early-init file appropriately.

The section titled How to install PEL below will guide you through the process.

[1](1, 2, 3, 4, 5)

I highly recommend the Mozilla Firefox browser. Firefox version 78 or later renders the PDF files in the browser window by default, a very useful feature when browsing PEL PDF files. PEL provides a user-option (pel-browser-used) to force the use of Firefox to open PEL PDF files even when you use another browser as your default browser for that reason.

In 2021 Firefox is a highly rated web browser. See the following articles:

1.1   The reason for PEL

PEL attempts to make Emacs easier for new users by providing already made configuration that is controlled by Emacs customization system. It reduces the need for writing Emacs Lisp configuration code for the packages it supports and incorporates the knowledge inside files that can be byte-compiled for further speed enhancements.

There are several great packages for Emacs. Some are easy to install, others require more knowledge, knowledge that is often not readily available to new users and will require a time investment you may not be willing to make.

Instead of having to write Emacs Lisp code inside an Emacs init file for each new package you want to use, you can use PEL, select the features you want via PEL Customization and then execute pel-init to activate them. PEL has the logic for configuring the packages it supports. In some cases it also contains the logic to install the package if it is not already installed.

PEL essentially came out as a desire to be able to use an Emacs configuration on several systems, both in terminal (TTY) mode and in Graphics mode while trying to keep Emacs initialization as fast as possible and reducing the repetitive writing of package initialization code.

I started writing PEL while learning Emacs, Emacs Lisp and various packages. PEL encapsulates some knowledge about various tweaks to use and configure several built-in Emacs features and third party packages.

I also created a set of PDF topic-oriented reference sheets that each list and describe a specific topic, the commands and key bindings related to that topic and a topic specific entry inside this manual that also refers to the corresponding PDF file. These are all accessible via the PEL Index PDF. There are several topics; Emacs navigation, Emacs buffers, windows and frames, how to undo, redo, work with Emacs Lisp, etc... See the Key Bindings Documentation section. The commands and key bindings described in those PDF files include what is provided by the plain vanilla GNU Emacs as well by the third party packages PEL integrates and the PEL implemented commands.

1.2   PEL Goals

  • Ease introduction to Emacs.
  • Simplify and speed up Emacs initialization and configuration.
    • Minimize Emacs initialization time even when a large number of packages are present on the computer.
    • Minimize the amount of Emacs Lisp code to write inside Emacs init file to support various external Emacs packages.
    • Provide all logic necessary to install and configure external Emacs packages.
  • Provide easy to remember key bindings via a key binding tree, key prefixes and the use of key choice visualization with package such as which-key, especially for commands that are seldom used.
    • Keep as many standard Emacs key bindings as possible.
  • Document what's available: the key bindings, the special considerations, the documents to read for further learning.
  • Allow use of PEL even when someone has an extensive Emacs init file.
  • Add support for several programming languages integrating many packages that support these programming languages. Support for C, C++, Rust, Go, Python, Erlang, Elixir, Haskell, OCaml and several are planned (but... no schedule yet!).
Note:
PEL will grow with time, incorporating more documentation, support for more Emacs packages related to editing and programming tasks. Don't hesitate to report problems and recommend better ways!

1.3   Using Portions of PEL Manually

If you prefer not using PEL's key bindings you can override them. You can also just use the PEL features you want and create your own key bindings. In that case, don't call pel-init, require the respective PEL source code file and create your own key bindings. Most PEL files are listed in each of the corresponding PEL Convenience Features section but the manual is not yet complete and will also evolve over time.

2   How to Install PEL

PEL is not yet available through MELPA (Milkypostman's Emacs Lisp Package Archive) or any Elpa-compatible Emacs package archive. It might be one day, although the nature of the PEL project might not be compatible with MELPA or ELPA.

Therefore semi-automated installation instruction are detailed in the following sections.

Requirements

Before you can install PEL, you need to ensure that you have the required tools. They are described in the following sections:

  1. Install Emacs 26.1 or later. If you are new to Emacs, the easiest is to use one of the latest stable releases.
  2. Install other required command line tools

Installation Instructions

The fully detailed instructions are described in the following sections:

  1. Clone the PEL Git repository on your computer.
  2. Prepare Emacs Initialization directory where lots of Emacs files will go.
  3. Byte Compile PEL Files. PEL features require byte-compilation.
  4. Further Configure the init.el File
  5. Learn PEL Customization mechanism you will use to configure Emacs.
  6. Optional Installation Steps you may want to do now or later

2.1   Install Emacs 26.1 or later

Install a version of Emacs you can run from the command line. It will be used to build PEL later. Once PEL is built on your system you can use either a terminal based version of Emacs or a graphical version of Emacs with PEL.

To check if you have Emacs on your system, open a shell and execute the following commands:

  • which emacs to see if Emacs is available.

    • On macOS, if this is /usr/bin/emacs, you most probably have the old version of Emacs that Apple installed, and that is most probably not version 26.1 or later.

  • Check the version of Emacs you have with the following command line:

    emacs --version

Make sure you have Emacs version 26.1 or later. If not, install it.

2.1.1   For macOS

You can use Homebrew, a command line utility, to install a command line version of Emacs.

  • See Homebrew home page for how to install Homebrew.
  • Once homebrew is installed, you can use the following commands inside a terminal shell:
    • brew search emacs to list Homebrew package names that include "emacs".
    • brew info emacs to see what version of emacs is available.
    • brew install emacs to download and install Emacs.

2.2   Install other required command line tools

If the following tools are not already installed on your system install them now:

  • git
  • make

You should also install spell checking utilities. There are several. The default is ispell. It's best to install it at the beginning if it is not already there, so also install:

  • ispell

If you want to use the fast vterm shell into Emacs, you also need to install:

  • cmake
  • and possibly libtool.

2.3   Clone the PEL Git repository

Description:

Clone the PEL's Github repo somewhere in your home directory but outside your "~/.emacs.d" directory. The instruction assumes that you store it inside "~/projects" to create "~/projects/pel".

Note:
You could use anything, but then you'll have to remember to update the instructions appropriately, replacing "~/projects" with whatever you want to use.

The commands will create the "~/projects/pel" directory tree with all PEL's files inside it, including all PDF topic-oriented reference sheets that document the key bindings of Emacs and the libraries you can activate with PEL.

Do this:

Open a terminal shell or command line window and execute the following commands:

cd
mkdir projects
cd projects
git clone https://github.com/pierre-rouleau/pel.git

2.4   Prepare Emacs Initialization directory

Description:

There are several ways to set up Emacs initialization file.

You will have to store several Emacs-related files in your system:

  • PEL itself,
  • Emacs init file, init.el.
  • Emacs customization file,
  • Emacs bookmarks file,
  • Emacs abbreviation files,
  • External Emacs Lisp libraries downloaded from Elpa-compliant sites like ELPA, MELPA or MELPA-STABLE,
  • External Emacs Lisp libraries from the EmacsAttics or EmacsMirror that are not Elpa-protocol compliant are supported by PEL and must be stored into the utils directory.
  • etc...

It is best to use the "~/.emacs.d" directory where all of these files will be stored.

Note:

If you currently store all your emacs configuration inside the ~/.emacs file, rename that file and keep it. The information it contains will have to be moved somewhere else, most probably inside the ~/.emacs.d/init.el if PEL does not already handle your logic.

Windows users:
Under Windows, your ".emacs.d" directory should be stored inside your HOME directory. See Emacs Windows init location FAQ for more information.

Do this:

  • Open a terminal shell or command line window and execute the following commands:
cd
emacs

This should open a graphical version of Emacs. If that does not work check your Emacs installation. You may also want to try to execute Emacs in terminal mode:

cd
emacs -nw
  • Close Emacs: type C-x C-c. That is hold the control key and type x followed by c and then release the control key.
  • If it did not already exist, this should have created the ~/.emacs.d directory. If not create it using the mkdir ~/.emacs.d command.
  • Copy PEL's example/init/init.el into your ~/.emacs.d using the following shell commands (assuming you stored PEL inside ~/projects/pel:
cd ~/project/pel
cp example/init/init.el ~/.emacs.d/init.el
  • Run emacs again:
emacs

This time PEL initialization file should have taken over.

  • PEL will create missing files and will access MELPA to install the popup and which-key packages.
  • PEL will then display a warning message to inform you about the fact that Emacs customization file did not originally exists before PEL created it. This message is expected when installing PEL and should not show up later. You should see something like this:
res/pel-install-01.png
  • Close Emacs (with C-x C-c). Open it again. Now you should see no warnings, just the standard Emacs screen:
res/pel-install-02.png

If you still see errors, and if that error contains something like:

File is missing: Cannot open load file, No such file or directory, pel

Emacs cannot find the pel file. If you did not clone the pel repo into your ~/project directory you now have to edit the ~/.emacs.d/init.el file.

Look for the following text and change the path of the pel directory inside the string:

;; OPTION B:  if PEL is stored somewhere else change the following value.
(defconst pel-home-dirpath-name (expand-file-name "~/projects/pel")
  "Directory where PEL Emacs Lisp source files are stored.")

Update the string inside the defconst call; identify where you stored pel. Then save the updated ~/.emacs.d/init.el file (with C-x C-s) and exit Emacs (with C-x C-c).

Start Emacs again, now all should be fine.

To activate PEL you must byte-compile all PEL Emacs Lisp source code. This is described in the next section.

2.5   Byte Compile PEL Files

Description:

PEL features require byte compilation of PEL's Emacs Lisp files. Not only it provides faster execution but byte compilation allows PEL Emacs Lisp macros to properly setup the environment.

Use the provided Makefile script to byte-compile all required PEL Emacs Lisp source code files located in the pel directory. It will also run some regression tests. Nothing will be downloaded during this byte compilation.

Do this:

cd ~/projects/pel
make clean
make

The make script should terminate with an exit code of 0 and you should see no error or warning.

In case of Errors:

If the make script stopped at an error, check the following:

  • Check the content of your Emacs user directory. Several files and directories are required by Emacs, some are added by PEL and some are old PEL files that should be removed. Check the list of files and directories in the section titles Emacs and PEL Files and Directories. Add missing files, remove obsolete PEL files.
  • Run make again.

If the problem persists, or if you see an error or a warning during the build or when you start Emacs, please create an issue describing the problem and your environment and I will get to it.

At this point you can use Emacs with PEL

You should have a working version of PEL with all PEL files byte-compiled for efficiency 😅!

Quick Test PEL

PEL download and activates the which-key external package by default. PEL uses the F11 key extensively.

  • Make sure your environment provide access to that key. In terminal mode you may have to configure your terminal application to prevent it from using the F11 key.
  • Once that's done open Emacs in terminal mode with emacs -nw from a shell, or open Emacs in graphics mode with emacs, then:
  • Hit the F11 key. That's PEL main key prefix. After one or two seconds the which-key package should display the keys that can be typed after F11 like this:
res/pel-install-03.png
  • The key keys following key prefixes will be shown at the bottom of the Emacs screen by which-key (because pel-use-which-key is turned on by default) and any package(s) which-key may require.
  • Type <f11> ? p and a topic to open one of the PEL PDF files. Use tab to complete what you type. Type tab at first to see a complete list of PDF files. Or type <f11> <f1> to open the local copy of the PEL Index PDF. This file has lots of hyperlinks. They all lead to the Github-hosted raw PDF you can quickly navigate with a browser that renders PDF inline, like Firefox [1] version 78 or later. That's a quick way to navigate PEL's key documentation and access relevant information.
  • As usual in Emacs, type C-x C-c to close it.

Next Steps

To fully take advantage of PEL continue with the following steps:

  • Update any option in PEL init.el file if required.
  • Learn PEL Customization mechanism you will use to configure Emacs.
  • Improve your Emacs user experience by selecting Emacs behaviour and packages that suits your needs with the Optional Installation Steps.
    • Note that PEL comes with a set of already-made Emacs customization files that you can copy into your ~/.emacs.d/emacs-customization.el file to quickly get a taste of working with PEL. These files activate a set of user-options including several pel-use- user-options that identify packages that PEL must download, install, configure and activate.
      • If you copy one of the files from the sample/emacs-customization directory into your ~/.emacs.d/emacs-customization.el, the next time you start Emacs with PEL-supporting init file, PEL will download the associated files, byte compile them and activate the key bindings associated with them.

More information about PEL configuration is in the next section.

2.6   Further Configure the init.el File

PEL's init.el file contain the code required to run PEL with Emacs. There are values set in that file you may want to change. These are described in this section.

Use Emacs to edit the ~/.emacs.d/init.el file.

  • Start Emacs.
  • To open the file type C-x f ~/.emacs.d/init.el
  • Read the instructions located inside the User Configuration section on top of the file.
  • Use C-s OPTION RET to search for the word "OPTION" and modify the code according to what you need:
    • OPTION B: If you want to store PEL's source code somewhere else than ~/projects/pel change the name of the directory at that option.
    • OPTION C: is where you control the use of the benchmark-init package to identify what code takes time during Emacs startup. You should do this only once you feel comfortable with Emacs.
    • OPTION D: By default Emacs displays generic information about GNU and Emacs on startup. After reading it once or twice you may want to prevent this information from showing up. For that un-comment the line shown below the OPTION C text and replace the string YOUR_USER_NAME by your OS user name. On Unix-like OS, this is what the who command displays.
    • OPTION E: this is a small section of code that activates or de-activates various global Emacs settings. It starts with a commented line that disables the tool bar of Emacs running in graphics mode. If you do not want to use that tool-bar un-comment the corresponding line of code. Read the code in that section. You may want to modify some of this. However remember that PEL controls Emacs behaviour through customization, not by code invoked through the init.el file: it's best to minimize what you add the this section of code if you want to take advantage of what PEL offers and to minimize Emacs startup time.
    • OPTION F: is where you will want to store the code that used to be inside your old init.el file if you had one. However if that code was selecting Emacs behaviour and configuring packages that are already under control from PEL, its best to keep this code out of init.el and leave PEL manage it. If you want PEL to support a feature it does not please write a ticket to report it and I'll try to accommodate the request quickly.
    • OPTION G identifies a set of Emacs functions that are normally disabled because they tend to confuse new Emacs users. You can activate them here.
  • Save your modifications back to the init.el file by typing C-x C-s
  • Keep Emacs opened on your init.el file.
  • Open a new terminal shell.
    • Open Emacs in that new shell. If all is OK, Emacs should start fine and should not display any error message. If it does display an error message then something is probably wrong in your init.el file. Modify it, save the file and try again.
  • Once Emacs starts properly close all Emacs sessions. You can type C-x C-c to save all buffers and terminate all Emacs sessions.

2.7   Optional Installation Steps

The following steps described in this section are optional but strongly recommended if you want to take advantage of:

2.7.1   Further PEL Configuration

The following sections describe optional optimizations or modifications that can be done after the first complete and successful installation of PEL.

2.7.1.1   Configure Spell Checking

To use spell checking features in Emacs, you must use a spell checking program available from the command line. Emacs Ispell and Flyspell can use a Ispell-compatible program like:

If none is available on your system you will have to install it manually.

Identify the program to use in PEL customization user option variable pel-spell-check-tools. This user option allow you to define one program per Operating System. You can also identify the location of your personal dictionary file.

To quickly gain access to the customization buffer for the pel-pkg-for-spelling group where that user option is located type the <f11> <f2> $ key sequence.

For the changes to take effect, save the changes and execute pel-init (with M-x pel-init) or restart Emacs.

More information on PEL support of spell checking is available in the PEL Spell Checking Support section and the Spell Checking PDF sheet.

2.7.1.2   Disable Emacs Startup splash screen and echo area message

By default Emacs displays its splash screen on startup and displays a message on the echo area telling you about Emacs in general and the concept of free software. Once you have read this information, you may want to prevent Emacs from showing it again.

The file example/init/init.el contains the code that disables the splash screen. the code that disable the message is still commented out.

To disable it, edit your init.el file, which contain the same code. Look for OPTION D. You can search by typing C-s then the string you search for. You should see the following comment:

;; OPTION D: Don't display Emacs startup help message, at least for me.
;; This variable is treated specially.  Don't group its setting with others.
;;   Replace YOUR_USER_NAME by your systems' login user name in the line
;;   below and un-comment it:
;; (eval '(setq inhibit-startup-echo-area-message "YOUR_USER_NAME"))

Remove the ;; to un-comment the last line and replace YOUR_USER_NAME_HERE by your user name. The same user name displayed by the who utility on a Unix-like operating system.

Emacs was written to allow multiple users from having access to the same configuration, and this identifies the user that will not be reminded of Emacs concepts and principles every time Emacs starts. So, to take advantage of that small speed up make sure you put your user name there.

2.7.1.3   Simpler Prompts

Emacs prompts that require you to type yes or no might be annoying. If you would prefer being able to just type y or n instead, as most people do, set the pel-prompt-accept-y-n user option to t. There are several ways you can do this:

  • Execute: M-x customize-option then type pel-prompt-accept-y-n, hit return to open the customization buffer and change the user option value. Then apply and save it.
  • Use the PEL key sequence for the above: <f11> <f2> o and type the name.
2.7.1.4   More Emacs Customization

If this is the first time you use Emacs you will also want to customize the following options. Use <f11> <f2> o or M-x customize-option for each of those because their corresponding file should already been loaded in Emacs.

Emacs user option Description
column-number-mode Set it to t to activate the display of the column number on the mode line.
comment-empty-lines Set it to t if you want to comment empty lines when commenting a region of lines.
confirm-nonexistent-file-or-buffer Set it to nil (never) to prevent confirmation prompts every time you want to edit a file that does not exist to create it.
fill-column Set the default maximum line length. A good number is 78. For source code, PEL provides another set of user options for each programming language, allowing you to control that user option from the file type.
hl-line-sticky-flag Set it to nil if you only want to highlight the text in the current window when the buffer shows in multiple windows.
truncate-lines Set it to t if you want Emacs to truncate long lines instead of wrapping them. You can change this behaviour by using <f11> l t or M-x toggle-truncate-line.
user-full-name Your full name. PEL uses it in various file skeletons.
user-mail-address Your email address. PEL uses it in various file skeletons.

You will probably want to configure some other behaviour. Since PEL promotes the use of the Emacs customization we'll do it through that. You need to know that some Emacs packages are loaded by default and they can be customized right away. Others define auto-loaded customization variables. Yet others do not autoload their customizable variables.

With PEL you activate packages via PEL customization variables that are always loaded. And you can customize variables of installed packages that are not yet loaded and have not been auto-loaded by using PEL commands.

The imenu package is built-in but its customization variables are not auto-loaded. To modify the following user-option (the other name for customization variables) you can type <f11> <f10> <f3> 2. That will load the imenu package and open the customization buffer for imenu where you can edit the following user-option.

Emacs user option Description
imenu-max-items Set the maximum number of entries in the imenu list if the default of 25 does not correspond to what you like.

Make sure to save the values in a file by pressing the Apply and Save button at the top of the buffer window. You may also have to confirm at a prompt shown at the bottom of the screen.

To modify bookmark specific user options, you can type <f11> ' <f3> 1 to open the bookmark customize buffer and then modify the following user-options:

Emacs user option Description
bookmark-save-flag Set it to 1 to get Emacs to save the bookmarks inside the bookmark file every time a bookmark is set.
bookmark-default-file Set the location of the bookmark file. The default is ~/.emacs.d/bookmarks

If a package is not installed you can't customize it. Set the PEL pel-use- user-option, restart Emacs to install the package and then you can customize it.

2.7.2   Create command line shortcuts for Emacs

New Emacs users may be interested by command line commands to start Emacs in various ways:

  • starting an independent emacs process in terminal (TTY) mode from a shell,
  • starting an independent emacs process in graphics mode from a shell,
  • starting an emacs client to an emacs daemon (the Emacs server).

PEL provides 3 short-named scripts to do this on macOS and Linux:

     
. e[OPTIONS..] [FILE..]

Start Emacs in text mode.

  • Supports emacs options and file arguments. See emacs man page.
.

ge :

  • ge [-h | --help]
  • ge [OPTIONS..] [FILE..]

Start Emacs in graphics mode.

  • Supports emacs options and file arguments. See emacs man page.
.

ec :

  • ec [-h|--help]
  • ec [-g|gui] [--name=NAME] [FILE...]
  • ec --start-daemon [--name=NAME]
  • ec --check-daemon [--name=NAME]

Start an Emacs client for an Emacs daemon.

  • Use ec to start an Emacs client to the default Emacs daemon, starting the daemon if it is not already running. The client is a terminal based client by default.
  • To start a graphical (GUI) Emacs client instead, use ec -g or ec --gui. This also starts the Emacs daemon if it is not already running.
  • By default the ec command launches and connects to the default socket name. Use the --name option to specify another name (for both the daemon and its clients). For example, use ec --name=PEL to start and connect to a Emacs daemon that uses the socket named PEL.
    • With this option it is possible to create several independent groups of Emacs daemon/clients.
  • Use ec --start-daemon (optionally specifying the daemon name with --name) to start the Emacs daemon without starting the client. If the Emacs daemon is already running the command prints a message and exits with the exit code 1.
  • To explicitly check if the Emacs daemon for the default socket is running use the ec --check-daemon command. To check for the Emacs daemon that uses a named socket use the same command and specify the --name=NAME option.

PEL also provides a quick installation script to do it.

Using short command names to use from the shell goes hand in hand with the desire to make Emacs start faster. And you probably don't have to worry about a clash with the 1970s E editor.

2.7.2.1   Start Emacs in Terminal/TTY mode

Emacs can run directly in a terminal emulator application window to take advantage of the fact that in general, Emacs starts faster when running in terminal (TTY) mode than when it runs in graphics mode.

2.7.2.1.1   Extend available keys to Emacs running under a terminal emulator

However, several key combinations and Emacs Modifier Keys may not be available by default. For instance the functions keys might be inaccessible. In most cases the Control key can only be used to compose the basic ASCII control codes, nothing else.

Fortunately most terminal emulator applications on Unix-like operating system provide ways to increase the number of recognized Emacs key sequences recognized.

The following sub-sections provide more information.

2.7.2.1.1.1   Prepare Keyboard Support for Emacs on macOS Terminal

The macOS provides the Terminal built-in application. Several important keys used by PEL are lacking from the default Terminal key settings but the can be added via the Terminal Preferences by specifying ANSI escape codes sequence for specific key combinations and to provide key bindings to cursor keys and numerical keypad keys.

See the macOS-terminal-settings PDF for more information.

2.7.2.1.1.2   Prepare Keyboard Shortcuts on Linux Distributions

In general Linux-based terminal applications provide a larger number of key sequences by default. However, several function keys, such as the F11 key are often reserved by either the terminal application or the OS windowing system.

But they can be modified easily using the terminal application preferences such as the Debian 10 Terminal Preference dialog shown below:

res/debian-terminal-preference.png
2.7.2.1.2   Scripts to Launch Emacs in Terminal mode

Use the Emacs -nw command line option to start Emacs in terminal/TTY mode, or the PEL supplied e script.

If you have not already done so, use PEL quick installation script to create the e command.

With these you will be able to open any file(s) with Emacs from the command line, doing something like this:

cd ~/my_development_directory
e hello.c
e hello.c hello.h
e *.c
2.7.2.2   Launching graphics mode Emacs from a shell

Under Unix-like Operating Systems like Linux and macOS when you run Emacs in graphics mode, Emacs may not get the complete environment variables that you get in your shell. That happens quite often in macOS as explained by Steve Purcell in the readme file of his exec-path-from-shell package. His package provides a way to fix the problem. PEL, however, does not integrate that library because it slows Emacs startup.

PEL uses another method based on environment variables and described in Identify Types of Emacs Processes and its sub-sections.

The method promoted by PEL requires setting up a small shell (or Window command) script that sets up an environment variable identifying that Emacs runs in graphics mode.

There are several advantages to that method:

  • Emacs starts up faster,
  • the graphical Emacs inherits the complete environment of the shell from which it is launched, without having to add yet another Emacs package (remember that as the number of Emacs external packages increases so does Emacs startup time),
  • you can launch several instances of graphics Emacs, from the same or different shells, where different shells may have different values for important environment variables, and that might include different versions of important programming languages related yo your project.
  • inside the script you can set environment variables to identify the fact that Emacs is running in graphics mode. That's only necessary when Emacs 27 or later is used with an early-init.el file and you need to set up something differently for Graphics mode during the execution of early-init.

PEL provides a fully working ge shell inside the pel/bin directory that can be used under macOS and Linux.

If you have not already done so, use PEL quick installation script to create the ge command.

With these you will be able to open any file(s) with Emacs from the command line, doing something like this:

cd ~/my_development_directory
ge hello.c
ge hello.c hello.h
ge *.c

2.7.3   Identify Types of Emacs Processes

PEL distinguish 3 types of Emacs process modes:

  1. GUI launched Emacs running in graphics mode. Examples of this is Emacs launched from Windows Explorer, macOS Finder, Linux file managers, etc...
  2. Shell launched Emacs running in graphics mode. When a command typed in a shell starts Emacs in graphics mode.
  3. Shell launched Emacs running in terminal mode.

PEL also supports two ways of handling Emacs customization:

  • Unique customization file: the usual way where the same customization file and external packages and their setup is used by Emacs running in terminal/TTY mode and Emacs running in graphics mode.
  • Dual customization files: a mode where 2 independent customization files and Elpa package directories are used: one for Emacs running in terminal/TTY mode and a different one for Emacs running in graphics mode.

These apply to the 3 types of Emacs processes listed above.

PEL uses environment variables to distinguish the types of Emacs process during execution and to determine if PEL uses the same or different customization files for Emacs running terminal/TTY and graphics modes. The environment variables are read by PEL's code but also by the code in the early-init.el [2] and init.el files.

Although this method requires an initial manual setup it runs quickly and does not slow Emacs startup [3].

PEL's method requires 2 environment variables and logic inside both early-init.el and inside init.el.

The environment variables are used like this:

Variable 1 Variable 2 Detected mode
Not set N/A GUI launched Emacs running in graphics mode.
Not set Set to "1" Shell launched Emacs running in graphics mode.
Set Not set Shell launched Emacs running in terminal mode.
  • Variable 1: identified by the pel-shell-detection-envvar user option.
    • The default value of the user-option is the specially reserved "_" environment variable used by Bash. If you do not use Bash to launch Emacs you will have to use something else. In the worst case, use PEL_SHELL and set that environment variable inside your shell startup script (something like ~/.bash_profile).
  • Variable 2: PEL_EMACS_IN_GRAPHICS environment variable. This variable must be set to "1" by the shell script that launches the shell launched Emacs in graphics mode. See the script examples in the sub-sections of Launching graphics mode Emacs from a shell.

If you plan to use PEL support for package quickstart, you must use an early-init.el file that identify whether Emacs is running in graphics mode or terminal mode using the environment variables. PEL provides an example of early-init.el that provides the required logic: example/init/early-init.el.

[2]Emacs 27 and later support the package quickstart mechanism. This requires setting information in the file early-init.el. At the moment Emacs process the content of early-init.el its graphics support code has not yet been initialized and Emacs Lisp code cannot detect whether it is running in terminal mode or in graphics mode by calling display-graphic-p: that function is not available at that time. One way around this is to use the getenv function to read the content of an environment variables, a method PEL promotes in the use of early-init.el.
[3]PEL uses an alternative to Steve Purcell's exec-path-from-shell method which unfortunately slows Emacs startup.
2.7.3.1   Prepare using GUI-launched Emacs running in graphics mode

If you plan to launch Emacs from a GUI application like Windows Explorer or macOS Finder you will find that Emacs process environment will not include everything you need to get everything working. As described in the previous section PEL provides a solution to this problem, a solution that does not slow down Emacs startup and requires you to set one or two PEL customization user-option variables:

  • pel-shell-detection-envvar to identify an environment variable whose presence identifies that Emacs was launched by a shell and absence identifies that Emacs was launched from a GUI application such as Windows Explorer, macOS Finder or something like that.
  • pel-gui-process-environment is where you define the environment variables for the GUI Emacs. You can define any environment variable name and value and specify whether you want PEL to use the value as-is or to prepend or append it to the value of variable if it exists.

You will most likely need to specify an extra set of directories to prepend to your PATH to allow Emacs to execute some of the programs you want to use because the OS PATH inherited by the GUI-launched Emacs is minimal and will probably not include the directory where several tools need such as the spell checker program (aspell, hunspell or ispell) or several compilers.

  • One trick you may want to use is to create a directory where you will store several symlinks to the programs you need to use and put that single directory in the PATH specified in pel-gui-process-environment user option with the prepend action.
  • You can add any other environment variables this way.

To support dual independent customization files do the following:

  • Make sure that your init.el file contains the logic identified in the example/init/init.el file:
    • Set OPTION A: set pel-init-support-dual-environment-p to t
    • Set OPTION B: set pel-ei-shell-detection-envvar to the name of the environment variable your shell always set or the one you always set inside your shell startup script (something like PEL_SHELL). Its value should be the same as what is defined by the pel-shell-detection-envvar user-option.
  • For Emacs 27 and later, to support the package quickstart feature you must also create an early-init.el file that has the logic shown inside the example/init/early-init.el file:
    • Set OPTION A: set pel-early-init-support-dual-environment-p to t.

To support GUI-launched GUI Emacs

If you want to use Emacs in graphics mode launched from a GUI application like Windows Explorer or macOS Finder you must also do the following:

  • Start Emacs with PEL support in graphics mode from a shell.
  • Type the <f11> M-s <f2> key sequence to open the customization buffer where you can set these two user-option variables.
    • Set the values of pel-shell-detection-envvar and environment. Save the customization file.
  • Restart Emacs for these to take effect.
2.7.3.2   Prepare using shell-launched Emacs running in graphics mode

If you plan to launch Emacs from the shell and want to use two independent customization files, one for Emacs running in graphics and another for Emacs running in terminal mode, you need to create a shell script that will launch Emacs in graphics mode. That script must set the PEL_EMACS_IN_GRAPHICS environment variable to 1 ( a string value). See the script examples in the sub-sections of Launching graphics mode Emacs from a shell.

2.7.3.3   Prepare using shell-launched Emacs running in terminal mode

Aside from invoking Emacs with the -nw command line there is nothing special to do for PEL to launch a terminal-mode Emacs from a shell.

See example of scripts in the section titled Scripts to Launch Emacs in Terminal mode.

3   PEL Customization

With PEL installed and built, as described in the installation procedure above you can run Emacs and select the packages you want to use by customizing Emacs and setting the PEL user options to activate the packages you want to use.

3.1   Activate PEL Features - Customize PEL

You customize PEL by using the flexible Emacs easy customization system. PEL controls the activation of external packages and their key bindings via a set of customize variables (also called user options) that have names that start with pel-use-, the PEL use variables.

3.1.1   PEL Use Variables

PEL controls activation of packages via customization user option variables that have a name that starts with pel-use-. The number of these user option variables grows as PEL evolves.

Note

If you prefer installing an external package yourself, instead of letting PEL install it for you, install that package before setting the corresponding pel--use- user option.

To get the list of these user options, use Emacs completion when executing the describe-symbol command: type <f1> o followed by pel-use- and the tab key. Emacs will show the available list of user options that have a name that starts with pel-use-. It will look like this:

The following table contains the list of the pel-use- user options currently available.

res/pel-use-completion.png

If you search pel-use- in a customization buffer, Emacs will also list all corresponding user options in alphabetical order. The following screen shot shows the buffer split in 2 windows synchronized with the follow-mode:

res/pel-use-cfg.png

There are several ways to customize PEL and key sequences to access the various customization buffers.

3.1.2   With a global view - use the PEL customization tree

At first, the easiest way to learn PEL customization of various features is to use the customization browser on PEL tree. You can then inspect each group one by one and activate what you want to use.

To do that, type <f11> <f2> P B or type M-x pel-browse-pel. This will open the customization tree at to root of PEL. You can split the window into 4 vertical windows using C-x 3 tree times, make them all the same size with the balance-window command bound to C-x + or with the PEL <f11> w s = key binding. Use Emacs follow-mode on the 4 windows to make them all display the consecutive content of one buffer (the *Customize Browser*).

When you click on an option link, Emacs opens another buffer from where you can select the value for the customize variable (also called user-option). Make your selection and then click the Apply and Save button to register your selection inside the customization file.

Here's a screen capture of that activity:

res/pel-start-customizing.png

To learn more about Emacs customization, read the Customization PDF and the various documents identified by the links it contains.

You can open that PDF via the <f11> ? p> key sequence. This opens a prompt at the bottom of the Emacs window. This prompt, like several other, supports tab-completion. Type cust, then the tab key which will complete it to customize then hit the return key to open the local copy of the PDF. Use the same key sequence with a prefix command argument key like C-u or M-- to open the PDF file inside your default or Firefox browser instead (see [1]).

You can also open that specific PDF file with its dedicated PEL key sequence: <f11> <f2> <f1> (and in the browser with something like C-u <f11> <f2> <f1>.)

3.1.3   Access PEL Customization Root

You can access the same information from the customization buffer of the top level PEL group by executing the pel-cfg command by typing the <f11> <f2> P ! key sequence. When running Emacs in graphics mode, you'll see something like what is shown in the window in the top left corner of the following screen shot:

res/pel-cfg.png

Emacs opens a buffer in Custom-mode and shows the top level of PEL configuration. Click on a subgroup link to open its customize buffer. The customize buffer for the Pel Package Use is shown above in the right hand side window. The above screen shot also shows the entire PEL customize tree in a customize browser buffer in the middle window.

All PEL package control user options have a name that starts with pel-use- and they are part of the pel-package-use customization group. If you select that group Emacs will open it and you will see something like the buffer shown on the right hand side window above.

If you want to see all pel-use- variables, you can also type pel-use- in the field to the right of the Search button and press that button. Emacs will list all pel-use- user option variables by alphabetical order, as shown below. Set the ones you want to activate. Then save your configuration and restart Emacs.

The following show a lot of options on. Most of them are turned off by default when you first get PEL. Turn them on, save the customization and execute pel-init or restart Emacs to activate them. When you restart Emacs, some more packages might be automatically downloaded when required.

Note: In Emacs Lisp the value t, is the symbol for truth and nil is used for the empty list and represent falsehood.

You can repeat the operation several times. If you saved the customization, you can exit Emacs: the new features will be available the next time you start it.

Links to PDF Documentation in Customization Buffers

PEL includes links to the PDF reference sheet files relevant to the PEL customization group inside the customization buffer. You can open your local PDF file by clicking on the button to the right of the "See also" note as shown here:

res/pel-link-to-pdf.png

3.1.4   Identify PEL User Option

PEL controls download, activation and configuration of Emacs external packages and features via PEL user options: the main ones are the PEL Use Variables, but PEL also defines other user-options for several of these features.

The PEL user options are named after the package or feature they control and are members of customization group organized by topics and hierarchies.

3.1.4.1   Identify PEL user option via PEL Topic PDF

PEL provides an extensive set of PDF topic-oriented reference sheets. All of these PDF files are identified inside the top-level PEL Index PDF. Each PDF file describes a specific topic:

  • an Emacs specific topic like navigation commands, Emacs buffers, Emacs windows, etc..
  • support for specific programming language, markup language, etc...
  • PEL specific conventions.

The PDF files identify the PEL user option that activate and control a specific feature. External packages are marked with the 📦 icon and PEL user options with the 🛃 icon.

For example, if you want to add or control a feature related to navigation start looking into the ⅀ Navigation PDF. You can open it via the <f11> ? P key sequence and type navigation. You can also open it by opening the PEL Index PDF with a browser that renders PDF files (see [1]) and click on the ⅀ Navigation link there.

3.1.4.2   Identify PEL User Option by Name

Once you know the name of the PEL user option or its customization group you can use Emacs commands to open the customization buffer where you can see the value of the user option and change it. The following commands are useful:

  • Use the customize-option command via M-x customize-option or through the PEL key binding <f11> <f2> o to open the customize buffer for the corresponding user option variable.
  • Use the customize-group command via M-x customize-group or through the PEL key binding <f11> <f2> g to open the customize buffer for the corresponding group of user option variables.

See the ⅀ Customize PDF for more information on Emacs customization and all PEL commands that provide quick access to the customization buffers.

3.1.4.3   Navigating PEL User Option Groups

Emacs customization information is organized as a tree of customization group which is mainly organized by topic. A group can be the child of more than one group. A user option variable can be the member of several groups as well. PEL takes advantage of that capability to provide access the user options from different, related, topics.

The PEL customization group is a child of Emacs Convenience customization group. Browse Emacs customization tree from the top with the <f11> <f2> B key sequence or from the top of the PEL customization group with <f11> <f2> P B. Click on the [+] nodes to expand them down to the topic of interest. This works with Emacs running in graphics mode as well as in terminal mode.

See sections With a global view - use the PEL customization tree and Access PEL Customization Root for examples of the way this looks.

4   PEL Key Bindings

Emacs makes extensive use of key prefixes.

PEL key bindings mostly use function keys as key prefixes: the F6, F7, F8, F11 and F12 keys are all PEL prefix keys:

  • F6 is a prefix for some often used commands.
  • F7 is used to access all PEL Hydra heads.
  • F8 is used as the prefix for the Projectile Project Interaction Manager commands. It is available when the pel-use-projectile user-option is active and the key is made available after activating the projectile-mode which can be done with the <f11> <f8> <f8> key sequence.
  • F11 is PEL's main global prefix key. It is always available and provide access to most of the PEL key maps.
  • The F12 key is also available in some major modes as described in the section titled PEL Mode Sensitive Key-maps.

PEL also binds:

  • F2, used to jump to bookmarked locations when the pel-use-bm user-option is active.
  • F5 as the repeat key.

All PEL key prefixes are used for PEL key maps. These all have names that start with pel:.

More information on keys in Emacs with PEL include:

  • The PEL Key Maps PDF file. To open a local copy it from Emacs type F11 followed by F1 (normally identified in this manual as <f11> <f1>).
  • The ⅀ ⌨︎ Modifier Keys PDF which describes Emacs modifier keys. Open the local copy of that file in Emacs with <f11> ? p modifier-keys followed by the return key.
  • The ⌨︎Keys - Fn PDF that has a table that shows how function keys are used by PEL. From within Emacs use <f11> ? p keys-fn to open it.
  • The ⌨︎Keys - F11 which lists the key bindings under the F11 key.
  • From Emacs you can list keys under a the prefix key (like F11) in the *Help* buffer: type that prefix key and then type C-h quickly.

As described in the Naming Conventions section the names in the binding column that use the pel: prefix are sub key-maps. All PEL command functions have a name that starts with the pel- name prefix.

Note: for Emacs running in terminal (termcap) mode

If you are using Emacs inside a terminal emulator program such as Linux GNOME Terminal you may have to update your terminal keyboard shortcuts to free the function keys and some other keys that PEL uses. The section titled How to Modify the Terminal Keyboard Shortcut Keys describes how to do that under some environments.

4.1   Key Binding Help

Using the which-keys package

By default, PEL configuration activates the which-key external package. When which-key-mode is active Emacs displays a list of key bindings after you type a prefix key.

For example, after typing the F11 key, wait a little and Emacs should display something like the following at the bottom of your Emacs window, called the echo area:

res/pel-which-key.png

This lists all keys and further key prefixes. If the list is long as it's the case here type C-h to show a menu of possible actions and then you will see you can type n to display the next set of key bindings. As soon as you hit a key related to a command the which-key window is closed.

If you type command keys fast enough the which-key window does not show up. You can control which-key parameters through Emacs customization. Use one of the following commands to access which-key customization group:

  • M-x customization-group RET which-key RET
  • <f11> <f2> g which-key RET
  • <f11> ? <f3> 5

If the which-key package is not enabled, you can enable it by setting the pel-use-which-key user-option to t. You can access it by opening the customization buffer for help by typing the <f11> ? <f2> key sequence.

Once set, it must be activated: execute pel-init by typing M-x pel-init RET to re-initialize PEL.

Displaying keys without the which-keys package

You can also see the list of commands without using the which-keys package. For example, you can see PEL's use of the F11 function key by hitting in sequence the F11 key quickly followed by the C-h key. Emacs will list PEL's F11 key bindings inside the *Help* buffer.

Open the PEL PDF reference sheet

Open the local copy of the PDF reference sheet file that describes the commands and key bindings accessible through a given key prefix by using the F1 key inside that key prefix.

The following table is a partial list of the key sequences you can use to open a specific PEL PDF file.

Context Key sequence Opened PEL PDF
From any buffer <f11> <f1> PEL Index PDF
From any buffer <f11> ? <f1> Help PDF
From any buffer <f11> ! <f1> Syntax Check PDF
From any buffer <f11> M-c <f1> Input Completion PDF
From any buffer <f11> SPC c <f1> C language PDF
From a C buffer <f12> <f1> C language PDF
From any buffer <f11> SPC e <f1> Erlang language PDF
From a Erlang buffer <f12> <f1> Erlang language PDF

As listed above and inside the PEL Help Support, the PEL key prefix for help and information commands is pel:help bound to the <f11> ? key sequence. To open the HELP PDF file, type <f11> ? <f1>.

Most PEL key prefixes have a <f1> key that opens the PDF describing the commands accessible through that key prefix. This includes the PDF that describe support for a major mode like support for programming languages. To access the PDF when the current buffer is using that major mode the keys sequence is always <f12> <f1>. If you want to access the PDF from a buffer that is not in the specific major mode type <f11> SPC and wait for the list of major modes to appear. Then select the key for the major mode and then complete it with the <f1> key.

Open the PEL PDF files in the browser

By default, PEL opens the PEL PDF files using the PDF reader application available on your operating system, for example Preview in macOS.

The PDF files are filled with hyperlinks to other PEL PDF files and various topics. Navigating through these hyperlinks with such an application may be cumbersome.

This is why PEL provides the ability to open PEL PDF files directly in your local browser. There are several ways to do that:

  • Type an argument key (like C-u or M--) just before typing the key sequence. For example typing C-u <f11> <f1> or M-- <f11> <f1> opens the PEL Index PDF raw PDF from Github inside your browser.
  • You can invert the meaning of the argument key presence such that typing <f11> <f1> opens the Github file in your browser and C-u <f11> <f1> opens your local PDF file. For that set the pel-flip-help-pdf-arg user-option to t. You can access its customization buffer with <f11> ? <f2>.

For the best user experience use a web browser that can render PDF files inline, like the excellent Mozilla Firefox [1] browser version 78 or later.

To force PEL to use Firefox even if your default web browser is something else, set the pel-browser-used user-option to 'firefox. You can access its customization buffer with <f11> ? <f2>.

4.2   PEL Mode Sensitive Key-maps

The first element of the table in the previous section lists the <f11> SPC special prefix. It's the top key-map of all PEL mode sensitive key-maps. It has several sub-maps, once for each of the major mode explicitly supported by PEL. Some of them are shown in the following table:

key binding
<f11> SPC C pel:for-C++
<f11> SPC D pel:for-D
<f11> SPC L pel:for-lisp
<f11> SPC c pel:for-C
<f11> SPC g pel:for-graphviz-dot
<f11> SPC l pel:for-elisp
<f11> SPC p pel:for-python
<f11> SPC r pel:for-reST

If you are editing a buffer in one of the mode explicitly supported by PEL, the F12 key is bound to the mode-specific prefix. For example inside a buffer using the elisp-mode major mode, typing <f12> is the same as typing <f11> SPC l. Inside a buffer containing Python source code, typing <f12> is the same as typing <f11> SPC p.

When the current buffer is using the rst-mode for editing reStructuredText files, the F12 key has the following bindings and more.

key binding
<f12> . pel-rst-makelink
<f12> g pel-rst-goto-ref-bookmark
<f12> s pel-rst-set-ref-bookmark

However, when the current buffer uses Emacs-Lisp mode for working on Emacs Lisp code, the F12 key has the following, different, bindings.

key binding
<f12> . pel-find-thing-at-point
<f12> D toggle-debug-on-error
<f12> a pel:elisp-analyze
<f12> c pel:elisp-compile
<f12> d pel:elisp-debug
<f12> e pel:elisp-eval
<f12> f pel:elisp-function
<f12> i parinfer-auto-fix
<f12> l pel:elisp-lib
<f12> m pel:elisp-mode

If you edit a reStructuredText file and want to use one of the commands available in the Emacs-Lisp key-map, then you can use the longer PEL key-map that uses the <f11> SPC l prefix.

4.3   Key Bindings Documentation

PEL comes with a set of tables listing and describing:

  • the standard GNU Emacs commands and key bindings for a given type of activity,
  • the commands and key bindings provided by PEL for the same type of activity,
  • the commands and key bindings for commands provided by external packages that PEL supports and can download and install.

These tables are inside PDF documents; the PDF topic-oriented reference sheets. They are listed in the PEL Index PDF.

Open PEL PDF files quickly from Emacs:

  • PEL provides a set of key bindings that open you local copy of the file (or the Github-hosted copy) inside most key prefixes.
  • For example to open your local copy of the Search and Replace PDF file that describes the search and replace features available under Emacs type <f11> s <f1>. To open the same file but from the Github site prefix these keys with C-u.
  • For topics such as Narrowing and Navigation, that do not have a specific PEL key map prefix, type <f11> ? p followed by the topic name or a portion of the name followed by tab to activate Emacs completion, then hit return once you selected the topic.

See the PDF Documentation section for more info on why these are PDF files. The format of these files makes them something between a set of quick-sheets and a full blown manual.

Each PDF file holds a table that list commands related to a specific topic and holds overview above a list of rows on:

  1. The command name with several hyperlinks to the related section of the GNU Emacs manuals or other appropriate resource.
  2. The key bindings for that command including:
    • the standard Emacs key bindings,
    • the bindings for integrated packages,
    • the bindings specific to PEL.
  3. The Emacs Lisp function form for the command, with the function name in bold and the arguments in Emacs help style.
  4. A description of the command, with lots of the text taken directly from Emacs help for what relates to the interactive use of the function but also with extra notes and references.

Several of these documents also a list of reference table with relevant topics. These references include hyperlinks to the relevant GNU Emacs manuals but also to several sites devoted to Emacs including several demonstration videos hosted on various platforms.

The tables are heavily marked up using colors and icons (actually Unicode character symbols) to highlight various concepts. For example key bindings that do not work when Emacs is running in terminal (TTY) mode are shown in orange, commands that require external Emacs package are shown in blue and use the package character (📦), etc... The full list of conventions are listed in the Document Legend table.

The list of tables follow below. As PEL evolves, it will cover more topics, more programming languages, major modes and will integrate with more of the external Emacs packages and more tables will describe how to use them.

5   Control External Package Installation and Emacs Initialization Speed

PEL controls the download and installation of external Emacs files and packages as well as their configuration and key bindings in some cases.

The value of the PEL Use Variables identify your configuration and the pel-init command (which runs on Emacs startup) activates what you requested.

You can disable packages you no longer need by using the pel-cleanup command. It moves the un-required packages off the elpa directory into the attic directory making them invisible to Emacs.

In normal startup mode, all of this is available and works automatically.

However, if you want to speed Emacs initialization more than what is normally possible, you can activate PEL fast startup mode. In fast startup mode PEL package management controlled by pel-init and pel-cleanup is no longer available.

On Emacs 27 or later you can also activate Emacs package quickstart.

You can also decide to manage the configuration of Emacs running in terminal mode independently from the one used when Emacs runs in graphics mode.

PEL provides commands to control these various setups. The following sub-sections provide more information.

5.1   PEL Initialization Command

When PEL is used, the init.el file calls the pel-init command after loading the Emacs customization file. If PEL operates in normal startup mode the pel-init command downloads and installs any un-installed external package identified by the activated PEL use variable .

With PEL you add a supported package by setting the corresponding PEL use variable user-option customize variable, making sure the new value(s) is stored in the customization file, and then either:

  • execute pel-init by typing M-x pel-init RET, or
  • restart Emacs.

For more information on customization see:

5.2   PEL Cleanup Command

As you start using more and more external packages, you will notice that Emacs startup time increases. PEL delays execution as much as possible, using the same techniques you will find in other packages such as the popular use-package and some other. If these were not used Emacs startup time would be much longer. But still, for a large number of packages Emacs startup time will still increase and that startup time might be noticeable.

PEL provides the fast startup mode to help. But you may also have installed several external packages you no longer need. Identify those and reset to their corresponding PEL use variable. Then execute the pel-cleanup command to move the un-required packages out of the elpa and utils directories and into their corresponding attic directories.

If you want to get a report of what would be removed (and not remove anything) instead, then type something like C-u M-x pel-cleanup RET. This performs a pel-cleanup dry run and displays a report in the pel-cleanup buffer. Something like this:

res/pel-cleanup-dry-run.png

When you're OK with what is going to be remove, execute the real thing with M-x pel-cleanup RET.

Remember: no file is deleted, pel-cleanup moves them into the attic directory. Later, you can copy them back into the elpa directory manually before re-activating the corresponding PEL use variable and run pel-init to activate them again. Or just activate the PEL use variable and run pel-init again to download a new copy. This way you keep a copy of the old version of the package in the attic directory. If something got broken you have the old one handy!

When using the dual independent customization then you can reduce the number of packages used in terminal or graphics mode by identifying the ones used in each mode.

See the list of important files in the section titled Activate dual independent customization.

It's also a good idea to place your customization file, the elpa and the attic directory under DVCS control.

5.3   PEL Setup Commands

PEL provides several commands that control important aspect of Emacs behaviour:

They are described in the following sub-sections and in the Customization PDF.

5.3.1   Independent Customization for Terminal and Graphics Modes

Emacs can be used in terminal (TTY/termcap) mode and in graphics mode. Usually Emacs customization file is used in both modes.

It may be quite useful to control the packages used by Emacs when it runs in terminal mode and use a different set of package when Emacs runs in graphics mode. That way you use the mode most appropriate with the job and use only the packages required for each modes, reducing the Emacs startup time in each mode.

PEL controls the name of Emacs customization file and the directories where Elpa-compliant packages and packages that are not Elpa compliant are stored:

PEL expects these files and directories to be located in the user-emacs-directory which is ~/.emacs.d by default for Unix-like operating systems. PEL uses:

  • The elpa directory (or symlink when using fast startup) to sore the Elpa-compliant packages,
  • The utils directory to store the Emacs Lisp files that are not part of Elpa-compliant packages.

The PEL installation instructions requires installing a PEL-compatible init.el file which will create the necessary files and directories for normal startup in a standard, single environment, Emacs setup.

PEL provides the extra ability to use 2 independent environment. One environment for Emacs running in terminal/TTY mode and another running in graphics mode. Each have access to its own Emacs customization file and package directories. This feature is called the PEL dual environment.

In this, PEL uses the following files and directories, located inside the user-emacs-directory:

For terminal/tty | all For graphics mode in dual mode Description
emacs-customization.el emacs-customization-graphics.el Customization data file
elpa elpa-graphics Symlink to complete or reduced directory
elpa-complete/ elpa-complete-graphics/ Stores all Elpa packages in normal startup
elpa-reduced/ elpa-reduced-graphics/ Stores reduced and pel-bundle in fast startup
elpa-attic/ elpa-attic-graphics/ Stores Elpa-packages removed by pel-cleanup
utils/ utils-graphics/ Stores non-Elpa external Emacs Lisp files
utils-attic/ utils-attic-graphics/ Stores non-Elpa files removed by pel-cleanup

PEL commands create the files and directories when they are required.

5.3.1.1   Comparing the two customization files with Emacs

The easiest way to compare the terminal/TTY customization file (emacs-customization/.el) from the one used in graphics mode when the dual environment is used (emacs-customization-graphics.el) is to open the 2 files, each one in its own buffer window and show only these 2 windows.

Then execute the pel-ediff-2files command by typing the PEL <f11> d 2 key sequence.

Type ? to display ediff help and the commands to navigate through the files and their differences. You can copy one set of changes from one file to the other this way. It's a quick way to duplicate customization and also a good way to review the recent changes to your customization.

5.3.1.2   Check customization state

The command pel-setup-info-dual-environment, bound to the <f11> <f2> ? and to the <f11> ? e <f2> key sequences, displays the name of the customization file or files used by PEL. If the symbol pel-init-support-dual-environment-p is set to t, requesting the use of two independent customization files it also checks if the environment is properly configured to support two independent customization files and reports all detected problems.

5.3.1.3   Activate dual independent customization

Use the pel-setup-dual-environment command, bound to the <f11> <f2> M-d key sequence, to configure your Emacs environment to support two independent customization files. The command will prepare all required files and directories. It will then perform a final check and will report any remaining problem.

Supporting two independent customization requires creating 2 sets files and directories for storing the Elpa-compliant packages, since PEL selects the active packages through customization: PEL uses the pel-use-... user-options customization variable and their values are stored inside the customization files.

PEL also support the fast-startup mode which also uses two directories to store the Elpa-compliant packages and a symlink to the one that is used.

When properly setup for dual independent customization and for fast-startup support, the Emacs user directory (normally ~/.emacs.d unless configured otherwise) contains the files and directories list in the following table.

For terminal/tty | all For graphics mode in dual mode Description
emacs-customization.el emacs-customization-graphics.el Customization data file
elpa elpa-graphics Symlink to complete or reduced directory
elpa-complete/ elpa-complete-graphics/ Stores all Elpa packages in normal startup
elpa-reduced/ elpa-reduced-graphics/ Stores reduced and pel-bundle in fast startup
elpa-attic/ elpa-attic-graphics/ Stores Elpa-packages removed by pel-cleanup
utils/ utils-graphics/ Stores non-Elpa external Emacs Lisp files
utils-attic/ utils-attic-graphics/ Stores non-Elpa files removed by pel-cleanup

The first column identifies the file, symlink and directories used when Emacs operates normally (with no dual environment as it's normally the case for Emacs) or when it operates in terminal/TTY mode.

The second column identifies the file, symlink and directories used when PEL is used in dual customization files and Emacs runs in graphics mode.

When you first install PEL only some of what is identified in the first column is created, requested by the PEL installation instructions:

  • elpa; the directory that stores the Elpa-compliant package directories.
  • utils; the directory where single files from non-Elpa compliant packages are stored.

The pel-cleanup command creates the attic directories when it needs to remove packages from Emacs sight.

If you want to use PEL fast startup mode, and execute the pel-setup-fast command to activate it, PEL renames the elpa directory to elpa-complete, creates the elpa-reduced directory to hold the Elpa-compliant directories that have several sub-directories and the pel-bundle sub-directory that holds the Emacs Lisp files of all single directory packages. Then PEL creates a symlink with the same elpa name and make it point to elpa-reduced. Later when the pel-setup-normal command is used, the elpa symlink is made to point to the elpa-complete directory.

When dual independent customization is used the same set of file, symlink and directories are created for the graphics specific mode. They all have the same name with the additional -graphics suffix.

5.3.2   Normal Startup and Fast Startup Modes

Once you have installed and configured all external packages you need you may find that Emacs startup time has increased too much for your liking. That will be the case if you use a large number of external Elpa-compliant packages because Emacs must process the autoloads package information inside each of the elpa package directory and that takes time. PEL uses several techniques to reduce Emacs startup time. As the number of package used grows you these techniques may not be sufficient.

To speed the startup further, PEL provides a fast-startup mode of operation. In that mode PEL bundles the Emacs Lisp code files of all single directory packages inside a single package directory (the pel-bundle pseudo package) and forces Emacs to use it as if it was a single package. Doing this reduces the number of packages Emacs see, which reduces the length of Emacs load-path and reduces the startup time substantially.

PEL provides the following 3 commands to deal with this:

  • pel-setup-info, bound to <f11> M-S ? and to <f11> ? e M-S key sequences. It displays the current operation mode.
  • pel-setup-fast, bound to <f11> M-S f. This commands reorganizes the content of your user-emacs-directory to bundle the elpa external packages to provide a faster Emacs init startup time. In this mode you cannot add new external packages though.
  • pel-setup-normal, bound to <f11> M-S n. This command restores the content of your user-emacs-directory the way it was, allowing you to use Emacs as before and with the ability to add or remove external packages.

These commands are described in the Fast Startup PDF Sheet.

The Emacs initialization speedup you will experience depends on several factors:

  • One main factor is the number of Elpa-compliant packages that PEL can bundle. PEL will be able to bundle all those packages that put all their files inside a single directory. PEL will then build a single pel-bundle-autoloads.el file and one pel-bundle-pkg.el for all of these packages. By doing so, and by adding extra code to make the whole thing work, by delaying package initialization in the init.el file, PEL reduces Emacs load-path and overall startup processing.
  • Another significant factor is the init.el code. The execution of package-init must be delayed. See the file example/init/init.el for a setup that properly supports PEL fast-startup.

It's possible to reduce the startup time down such that benchmark-init report it to be 0.1 second, even with a relatively large number of external package.

5.3.2.1   Speedup Examples
5.3.2.1.1   238 external packages in about 0.1 second
  • Startup time:
    • with PEL in normal startup mode: about 0.6 second
    • with PEL in fast startup mode: about 0.1 second
  • Environment:
    • 238 external packages.
    • Computer: 2014 iMac computer with 4GHz Intel Core i7 CPU and Flash storage memory running macOS Mojave.
    • Emacs 26.3 running in terminal mode inside a macOS Terminal window running Bash.

The following screen shots show the benchmark-init reports for Emacs running in this environment in normal startup mode and in fast-startup mode.

Screen Shot #1: Emacs 26.3 in terminal mode using 238 external packages in normal mode exhibiting a 0.6 second startup:

res/normal-startup-001.png

Screen Shot #2: With the same setup as above but now running under PEL's fast-startup operation mode: Emacs startup time is now around 0.1 second.

res/fast-startup-001.png
5.3.2.2   Measuring Emacs Startup Time
5.3.2.2.1   Using benchmark-init

If you want to know the time each loaded file takes during Emacs initialization time you can use the benchmark-init package. This is not controlled by PEL because it must be launched as as early as possible inside your init.el file.

To install it type M-x list-packages then hit the return key to get a list of all elpa-compliant packages. Search for benchmark-init, select it and install it. You can also type: M-x package-install benchmark-init.

After installing it, move the .el and .elc out of the benchmark-init-... sub-directory of ~/.emacs.d/elpa and copy them inside the ~/.emacs.d/utils directory. Then remove the entire benchmark-init-... directory from ~/.emacs.d/elpa.

We don't want to add yet another package to the elpa directory. That will slow down Emacs startup time. By moving the code into PEL's utils directory Emacs will be able to find it faster and we don't add an extra directory.

Then add the following code as close as possible to the top of your init.el file:

(require 'benchmark-init
         (expand-file-name "~/.emacs.d/utils/benchmark-init"))
(add-hook 'after-init-hook 'benchmark-init/deactivate)

This code is present but commented out inside the file example/init/init.el.

With the above code in your init.el file, you can then execute the PEL command pel-show-init-time (or using the <M-S-f9> keystroke for it) Emacs will open 2 buffers and will show something like this:

res/pel-benchmark.png

This is a snapshot taken on GNU Emacs running in terminal mode on a 2014 macOS computer with PEL running with 96 packages selected by customization giving 156 lines inside the benchmark-init buffers.

Here's another snapshot taken after installing PEL on Mint 20 Linux running inside Parallels Desktop VM under macOS host:

res/pel-benchmark-mint20.png

The next time you run pel-cleanup while Emacs runs in normal startup mode, PEL will remove the benchmark-init files from ~/.emacs.d/utils and place them into the ~/.emacs.d/utils-attic where you can restore them when needed.

5.3.3   Package Quickstart Mode for Emacs 27 and later

Emacs 27 introduced the package quickstart feature. When this feature is used, Emacs creates the file package-quickstart.el in the Emacs user directory. This file holds the auto-load logic extracted from all package files. When Emacs ≥ 27 detects the presence of this file it uses it instead of scanning the information from all elpa package directories. This speeds Emacs startup.

On Emacs ≥ 27 , PEL supports the 4 different combination of setups, listed below in decreasing order of startup time:

  • normal mode
  • normal mode with Emacs package quickstart
  • PEL fast startup
  • PEL fast startup with Emacs package quickstart

To activate Emacs package quickstart you must create a early-init.el file and create the package-quickstart.el file using the package-quickstart-refresh command. PEL provides logic that takes cares of this and can create all the files while also supporting the PEL fast startup mode and the dual independent terminal/graphics customization.

  • PEL provides a fully functional copy of early-init.el, example/init/early-init.el that will work with PEL’s features example/init directory. PEL modifies the values of some of the defconst variables inside the early-init.el file to control its behaviour.
    • That file name is identified by the pel-early-init-template user-option. If you want to create your own copy of that file and add your content then update the user-option with new file name. Your file but you must include the code located in the file example/init/early-init.el. If you do not need any extra logic, leave the default and use the template file unmodified.
    • Use the <f11> M-S <f2> key sequence to open the appropriate customization buffer.

PEL provides the following 2 commands to setup Emacs ≥ 27 environment to support package quickstart or to remove it:

  • pel-setup-with-quickstart (bound to <f11> M-S q) to activate package-quickstart and create all necessary files. You can also use it to refresh package quickstart files after installing new packages (which you can do in PEL normal startup mode),
  • pel-setup-no-quickstart (bound to <f11> M-S M-q) to disable package-quickstart.

These commands handle the PEL fast-startup mode and the dual independent customization for terminal and graphics mode: pel-setup-with-quickstart activates the package quickstart mechanism and refreshes the files. pel-setup-no-quickstart disables the package quickstart mechanism.

Manual Setup May be Required

If your Emacs customization file is not what PEL normally uses, emacs-customization.el then you will have to create your modified copy of PEL's example/init/early-init.el and modify the value of pel-early-init-custom-file inside that file. See the complete instructions inside the User configuration section of the file example/init/early-init.el.

5.4   Update Packages and Keep Older Versions

To get a later version of package already installed do the following:

  • Make sure PEL is running in normal startup mode. Type <f11> M-S ? to check and <f11> M-S n to activate the normal startup mode if necessary.
  • Move the package directory out of the elpa or utils directory where it resides to the corresponding elpa-attic or utils-attic directory.
    • These directories are located in the directory identified by user-emacs-directory which is often ~/.emacs.d on Unix-like OS.
    • If you use independent customization for terminal and graphics mode, do the same for both set if the package is used in both sets.
    • After a while the elpa-attic directories will contain several older version of the various packages as you move them in since each Elpa-compliant package directory name identifies its version.
      • These older versions can later be restored by placing them back into their corresponding elpa directory.
      • The files in the utils directories have no version identified. Only one copy is available for backup unless you use a versioning scheme when copying them into the attic.
    • See the table below for the list of directories.
  • Exit Emacs and restart it. It will download and install the new version of the packages you just moved out of the elpa and utils directories.

For upgrading external packages you do not need to perform a pel-cleanup/pel-init cycle which would require you to modify your PEL user-options twice. It's faster and more convenient to simply move the package directories as described above.

The various directories (and symlinks) you will find inside your user-emacs-directory are listed here:

For terminal/tty | all For graphics mode in dual mode Description
elpa elpa-graphics Symlink to complete or reduced directory
elpa-complete/ elpa-complete-graphics/ Stores all Elpa packages in normal startup
elpa-attic/ elpa-attic-graphics/ Stores Elpa-packages removed by pel-cleanup
utils/ utils-graphics/ Stores non-Elpa external Emacs Lisp files
utils-attic/ utils-attic-graphics/ Stores non-Elpa files removed by pel-cleanup

6   Emacs and PEL Files and Directories

6.1   PEL Directory

PEL is written in over 100 Emacs Lisp files stored inside the PEL directory. That directory must be identified in your init.el file in the pel-home-dirpath-name variable. All PEL Emacs Lisp files are byte-compiled using make with the Makefile script.

The pel_keys.el file is byte-compiled by the Makefile script but also when you execute the commands pel-setup-fast and pel-setup-normal. pel_keys.el is byte-compiled by these commands because these commands modify the behaviour of Lisp macros that control external package downloading and installation. Normally the macros generate code that checks for the presence of external package required by the pel-use- user-options and force a download and installation if the package is not present. That behaviour is disabled when PEL operates in fast-startup mode speeding up the execution of pel-init since PEL knows that all packages required are present because it does not support automatic download and installation in fast-startup mode. When returning in normal-startup mode, the macros have code that detect presence of external packages and automatic download and installation of external packages is re-enabled.

The pel__hydra.el is also byte-compiled dynamically by pel-init to activate support of Hydra feature when pel-use-hydra is turned on.

No other PEL Emacs Lisp file is byte-compiled outside of the Makefile script.

6.2   User Emacs Directory

The User Emacs Directory is normally ~/.emacs.d. With PEL that directory holds the following files and sub-directories.

Name Description
init.el Emacs initialization required for PEL. Use a copy of example/init/init.el.
elpa The directory that holds Elpa-compliant Emacs external packages. When using PEL fast-startup feature this is replaced by a symlink to the elpa-complete directory or to elpa-reduced directory.
utils PEL specific directory. PEL stores Emacs Lisp files that are not Elpa-compliant packages here.
PEL Cleanup Attics The pel-cleanup command moves un-required packages out of their Elpa directory and into an attic directory where they can later be retrieved. See PEL Cleanup Command.
elpa-attic Directory that holds package directories moved out of the elpa directory by pel-cleanup.
utils-attic Directory that holds files moved out of the utils directory by pel-cleanup.
Package Quickstart The following files are used for the support of the package-quickstart feature. This is only available for Emacs 27 and later.
early-init.el Emacs early initialization file where package quickstart and some other PEL features must be activated. PEL provides the example/init/early-init.el which it uses by default when it activates the package-quickstart feature. See the section titled Package Quickstart Mode for Emacs 27 and later.
package-quickstart.el Emacs package quickstart file that holds the autoload logic of all packages.
PEL fast-startup The following files and directories are used by PEL for the fast-startup and normal startup modes. See PEL Cleanup Command.
elpa-complete Directory used when PEL fast-startup feature has been initialized once. In PEL normal startup mode this stores the Elpa-compliant packages that are were stored in the elpa directory, and elpa is turned into a symlink that points to elpa-complete.
elpa-reduced Directory used when PEL fast-startup has been turned on. It holds the pel-bundle pseudo package and all multi-directory Elpa packages. The elpa symlink points to elpa-reduced when PEL operates in fast startup mode.
pel-fast-startup-init.el File created by pel-startup-fast that acts as a flag to early-init.el and init.el indicating request to use the fast startup mode and which identifies the name of the pel-bundle directory.
Dual Custom files The following files and directories are only used when the dual independent customization files for terminal/TTY and graphics mode is used. These are all PEL specific. See Independent Customization for Terminal and Graphics Modes.
emacs-customization-graphics.el Holds Emacs customization for Emacs running in graphics mode. PEL specific.
elpa-graphics Symlink that points to elpa-complete-graphics in normal startup mode or to elpa-reduced-graphics in fast startup mode.
utils-graphics Directory that holds Emacs Lisp files of non Elpa-compliant packages used in graphics mode.
elpa-complete-graphics Directory that holds graphics mode specific Elpa-compliant packages used when PEL operates in normal startup mode.
elpa-reduced-graphics PEL specific directory. Used when dual independent terminal/TTY and graphics mode is used. Holds terminal/TTY mode specific Elpa compliant packages used when PEL operates in normal startup mode.
elpa-attic-graphics PEL specific directory that holds package directories moved out of the elpa-graphic directory by pel-cleanup.
utils-attic-graphics PEL specific directory that holds files moved out of the utils-graphic directory by pel-cleanup.
package-quickstart-graphics.el Package quickstart file for Emacs running in graphics mode.

6.2.1   Obsolete PEL Files

  • The pel-setup-package-builtin-versions.el is the old name of the pel-fast-startup-init.el file. If you have that file in your Emacs user directory, remove it and manually force the elpa and elpa-graphics symlink to point to elpa-complete and elpa-complete-graphics directory respectively.

7   Updating PEL

After your first successful build of PEL, you can easily update PEL by pulling from the Git depot and running make to update the byte-compile code files used by PEL.

Execute the following commands inside the pel directory.

cd ~/projects/pel
git pull
make

If you want to force byte-recompilation of all PEL code do a make clean before issuing the make command.

To use a new feature that was introduced in the new PEL code, set the corresponding PEL activation user-option variable through the relevant Emacs customization buffer, save the new customization data and run pel-init by using M-x pel-init or by restarting Emacs.

As usual with PEL if new packages are identified by your new configuration they will be downloaded, installed, byte-compiled and configured automatically.

8   PEL Convenience Features

PEL implements a set of small utilities that complement what's already available in standard GNU Emacs and some other packages. The code is spread into several small files. Each of those file is described in the following subsections. PEL comes with a set of PDF files that describe key bindings , including the standard GNU Emacs bindings, the bindings of the external packages integrated by PEL and the bindings for PEL commands. The sections below contain link to the relevant PDF files. The complete list of PDF files is shown in the Key Bindings Documentation section.

8.1   PEL Abbreviation Management Support

PDF Sheet:Abbreviations.
PEL Customization:pel-use-hippie-expand.
PEL Key Prefix:pel:abbrev : <f11> a

PEL provides automatic activation of Hippie expansion when the pel-use-hippie-expand user option is set to t. Otherwise it defaults to Dabbrev expansion. PEL also provides the pel:abbrev key map which provides access to some abbreviation related commands. PEL binds it to <f11> a.

All code provided by PEL about abbreviations is located inside the file pel.el.

8.2   PEL Auto-Completion Support

PDF Sheet:Auto-completion.
PEL Customization:pel-use-auto-complete, pel-use-company.
PEL Key Prefix:pel:auto-completion : <f11> ,

The file pel-autocomplete.el manages the activation and enabling of auto-completion systems globally and per buffer so that you can install several auto-completion packages and then select one of them either globally or per buffer. The selection logic does not allow more than one auto-completion mechanism to be used for a single buffer.

This version of PEL currently supports the following auto-completion packages:

It provides the following commands:

  • pel-global-auto-complete-mode toggles the global Auto Complete mode on/off if it can. Activation is not allowed when Company Mode is active.
  • pel-auto-complete-mode toggles the Auto Complete mode for the current buffer if it can. Activation is not allowed when Company mode is active for the current buffer.
  • pel-global-company-mode toggles the global Company mode on/off if it can. Activation is not allowed when Auto Complete mode is active.
  • pel-company-mode toggles the Company mode on/off for the current buffer if it can. Activation is not allowed when Auto Complete mode is active for the current buffer.
  • pel-completion-info shows the state of the auto completion global and buffer specific modes. It displays if the packages are available and whether they are enabled on not.
  • pel-complete performs an explicit completion using the completion mode enabled in the current buffer.

8.3   PEL Autosave & Backup Documentation

PDF Sheet:Autosave & Backups.
PEL Customization:none
PEL Key Prefix:none

PEL provides a table describing the autosave and backup commands in the Autosave & Backups PDF file.

8.4   PEL Buffer Management Support

PDF Sheet:Buffers.
PEL Customization:none.
PEL Key Prefix:pel:buffer : <f11> b

PEL provides extra key bindings to Emacs commands that manage Emacs buffers: the keys are bound under the pel:buffer key prefix (<f11> b).

See the Buffers PDF sheet for more information.

8.5   PEL Bookmark Management Utilities

PDF Sheet:Bookmarks.
PEL Customization:pel-use-bm.
PEL Key Prefix:pel:bookmark : <f11> '

The file pel-bookmark.el does not contain much. It only provides the utility function pel-bookmark-in-current-file-p` which checks if a bookmark of a given name is present in the currently edited file. This is used in other parts of PEL.

For supporting bookmarks PEL provides the following:

  • PEL provides a set of key bindings under the pel:bookmark key prefix set to <f11> ' by default.
  • If the pel-use-bm user option is set to t PEL add bindings to the visible bookmark commands and binds the F2 key to bm-next which moves point to the next visible bookmark. PEL sets it to support bookmarks in several files and moving across files.
  • Also, the project provides the Bookmarks PDF table which lists several bookmark related functions from various sources and their key bindings.

8.6   PEL Comments Utilities

PDF Sheet:Comments, Cut, Delete, Copy and Paste, Narrowing.
PEL Customization:pel-use-hide-comnt
PEL Key Prefix:pel:comment : <f11> ;

The pel-comment file provides a collection of commands to help manage file comment management.

  • The following commands allow you to display the strings used to control comments in the current buffer and change them:
    • pel-comment-start display/set the string used to start a comment.
    • pel-comment-middle display/set the string used to continue a comment.
    • pel-comment-end display/set the string used to end a comment.
  • With pel-toggle-comment-auto-fill-only-comments you control whether automatic filling is done inside source code comments.
  • The pel-delete-all-comments deletes all comments in current buffer. Use narrowing to reduce the area where comments are deleted.
  • The pel-kill-all-comments kills all comments in current buffer. Each killed comment group is retained in the kill ring, as a separate kill ring entry. That allows selective restoration of comments later with yank operations. See the Cut, Delete, Copy and Paste document.
  • When pel-use-hide-cmnt user option is t the hide-comnt.el file, written by Drew Adams is used and provides 2 commands to hide the comments in the buffer or just in a marked region.

8.7   PEL Closing and Suspending Table

PDF Sheet:Closing and Suspending
PEL Customization:none
PEL Key Prefix:none

PEL provides the Closing and Suspending PDF table listing the Emacs commands to close and suspend.

8.8   PEL (Input) Completion Mode Control

PDF Sheet:
PEL Key Prefix:

none

Emacs support several input completion mechanisms. These help you enter something at a prompt. For example when entering the name of a file you can type the beginning of the file name and then hit a key to complete it. Emacs allows this kind of input completion to be used in several context and PEL provides you with the ability to try and select various methods for various prompts. You can select what you want to start with and then change it during an editing session to adapt to the situation or to test various ways of doing things.

Emacs has one native input completion mechanism (called Emacs default) that kicks into action whenever you use a command that prompts for something like a file name, a buffer name, a command name, etc... It's a minimal input completion mechanism that works by extending the currently typed string with the tab key. Emacs then show possible completion in a completion buffer.

Several other completion modes exist. The IDO completion mode is shipped with Emacs. It is very powerful and supports several ways of filtering the suggestions. The Input Completion PDF describes the various keystrokes it supports. It is well worth the effort to learn these.

IDO can also be extended in various ways. PEL supports several packages:

  • that extend the way it presents available choices:
    • in a grid, originally collapsed in 1 line
    • in a grid fully extended on start
    • vertically, similar to what Ivy does (see below).
  • that extend the way it searches for potential choices:
    • flx-ido
  • that extend what prompt command provide IDO input completion:
    • ido-ubiquitous.

PEL also provide access to The Ivy, Counsel and Helm that are other popular completion modes. They can be installed via PEL and activated by PEL customization and the mode that should be used when Emacs starts is identified by the pel-initial-completion-mode user option.

Once more than one completion mechanism is activated, PEL provides a command to select another completion mode: pel-select-completion-mode. PEL maps this to <f11> M-c. To see which input completion is currently active use <f11> ? c.

With this you can start with Ido mode, then quickly switch to using Ivy mode for a while and return to Ido mode when you're done. Or use whatever you want at the moment you want without having to change and reload your Emacs initialization code.

Persistence of your choices across Emacs editing sessions is provided by Emacs customization mechanism. See the Input Completion and Customization PDF files for more information.

The management of completion mode is provided by the pel-completion file.

8.9   PEL Configuration/Customization Support

PDF Sheet:

User Option Customization.
PEL Key Prefix:
  • pel:cfg : <f11> <f2>
  • pel:cfg-pl : <f11> <f2> SPC
See Also:

Activate PEL Features - Customize PEL

PEL is designed to help you control Emacs through Emacs Easy Customization system instead of explicit Emacs Lisp code. You can always write more Emacs Lisp code to specialize it further but in most cases it might not even be necessary. PEL controls what package is activated and how the features are configured through the Emacs Customization interface. The information is stored in a file and if you followed the instructions inside the section How to Install PEL, your selections will be stored inside the file "~/.emacs.d/emacs-customization.el". You can even copy that file and keep multiple revision around.

Since customization is central to PEL, PEL also provides a set of key bindings that you can use to quickly open a buffer to customize a specific user option or a group or all of Emacs. These key bindings use the pel:cfg prefix, which by default is bound to the <f11> <f2> key sequence.

PEL customization user options are organized in Emacs customization groups with several general groups but also groups for each programming language and markup languages supported by PEL. When point is inside the buffer editing a file in one of the programming or markup language mode supported by PEL you can quickly open the customization buffer for the group of that language by using the <f12> <f2> key.

You can also use the global prefix pel:cfg-pl bound to <f11> <f2> SPC followed by the character identifying the language to open the customization group for a specific language. For example, if you want to change the indentation style and width for your C++ files, use the command associated to the <f11> <f2> SPC C key sequence. This will open the PEL customization group for configuring C++ editing. If point is already inside a buffer in C++ mode, then <f12> <f2> does the same.

After customizing something, you can type the q key to close the customization buffer and come back where you were. And to activate your changes then run pel-init by issuing the M-x pel-init command.

Use Emacs customize data browser to see the customize data in a tree form. Type <f11> <f2> M-1 to browse PEL's customize data tree. Here's a snapshot of a portion of PEL's data tree:

res/pel-custom-tree.png

See the User Option Customization reference sheet for key bindings and the section titled Activate PEL Features - Customize PEL for relevant information.

8.10   PEL Counting Support

PDF Sheet:Counting.
PEL Customization:none
PEL Key Prefix:pel:count : <f11> c

PEL provides the pel:count key prefix (<f11> c) to Emacs commands that count text and display results in the echo area.

8.11   PEL Cross Reference Support

PDF Sheet:Cross-Referencing
PEL Customization:none
PEL Key Prefix:pel:xref

The file pel-xref.el holds utilities related to Etags based cross-reference support and other methods.

8.11.1   Tag-based systems

Emacs supports several tag based systems back-ends for the creation, management and use of those tags for cross referencing purposes. The supported system include:

  • GNU ctags (ctags).
  • Universal CTags (ctags) , the successor of Exuberant CTags.
  • Emacs Etags (etags).
  • GNU GLOBAL gtags.

The following sub-sections describe how to install, setup and use those.

8.11.1.1   GNU GLOBAL source code tagging system - gtags

The GNU GLOBAL gtags homepage describes this powerful system. It combines the capabilities of Universal Ctags, Pygments with its own logic when to parse and tag a large set of programming languages. To use it effectively you must therefore install 3 programs and do a small script to configure them. You must also have Python installed since Pygments is written in Python.

Installation Instructions

  • Install Python 3.5 or later if it is not already available on your platform.
  • Install GNU GLOBAL
    • For macOS, use: brew install global.
    • On Fedora Linux, use: sudo dnf install global
    • On Mint Linux, use: sudo apt install global
    • On Ubuntu Linux, use: sudo apt install global
    • etc ...
  • Install Universal-Ctags (it will replace GNU ctags):
    • for macOS, use: brew install universal-ctags
    • On Fedora Linux, use: sudo dnf install universal-ctags
    • On Mint Linux, use: sudo apt install universal-ctags
    • On Ubuntu Linux, use: sudo apt install universal-ctags
    • etc ...
  • Install Pygments:
    • Use: pip install pygments

Create a script to activate the Pygments plugin of GNU GLOBAL

Store a copy of the envfor-gtags shell script inside one of your directories. Ideally a directory on your PATH but that's not absolutely necessary.

Then, to activate GNU GLOBAL Pygment/Universal-CTags plugin source that script in the shell you want to use gtags in.

For example you could store the script inside a ~/bin directory and then use:

. envfor-gtags

if ~/bin is on your PATH, or:

. ~/bin/envfor-gtags

if ~/bin is not on your path.

If you want to provide access to global in all shells, you can place this command in your startup script (e.g. ~/.bash_profile for Bash).

8.11.1.2   PEL Utilities that build TAGS File

PEL provides a set of POSIX-compliant shell scripts that can be used to find the source code files inside specified directory trees and build TAGS for a given set of programming languages.

More information on it is available in the page titled Using ctags and etags for cross referencing with TAGS.

8.12   PEL CUA Mode Extension Utilities

PDF Sheet:CUA
PEL Customization:none
PEL Key Prefix:none
Status:Experimental
Note:
🚧 While CUA Mode itself is a stable Emacs feature, PEL's additions are experimental.

I'd like to find ways to easily manage rectangles of text without having to activate the CUA mode and the file pel-cua.el holds some experimental and unfinished code for going in that direction. Some of the commands are bound to PEL keys and described in the PDF tables. But this work is in very early stage.

8.13   PEL Cursor Management Support

PDF Sheet:

Cursor
PEL Customization:
  • pel-cursor-overwrite-mode-color
  • pel-cursor-type-when-mark
  • pel-use-multiple-cursors
  • pel-use-visual-regexp-steroids
  • pel-use-visual-regexp
PEL Key Prefix:

none

The pel-cursor.el file the logic required to control the cursor color and type when Emacs is running in graphical mode.

  • With the pel-cursor-overwrite-mode-color user option, you can select a color different than what is normally used by the cursor to change cursor color when the overwrite-mode is active.
  • With pel-cursor-type-when-mark you can set a different cursor type (shape) used when the mark is active.

When pel-use-multiple-cursors is set to t the popular multiple-cursors mode is made available and PEL provides a set of key bindings for this. The pel-use-visual-regexp and pel-use-visual-regexp-steroids activate the ability to perform a search which yields to multiple cursors activated at the match locations.

See the PDF Cursor document for more information.

8.14   PEL Cut, Delete, Kill, Copy, Paste and Yank Utilities

PDF Sheet:

Cut, Delete, Copy and Paste, Marking.
PEL Customization:

pel-use-popup-kill-ring.
PEL Key Prefix:
  • pel:clipboard : <f11> C
  • pel:copy : <f11> =
  • pel:kill : <f11> -
  • pel:text-whitespace : <f11> t w

The pel-ccp.el file provides a collection of commands to perform Emacs style kill/yank and otherwise copy/cut/paste operations on various parts of the text, targeting specific syntax entities or other simpler parts.

  • The following commands copy the specified syntax entities at point into the kill ring:
    • pel-copy-word-at-point
    • pel-copy-symbol-at-point
    • pel-copy-sentence-at-point
    • pel-copy-function-at-point
    • pel-copy-sexp-at-point
    • pel-copy-whitespace-at-point
    • pel-copy-filename-at-point
    • pel-copy-url-at-point
    • pel-copy-list-at-point
    • pel-copy-paragraph-at-point
    • pel-copy-paragraph-start
    • pel-copy-paragraph-end
    • pel-copy-line-start
    • pel-copy-line-end
    • pel-copy-char-at-point
    • The command pel-copy-marked-or-whole-line copy a marked region if any or the entire line (including the line termination) into the kill ring.
  • The following commands kill the specified syntax entities at point:
    • pel-kill-word-at-point
    • pel-kill-symbol-at-point
    • pel-kill-sentence-at-point
    • pel-kill-function-at-point
    • pel-kill-sexp-at-point
    • pel-kill-whitespace-at-point
    • pel-kill-filename-at-point
    • pel-kill-url-at-point
    • pel-kill-list-at-point
    • pel-kill-paragraph-at-point
    • pel-kill-char-at-point
    • pel-kill-from-beginning-of-line
    • The command pel-kill-or-delete-marked-or-whole-line is a flexible command that can kill or delete the current line, multiple lines or the currently marked region.
  • The following commands delete text at point and don't store the text in the kill ring:
    • The pel-delete-whole-line command delete the current line, including the line termination.
    • The pel-delete-to-next-visible delete all whitespace characters between point and the next non-whitespace character.
  • The pel-mark-whole-line marks the complete current line excluding the line termination.

8.15   PEL Diff and Merge

PDF Sheet:

Diff and Merge.
PEL Customization:

pel-use-ztree
PEL Key Prefix:
  • pel:diff : <f11> d
  • pel:ediff : <f11> e
    • pel:ediff-buffer : <f11> e b
    • pel:ediff-dirs : <f11> e d
    • pel:ediff-files : <f11> e f
    • pel:ediff-merge : <f11> e m
    • pel:ediff-patch : <f11> e p
    • pel:ediff-regions : <f11> e r

PEL provides key bindings to the following software packages that you may use for compare 2 files, and perform a 2-way merge (comparing 2 files and moving text from one file to the other) and a 3-way merge (such as what's used when merging with your preferred DVCS):

  • Emacs built-in diff package that supports simple diff,
  • Emacs built-in ediff package, a more powerful package capable of performing interactive 2-way and 3-way merge operations.

8.15.1   Merging Files with ediff-merge

Merge the content of two different files inside a *ediff-merge* buffer with the ediff-merge command (bound to <f11> d e m f command.

The following example shows the merging of two different versions of the file pel--base.el stored into 2 different directories.

  • First issue the command and identify the 2 different files to the command prompt.
  • When running Emacs in terminal mode the ediff-merge will show its menu at the end or a message stating that you can type ? to show it. In graphics mode the ediff-merge menu may show up inside a different, floating frame.
  • The command shows 2 windows at the top, with file A on the left side and file B on the right side. The *ediff-merge* buffer that will hold the result of the merge is show under these two windows, above the ediff-merge *Ediff Control Panel* window.
res/ediff-merge-00.png
  • Type n or Space to move to the next difference. The select which of the text to use in the merged: type a to take text from A or b to take text from the B file.

The snapshot shows the first difference. The merge buffer shows the content of file A as variant A and the content of B as variant B in the yellow highlighted area.

res/ediff-merge-01.png

After typing b, the content of file B is copied into the merge, as shown here:

res/ediff-merge-02.png

Type n to move to the next difference.

res/ediff-merge-03.png

Continue until you reach the end of the files. When you're done, type q to terminate the ediff-merge session. The result of the merge is inside the *ediff-merge* buffer. You can then save the content of the buffer into a file.

During the merge session you can decide to go back to a previously merged area and make a different choice. Emacs will prompt to confirm and will merge in you new test selection.

8.15.2   Merge Files with ediff-merge-with-ancestor

The ediff-merge-with-ancestor prompts for the name of 3 files, file A and B and then file C, the ancestor of those files. It opens four windows showing file A and B at the top, and then showing the result of the merge inside the *ediff-merge* buffer on the right and the content of the ancestor file on the right.

The process is very similar to the use of ediff-merge described in the previous section.

After issuing the ediff-merge-with-ancestor command (bound to <f11> e d m F), Emacs shows the 4 buffers: file A, File B on the top and the *ediff-merge* buffer and the ancestor file at the bottom. The Ediff Control Panel* buffer is the current buffer.

res/ediff-merge-wa-00.png

Press ? to bring the help menu.

res/ediff-merge-wa-01.png

Press n to move to the next difference to merge. Emacs highlights the areas in all buffers. Press a or b to select the change from file A or B.

res/ediff-merge-wa-02.png

Press n to go to the next change.

res/ediff-merge-wa-03.png

Next is the result shown after pressing b once. Notice that the content of file B was placed inside the *ediff-merge* buffer on the left while the ancestor shows the original text.

res/ediff-merge-wa-04.png

Next is the result after pressing b again, completing the merge. The original file still shows its original text.

res/ediff-merge-wa-05.png

Press q to complete the merge session and answer the prompt. The result is inside the *ediff-merge* buffer.

res/ediff-merge-wa-06.png

The changes are merged inside the *ediff-merge* buffer. The buffer showing the ancestor file is in read-only mode and cannot be modified. Once you compete the merge you can save the content of the *ediff-merge* buffer into a file with the usual C-x C-s. Emacs will prompt for the file destination which defaults to the name of file A, which would normally be the local file in a DVCS merge operation.

res/ediff-merge-wa-07.png

8.16   PEL Drawing Support

PDF Sheet:

Drawing, PlantUML-Mode.
PEL Customization:
  • pel-use-plantuml,
  • pel-use-flycheck-plantuml.
PEL Key Prefix:
  • pel:draw : <f11> D
  • pel:plantuml: <f11> D u

PEL provides key bindings to enter the Emacs text drawing modes:

  • <f11> D a: toggle artist mode.
  • <f11> D p: enter picture-mode.

☝️ The picture-mode can be quite useful to edit tabular data as well as editing tables for markup languages like reStructuredText or even for lining text vertically in any other type of file; for example lining up text vertically.

8.16.1   Drawing with PlantUML

If you need to draw UML diagram, you can use the plantuml-mode to write the diagram in PLantUML syntax and then generate the diagram. If Emacs is running in graphics mode, the preview shown is an image. If Emacs is running in text mode the preview is a text-based drawing that can easily be inserted inside a source code file. PEL defines the pel:plantuml key prefix (<f11> D u) for the PlantUML-mode commands. See the PlantUML-Mode PDF document for more information.

PEL activates support for PlantUML with the plantuml-mode when the pel-use-plantuml user options is either set to t or to server. When set to t you use a local instance of the PlantUML Java application. You need to install PlantUML. If set to server Emacs communicates with a remote PlantUML server to crete the image. Your data is sent to that external server, so make sure you set this to what you need and do not sent proprietary information across the Internet by mistake!

8.17   PEL Enriched Text Support

PDF Sheet:Enriched Text.
PEL Customization:none
PEL Key Prefix:pel:textmodes : <f11> t m

PEL Enriched Text PDF table shows the Emacs commands available for enriched text.

8.18   PEL File Management Utilities

PDF Sheet:

File Management, Dired.
PEL Customization:
  • pel-pkg-for-completion:
    • pel-use-ido-mode.
  • pel-pkg-for-filemng:
    • pel-use-ffap
    • pel-use-neotree
    • pel-pkg-for-ztree:
      • pel-use-ztree
      • pel-ztree-dir-move-focus
      • pel-ztree-dir-filter-list
      • pel-ztree-dir-show-filtered-files
PEL Key Prefix:
  • pel:file : <f11> f
  • pel:ffap: <f11> f a
  • pel:file-revert : <f11> f r
  • pel:filevar : <f11> f v

The pel-file.el file provides logic to extra the name of a file or a URL from text at point and visit (open) that file inside an Emacs buffer or launch a web browser to load the specified URL.

  • The main command is pel-find-file-at-point-in-window which opens the file or URL. When opening a file, the command accepts a wide range of numeric arguments to specify the window to use. When the file name is followed by a line number the point is moved at that line. If the line number is followed by a column number point is moved to that column. The command supports several formats.
  • Two other utility commands are provided:
    • pel-show-filename-at-point which simply shows the name of the file extracted from point.
    • pel-show-filename-parts-at-point which displays the components extracted from point. It's mainly used for debugging when unexpected formats are encountered.

PEL also provides the ability to use the ffap (find file at point) standard library which complements the PEL command that can also open a file or URL at point (but can also specify a window by coordinates and handle line and column numbers). PEL activates the special pel:ffap binding when pel-use-ffap user option is set to t. If you prefer the standard ffap binding, then set pel-use-ffap user option to ffap-bindings.

When the pel-use-ido-mode user option is set to t pel-init activates IDO-mode everywhere, enables flex matching and prevents prompt when creating new buffers with C-x b.

In Dired mode, the normally unassigned 'z' key is mapped to the command pel-open-in-os-app. It opens the file or directory at point with the OS-registered application. The <f11> f f key sequence is also mapped to that command. The current implementation (in pel-filex.el) only supports Linux, macOS and Windows.

Credits:

Thanks to Jason Blevins for the idea taken from his blog and to Xah Lee for ideas from his Open File in External App page.

To see a textual representation of a directory tree, PEL provides access to the neotree and z-tree packages. They are activated by the pel-use-neotree and pel-use-ztree user option respectively.

PEL provides the <f11> <1> f key binding to quickly access the pel-pkg-for-filemng customization group editing buffer to modify the relevant user options.

8.19   PEL File and Directory Local Variable Control Support

PDF Sheet:

File and Directory Local Variables
PEL Customization:

none
PEL Key Prefix:
  • pel:filevar : <f11> f v
  • pel:dirvar : <f11> f v d

PEL provides a set of key bindings to manage local file variables and local directory variables.

See the File and Directory Local Variables PDF table.

8.20   PEL Font Management Utilities

PDF Sheet:Faces and Fonts.
PEL Customization:none
PEL Key Prefix:none

The file pel-font.el provides utilities to control the font size of all windows when Emacs runs in graphics mode, to complement what already exists in standard GNU Emacs. The available commands are:

  • pel-font-increase-size-all-buffers, bound to <s-kp-add>. On the macOS keyboard: ⌘-+, using the + on the keypad.
  • pel-font-decrease-size-all-buffers, bound to <s-kp-subtract> On the macOS keyboard: ⌘--, using the - on the keypad.
  • pel-font-reset-size-all-buffers, bound to <s-kp-0>. On the macOS keyboard: ⌘-0.

The key binding selected correspond to what is used on macOS for manipulating the font size of the Terminal.app application when the super modifier key is set to the macOS command (⌘ ) key.

8.21   PEL Frame Management Utilities

PDF Sheet:Frames.
PEL Customization:pel-use-framemove
PEL Key Prefix:pel:frame : <f11> F

The file pel-frame-control.el provides a set of utilities to manage Emacs frames. Emacs supports frames both when it operates in graphics mode and in terminal (TTY) mode. In terminal mode, you can only see one frame at a time; all frames of one instance of Emacs running in terminal mode share the same terminal OS window (called a frame in Emacs nomenclature).

This PEL file provides the following commands:

  • pel-toggle-frame-fullscreen toggles the frame to and back full screen mode when Emacs is running in graphics mode. If Emacs is running in terminal mode the command prints a message. For some environments the message describes what must be done to toggle the terminal window to full-screen and back. At the moment PEL is able to describe what must be done on macOS with the Terminal.app and iTerm.app.
  • pel-show-frame-count displays the total number of frames used by this instance of Emacs and the number of those frames that are currently visible.
  • The following two commands work when several frames are used by Emacs whether it is running in graphics mode or terminal mode:
    • pel-next-frame moves point to the next frame.
    • pel-previous-frame moves point to the previous frame.

8.22   PEL Function Keys Bindings

PDF Sheet:Function Keys, F11 Keys.
PEL Customization:none
PEL Key Prefix:N/A

PEL avoids remapping most standard GNU Emacs key bindings. Instead PEL uses the following function keys:

  • F2, bound to bm-next (from visible bookmarks) to quickly move to next visible bookmark when the pel-use-bm user option is t.
  • F5, bound to repeat.
  • F6, the pel:f6 prefix, which provides quick access to some often used commands, and generic template insertion commands that work in all major modes.
  • F7 is used for Hydra keys key sequences when pel-use-hydra is t.
  • F11, the pel: prefix , is the main prefix key for PEL, providing access to a large set of key bindings and second-level key prefixes.
  • F12 is a mode-sensitive key prefix with quick access bindings for the current major mode. The F12 F12 key sequence (normally referred to as <f12> <f12> in this document and PDF tables) provides access to specialized text template insertion in the major modes of several programming and markup languages.

The use of function keys and Emacs modifier keys is shown in the Function Keys PDF table, reproduced here:

res/fn-keys.png

The F11 acts as a the main prefix for PEL: the prefix pel:. Several sub-prefixes are available after <f11> but also some command bindings using other keys, like cursor keys with or without modifiers.

To easily see what's available it's best to activate the which-key package to show the available keys following a prefix key, like the F11 key. Here's what the echo area looks like after pressing the F11 key when which-key is installed and activated:

res/pel-which-key.png

To install and activate it, you must set the pel-use-which-key customize variable to t. Use the M-x customize command and search for pel-use-which-key. Set it to t. The restart PEL by using M-x pel-init. PEL will download and install the which-key package and will activate it.

8.23   PEL Grep Support

PDF Sheet:

Grep, Projectile Project Interaction Manager.
PEL Customization:
  • pel-use-ripgrep
  • pel-use-ag
  • pel-use-projectile
PEL Key Prefix:

pel:grep : <f11> g

PEL provides the pel:grep (<f11> g) key map to regroup grep commands. If the pel-use-ripgrep user option is t that includes access to the rg command that uses the fast ripgrep executable.

When pel-use-projectile is set to t, the ripgrep.el package is also used because projectile uses ripgrep.el instead of the rg package. Both provide access to the ripgrep executable.

When pel-use-ag is set to t, the ag (ag, the silver searcher) is also available. This is another fast grep alternative that requires the ag command line.

You must install the ripgrep and ag command line utilities separately.

8.24   PEL Help Support

PDF Sheet:

Help
PEL Customization:
  • pel-use-ascii-table
  • pel-use-free-keys
  • pel-use-which-key
PEL Key Prefix:
  • pel:help : <f11> ?
  • pel:apropos : <f11> ? a
  • pel:describe : <f11> ? d
  • pel:emacs : <f11> ? e
  • pel:info : <f11> ? i
  • pel:keys : <f11> ? k

PEL provides a set of key bindings to request help information, bound to the pel:help key prefix (<f11> ?) and it sub-prefixes. Several of these commands are accessible via standard Emacs bindings of the <f1> and the C-h keys. There are also some other, as shown in the Help PDF table. The customization include the pel-use-free-keys and pel-use-which-key variables. The latter is enabled by default; it help see the available bindings following key prefixes.

You can also open the local copy of the PDF reference sheet file that describes the commands and key bindings accessible through a given key prefix by using the F1 key inside that key prefix. For example, the PEL key prefix for help and information commands is pel:help bound to the <f11> ? key sequence. To open the HELP PDF file, type <f11> ? <f1>. Not all PEL key prefixes have this key, but most have.

8.25   PEL Hide/Show Code Block Support

PDF Sheet:Hide/Show Code Block
PEL Customization:none
PEL Key Prefix:pel:hideShow : <f11> /

Emacs provides the Hide/Show minor mode to collapse and expand blocks of source code. To use its commands it you have to activate the minor mode first. PEL provides commands that automatically activates the Hide/Show minor mode and provides easy to use key-bindings provided by the pel:hideShow <f11> / key-map. The Hide/Show Code Block PDF document describes the keys and commands provided by PEL as well as the standard Emacs commands and key bindings.

8.26   PEL Highlight and Whitespace Management Support

PDF Sheet:

Highlight , Whitespaces.
PEL Customization:

pel-use-rainbow-delimiters, pel-use-vline.
PEL Key Prefix:
  • pel:highlight : <f11> b h
  • pel:whitespace : f11> t w
  • pel:align : <f11> t a

The file pel-highlight.el provides the following simple utility commands.

  • The following help manage current line background highlighting, useful to quickly identify the location of the cursor on a large display:
    • With pel-set-highlight-color you can select the color of the highlight line by name. Use the list-colors-display command (bound to <f11> ? d c in PEL) to list all colours and their names.
    • The pel-toggle-hl-line-sticky command toggles line highlighting of only the current window or all windows that hold the current buffer.
  • It also provides the following whitespace management commands:
    • pel-toggle-show-trailing-whitespace toggles the highlight of trailing whitespaces in the current buffer.
    • pel-toggle-indicate-empty-lines toggles highlighting of empty lines.
    • pel-toggle-indent-tabs-mode toggles the use of hard tabs and whitespace for indentation inside the current buffer (but does not tabify or untabify existing content.) It displays what's being used now.
  • When pel-use-vline user option is t the <f11> b h v key is bound to vline-mode which toggles a vertical bar across the current window at the cursor location.

8.27   PEL Indentation Support Utilities

PDF Sheet:Indentation.
PEL Customization:none
PEL Key Prefix:pel:tab : <f11> <tab>

The file pel-indent.el includes some very basic utilities for simple indentation control, complementing what is available in Emacs. The available commands are:

  • pel-indent-lines indent the current line or all lines included in the current marked region, regardless of the point and mark position.
  • pel-unindent-lines un-indent the current line or all lines included in the current marked region, regardless of the point and mark position.
  • pel-indent-rigidly indents the current line or marked region, this command extends the Emacs indent-rigidly command.

The PEL support for indentation will evolve as support form various types of files, programming languages and markup languages evolves.

8.28   PEL Input Method Control

PDF Sheet:Input Method.
PEL Customization:none
PEL Key Prefix:pel:text : <f11> t

PEL rebinds the C-\ prime key, normally bound to toggle-input-method, used to select another Emacs input method, to pel-kill-from-beginning-of-line. PEL binds toggle-input-method to <f11> t i instead. And to change the alternate input method, it binds set-input-method to <f11> t I. To lists all input methods, PEL provides <f11> ? d i bound to list-input-methods.

8.29   PEL Key Chords Support

PDF Sheet:

Key Chords
PEL Customization:

pel-pkg-for-key-chord:

  • pel-use-key-chord
  • pel-use-key-seq
  • pel-key-chords
  • pel-key-chord-two-keys-delay
  • pel-key-chord-one-key-delay
  • pel-key-chord-in-macros
PEL Key Prefix:

none

PEL provides access to the key-chord external library when the pel-use-key-chord user option is set to either t (to activate key-chords when the key-chord-mode is ttuned on) or to use-from-start (to activate the key-chord mode and all defined global key-chords when Emacs starts).

If you set the pel-use-key-seq suer option to t, PEL also provides access to the key-seq external library and allow you to identify your key-chord to be a key-seq instead.

A key-chord is two characters typed simultaneously quickly or the same key typed twice quickly that trigger a specified action. The action may be inserting some other text, moving the piint, executing a specified function or executing a specified Emacs command expressed as an Emacs Lisp lambda expression. The key-chord can be made of any ASCII printable characters and ASCII control characters. These keys must be type quickly; the order into which they are typed does not matter.

For some fast typist using two keys that might be inside normal words in one order but not the other, it might be interesting to be able to specify the key order for a special action. This is what key-seq does: it imposes an oorder for the 2 characters tyoped quickly. Different order is not triggerring the special action. Note that key-seq only accepts ASCII printable characters (ie. in the range decimal 32 to 26 inclusive.)

Both key-chord and key-seq can be global, where they are always accessible in Emacs, and mode-specific. A mode specific key-chord or key-seq is only available in buffers where the specific mode is active. For mode-specific key-chord or key-seq, PEL schedule the loading of the definitions when the file identifying the mode is loaded in Emacs.

With PEL, you define the key-chord and key-seq via customization. They are stored inside the pel-key-chords user option.

PEL provides a set of key-chords by default which you can modify via the Emacs customize buffer for the pel-pkg-for-key-chord customize group. These also provide examples of how to specify your own key-chords or key-seqs.

PEL provides the <f11> <f2> K key binding to quickly access this customize group and the <f11> M-K binding to toggle the key-chord-mode on and off.

PEL defines several default key-chords that use Emacs Lisp lambda form. This is the most flexible way to define a key-chord. It allows you to perform anything with you command, just as if you were writing Emacs Lisp code in your initialization file. It also allows the use of keyboard prefix argument keys, just like any other Emacs command. With this you can prevent the execution of code associated with a key-chord in read-only buffer, or pass numeric arguments that modify the behaviour of the code. You have the full flexibility of Emacs Lisp at your disposal.

Be careful with this if you do not know Emacs Lisp: if you change a setting that refer to a symbol that is not known when you open Emacs's customize UI, Emacs customize UI will report a mismatch error and you will not be able to make any modification. If this happens to you, edit your customization file and delete the entry for pel-key-chords from the file, save the file back and restart Emacs. If you followed the installation instructions the name of this file is "~/.emacs.d/emacs-customization.el".

The logic for managing key-chord definitions stored in customization user option is stored in the file pel-key-chord.el. The default values for the pel-key-chords user option is in the pel--options.el file.

For more information see the Key Chords PDF Documentation.

8.30   PEL Keyboard Macro Utilities

PDF Sheet:Keyboard Macros.
PEL Customization:pel-kmacro-prompts.
PEL Key Prefix:none

The file pel-kbmacros.el implements pel-kmacro-start-macro-or-insert-counter used to replace the standard kmacro-start-macro-or-insert-counter to record a keyboard macro. If the user option pel-kmacro-prompts is set to t, the PEL function checks if the macro is already defined and if it is, prompts before allowing to replace the existing keyboard macro with a new one. It just offer a little protection. And this protection can be reset by executing the second command: pel-forget-recorded-keyboard-macro. In some case that level of protection might be annoying, to disable it completely and restore the normal Emacs keyboard macro recording without any protective prompting, just set the pel-kmacro-prompts to nil.

8.31   PEL Line Control Utilities

PDF Sheet:Display Lines.
PEL Customization:none
PEL Key Prefix:pel:linectrl : <f11> l

The file pel-line-control.el contains:

  • 2 commands that move the cursor to the previous and next logical lines, lines that when wider than the current window, wrap around:
    • pel-lc-previous-logical-line and
    • pel-lc-next-logical-line.
  • 1 command to toggle the display of the current line and column on the mode line. In some cases the mode line is too short to display all information, removing the display of point's line and column frees real-estate to allow seeing more of the remainder of the mode line.

PEL provides a set of commands under the pel:linectrl key prefix, <f11> l, which deal with those commands and other Emacs line control related commands.

8.32   PEL Mark Management Utilities

PDF Sheet:Marking.
PEL Customization:pel-use-expand-region.
PEL Key Prefix:pel:mark : <f11> .

The file pel-mark.el provides utilities to help manage the mark and the mark ring buffer.

  • pel-mark-ring-stats displays information on global and buffer local mark and mark rings.
  • pel-popoff-mark-ring removes the top entry from the buffer's mark ring.
  • The following 2 commands allow marking lines quickly and PEL binds these commands to keys that include cursor to make the operation natural. Being able to mark lines this way helps on various types of operations on regions, like commenting lines, kill, copy, etc... The following two commands are provided:
    • pel-mark-line-up mark the current line: it places point at the beginning of the line and the mark at the end. If the mark is already active, the command extends the region one more line up. One of the PEL key bindings for this command is M-S-<up>.
    • pel-mark-line-down mark the current line: it places the mark at the beginning of the line and point at the end. If the mark is already active, the command extends the region on more line down. One of the PEL key bindings for this command is M-S-<down>.
  • The following commands correspond to code provided by Mickey Petersen in his great web site in the page Fixing the mark commands in transient mark mode. These are:
    • pel-push-mark-no-activate pushes point to the buffer's mark-ring without activating the region. PEL binds <f11> . SPC to this command.
    • pel-jump-to-mark jumps to the next mark in the buffer's mark-ring and then rotate the ring. PEL binds <f11> . ` to this command.
    • pel-exchange-point-and-mark-no-activate does the same thing as the Emacs command exchange-point-and-mark but without activating the region. PEL binds <f11> . , to this command.

8.33   PEL Markup Language Support

PEL markup language support assigns the F12 key as the prefix key for PEL markup-specific commands. The prefix key is the same for other markup languages (or programming languages) but the key bindings after the prefix differ, while keeping them as similar as possible.

8.34   PEL AsciiDoc Support

PDF Sheet:AsciiDoc support.
PEL Customization:pel-use-asciidoc
PEL Key Prefix:none

When pel-use-asciidoc is set to t, PEL activates the adoc-mode for files with the .adoc file extension.

8.34.1   PEL reStructuredText Support Utilities

PDF Sheet:

reStructuredText mode.
PEL Customization:
  • pel-use-rst-mode,
  • pel-rst-adornment-style,
  • rst-preferred-adornments.
PEL Key Prefix:
  • Globally: pel:for-reST : <f11> SPC r
  • For buffers in rst-mode: <f12>
    • Sub-keys: pel:rst-adorn-style : <f12> A

The file pel-rst.el provides features that complement the support for reStructuredText markup provided by the rst.el, which implements the rst-mode and which is distributed with standard GNU Emacs.

The following 3 commands simplify the creation of reStructuredText hyperlinks and where their external hyperlink targets are located:

  • First you identify a location inside the file where the next external hyperlink target reference will be written by using the pel-rst-set-ref-bookmark which puts an actual Emacs bookmark to that location.
  • Then to create a hyperlink inside the text, use the pel-rst-makelink. It adds the relevant markup around the word or marked region at point, move point to the location where the explicit hyperlink target references are located (using the location you previously set) and enters the first portion of the hyperlink markup. You can then type or yank/paste the required URI to complete the statement. After that you can use pel-jump-to-mark (normally bounded to M-`) to jump back to where you were typing the text.
  • The pel-rst-goto-ref-bookmark moves point to where the external hyperlink target references are located.

Note that pel-rst-set-ref-bookmark sets an Emacs bookmark to the location, so it is retained across sessions like other bookmarks. The bookmark has a special name which uses the "RST-" prefix followed by the name of the current file. This means that only one explicit hyperlink target reference location can be remembered per file. You can set any number of them, but only the last one will be retained inside the bookmark across Emacs sessions.

8.34.1.1   Section Adornment Support

The default support for line title adornments done by the rst-adjust function does not always work and fails when some markup is used. PEL provides a set of simple commands that adorn the current line with the character supported by the specified level. The pel-rst-adorn command takes a numeric argument to add the adornment specified by the customization list of adornments stored in the rst-preferred-adornments variable. To make life simple PEL also defines 10 commands to adorn the current line with the adornment level specified by the command name and binds these commands to easy to use keys listed in the table below. For example, to adorn a line with the level 2 adornment just type <f12> 2 in a buffer in rst-mode. For other buffers it's still possible to use the commands, but the key sequence is longer, in this case it would be <f11> SPC r 2, as explained here.

For all styles:

  • level 0 is created with the key <f12> t,
  • level 1 to level 9 use <f12> 1 to <f12> 9,
  • level 10 is using the <f12> 0 key.

The following commands allow creating line adornments for sections at levels relative to the previous section or change the section level of the current line:

  • pel-rst-adorn-same-level adorn the line at the same level as the previous section. If an adornment already exists it replaces it.
  • pel-rst-adorn-increase-level adorn the line with a level higher than the previous section level (creating a sub-section) if the line has no section underlining adornment. If it has one, it increases the level.
  • pel-rst-adorn-decrease-level adorn the line with a level lower than the previous section level (creating a sub-section) if the line has no section underlining adornment. If it has one, it decreases the level.
  • pel-rst-adorn-refresh refreshes the adornment length of the current line. This is useful when changing the text of the line.

PEL supports 3 types of section adornment styles:

  • rst-mode default, a style with a title (level 0) and 7 other levels
  • Sphinx-Python style, a style with 6 levels supported by Sphinx.
  • CRiSPer style, a style with a title level (level 0) and 10 other levels.

The default style is selected by the pel-rst-adornment-style user option. It can be changed for the current buffer using the following commands:

  • pel-rst-adorn-default selects the default style,
  • pel-rst-adorn-Sphinx-Python selects the Sphinx-Python style,
  • pel-rst-adorn-CRiSPer selects the CRiSPer style.

When editing a buffer that uses the rst-mode, PEL sets the mode sensitive F12 prefix to pel:for-reST so the above commands can be accessed using the following key strokes:

key binding
Hyperlink control  
<f12> . pel-rst-makelink
<f12> g pel-rst-goto-ref-bookmark
<f12> s pel-rst-set-ref-bookmark
Section Level Adornment  
<f12> t pel-rst-adorn-title
<f12> 1 pel-rst-adorn-1
<f12> 2 pel-rst-adorn-2
<f12> 3 pel-rst-adorn-3
<f12> 4 pel-rst-adorn-4
<f12> 5 pel-rst-adorn-5
<f12> 6 pel-rst-adorn-6
<f12> 7 pel-rst-adorn-7
<f12> 8 pel-rst-adorn-8
<f12> 9 pel-rst-adorn-9
<f12> 0 pel-rst-adorn-10
Select Adornment Style  
<f12> A d pel-rst-adorn-default
<f12> A S pel-rst-adorn-Sphinx-Python
<f12> A C pel-rst-adorn-CRiSPer

The longer to type global prefix is always available: <f11> SPC r.

All of the above is activated by pel-init only when the pel-use-rst-mode user option is set to t.

8.34.1.2   Text Emphasis

PEL provides four commands to put emphasis markup aound the current word or marked area. The following commands are available for reStructuredText:

key Emphasis
<f12> b Bold
<f12> i Italic
<f12> l Literal
<f12> ` Interpreted text

8.35   PEL Mouse Support

PDF Sheet:Mouse.
PEL Customization:none
PEL Key Prefix:none

When Emacs runs in graphcsi mode it supports the mouse seemlessly. When Emacs runs in Terminal (TTY) mode, however, the mouse events are normally used by the terminal emulator, not Emacs. The mouse support is available by activating the xterm-mouse-mode. The PEL system binds the <f11><f12> key sequence for this command and also activates mouse-driven scrolling. Turn the xterm-mouse-mode off if you want to copy and paste text in or out of the terminal/Emacs session from/to another process.

See the Mouse PDF document for more information.

8.36   PEL Menu Index Utilities

PDF Sheet:Menus.
PEL Customization:none
PEL Key Prefix:pel:menu : <f11><f10>

The file pel-imenu.el provides code that changes the order of entries of the MenuBar Index entries so that they are easier to use with source code files and markup files. The entries are ordered in the order of appearance inside the file instead of placing all sub-menus at the top the way Emacs normally does it.

When pel-init is called it calls pel-imenu-init which installs the pel-imenu-outline--split-menu utility function. That function holds the code to change the menu entry order.

Credit:
The code of that utility function is based on pdf-tools/pdf-outline code mentioned here.

It is possible to restore Emacs original behaviour by executing the command pel-toggle-imenu-index-follows-order and then forcing a menu entry re-scan.

PEL provides other key bindings to manage the MenuBar but also accessing the menu via the mini-buffer. The key prefix for these command bindings is <f11><f10>.

8.37   PEL Narrowing Documentation

PDF Sheet:Narrowing.
PEL Customization:none
PEL Key Prefix:none

PEL provides the Narrowing PDF table listing Emacs commands dealing with the powerful concept of narrowing.

8.38   PEL Navigation Support

PDF Sheet:

Navigation.
PEL Customization:
  • Group: pel-pkg-for-navigation (<f11> <f2> n):
  • pel-use-any
  • pel-use-ace-link
PEL Key Prefix:

none

The pel-navigate file provides a collection of navigation commands that complement the standard Emacs navigation commands.

  • pel-beginning-of-line is meant to replace beginning-of-line as it does the same and extends it: if point is already at the beginning of the line then it moves it to the first non-whitespace character.
  • pel-end-of-line is also replacing end-of-line. If the point is already at the end of the line, then point moves to beginning of trailing whitespace if there is any (otherwise point does not move).
  • pel-newline-and-indent-below is useful as a variant of the return key.
  • pel-find-thing-at-point provides a search capability without the need for a tag database but it is limited in what it can find. It's a poor man cross reference.
  • pel-show-char-syntax shows the character syntax of the character at point.
  • pel-forward-token-start and pel-backward-to-start move forward or backward to the beginning of a text semantic token as defined by Emacs character syntax for the current buffer.
  • pel-forward-word-start moves point to the beginning of next word. This complements what's already available in standard Emacs: forward-word and backward-word.
  • pel-forward-syntaxchange-start and pel-backward-syntaxchange-start move point forward or backward to the character syntax change character. This can be useful to debug syntax characters for a specific mode.
  • pel-next-visible and pel-previous-visible move point to the next or previous visible (non whitespace) character.
  • pel-home and pel-end implement a quick, multi-hit movement to the beginning or end of the current field, line, window and buffer. These commands are similar to the home and end CRiSP/Brief commands. They also support the multiple window scroll sync provided by the pel-scroll commands.
  • pel-beginning-of-next-defun move point to the beginning of the next function definition. This complements beginning-of-defun which only reaches the same location by moving backwards.

PEL also provides ability to use the avy and ace-link external packages to provide super efficient navigation inside windows and across windows using the keyboard home row!

The details are available in the Navigation PDF table.

8.38.1   Navigation Using imenu detected definitions

Emacs provides a powerful item detection and indexing system called imenu. Each major mode can support imenu to quickly identify important locations inside the file such as the location of function or type definitions inside a programming language file or the section headers inside a markup file.

PEL takes advantage of this and extends it with available input completion mechanisms to provide a set of easy to use key sequences to quickly navigate to such locations inside the current buffer or to any currently opened buffer of the same major mode as the current one.

The imenu system parse the content of the buffers. When you modify the buffer you may need to manually re-scan the buffer to update imenu indexing system. PEL provide the <f11> <f10> r key sequence for that.

To pop a menu of the current index list PEL provides the <f11> <f10> <f10> key sequence. The following screen shot shows what it does when used inside the imenu.el file.

The provided menu is often a hierarchical menu of entries: you can select function, types, variables, classes and then their names or sub-names, etc..

res/m-g-h/imenu-popup.png

PEL also provide the M-g h and the M-g M-h key sequences to prompt for one of the items by name or partial name using one of the powerful input completion like Ido, Ido-grid, Ido-vertical or Ivy.

You can select the completion mechanism via the input completion customization. You can also change the mode used during an editing session (although your choice won't persist across editing sessions). Use the M-g C-h key sequence to select the mode.

Here's what it looks like when using the M-g h key with Ido-grid with the grid expanded.

res/m-g-h/ido-grid.png

And what it looks when using Ivy:

res/m-g-h/ivy.png

8.38.2   Navigation in a large file using imenu and speedbar

When navigating in a very large file, the imenu pop-up menu will be split into several sections. It does not give you an overview of the content of the file though. For that you can use the Speedbar. Both present information in hierarchical fashion. You can customize the speedbar to display all elements of the same type as a continuous list.

Here's an example using the file sqlite3.c. This file contains all the C code of the SQLite 3 database: about 231,756 lines.

The following screen shot shows the file open in Emacs running in terminal mode with that file opened. The imenu popup window is opened by typing <f11> <f10> <f10>:

res/navigation/def-lists/sqlite3-imenu-popup-top.png

The list is split in several sections. The first section is Class with is the name of a sub-section. Later, somewhere else in that file, using the same command and selecting the Class section, imenu shows the list of structure names also organized in sub-sets.

res/navigation/def-lists/sqlite3-imenu-popup-class.png

Here's what you see on the same file when opening the Speedbar in terminal mode. With PEL use <f11> M-s to open the speedbar.

res/navigation/def-lists/sqlite3-speedbar-top.png

Without moving point you can scroll the speedbar window using the <M-S-f6> key stroke and see more of it.

res/navigation/def-lists/sqlite3-speedbar-scrolled-down.png

8.39   PEL Number Keypad Support

PDF Sheet:Number Keypad.
PEL Customization:none
PEL Key Prefix:none

The file pel-numkpad.el implements the PEL number keypad support.

The number keypad available on various keyboard differ in behaviour. Some keyboard have a NumLock key, others, like Apple keyboards do not have it. PEL support different keyboards thta have a number keypad, and provides its own management of the Numlock, with the <f11> # key mapped to pel-toggle-mac-numlock to provide two set of commands: one when in Numlock mode and another when Numlock mode is off. In that latter mode, the commands normally associated to cursor keys are provided, but also the pel-home and pel-end as well as several copy and kill commands.

Refer to the Number Keypad PDF document for more information.

8.40   PEL Package Management Documentation

PDF Sheet:Packages.
PEL Customization:none
PEL Key Prefix:none

PEL provides the Packages PDF table listing Emacs commands dealing with Emacs package management.

8.41   PEL Programming Language Support

PEL programming language support assigns the F12 key as the prefix key for the programming language. The prefix key is the same for other programming languages (or markup languages) but the key bindings after the prefix differ, while keeping as similar keys as possible.

Note:
PEL support for programming languages is still evolving. It will be enhanced with upcoming versions.

Programming Language Families

BEAM-VM Programming Languages:

PEL supports several BEAM programming languages, including:

For the moment support for Erlang and LFE are the most evolved. Erlang support is very evolved. LFE support also because it inherit the capabilities of Lisp-based languages. Support for Elixir and Gleam is experimental.

Curly-Bracket Programming Languages:

PEL provides explicit support for the following curly-bracket programming languages:

It also provides experimental support for:

LISP-based Languages:

PEL provides explicit support for the following LISP-based programming languages:

8.41.1   PEL Apple-Script and Audio Narration Support

PDF Sheet:

Apple-Script.
PEL Customization:
  • Group: pel-pkg-for-programming
  • Activation:
    • pel-use-applescript
    • pel-use-hydra
  • Configuration:
    • pel-mac-voice-name
PEL Key Prefix:

pel:narrate : <f8>

PEL provides basic Apple-Script support via the apples-mode external package: that does basic syntax colouring and provides a scratch-pad to write some Apple-Script code to copy somewhere else.

If your Emacs is running a=on a macOS computer PEL also provides a set of commands that read text from a buffer and uses the Apples system voice synthesis to say the text out-loud. Essentially providing a text-to-speech system. By default the code uses the voice that is selected by default on the system but you can also change it by setting the pel-mac-voice-name user option variable. Normally this would only work on the Cocoa-based (Graphics mode) Emacs, but PEL also implements basic support for Emacs running in Terminal (TTY) mode.

A couple of other functions are provided to issue Apple-Script commands from Emacs.

More information is available in the Apple-Script PDF table.

8.41.2   PEL Support For C

Language Family:

Curly-Bracket Programming Language
PDF Sheet:

𝕻𝔩 - C
PEL Customization:
  • Group: pel-pkg-for-c
  • Activation: none
  • Configuration:
    • pel-c-indent-width
    • pel-c-tab-width
    • pel-c-use-tabs
    • pel-c-bracket-style
    • pel-c-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-c : <f11> SPC c
  • From a buffer in c-mode: <f12> and <M-f12>

PEL provides support for the C Programming Language via Emacs built-in c-mode. No activation is necessary since the c-mode is built-in Emacs. However, configuration of important editor behaviour such as the indentation/bracket style and the indentation is completely controlled by user options listed above and can easily be changed using Emacs customize system. PEL also provides easy access to commands that can change the CC Mode behaviour on which the c-mode is based via the pel:for-c key-map, bounded to the F12 key for each buffer in c-mode.

8.41.2.1   C Style Control

Ideally the editor should support various indentation styles for the C preprocessor directives. A selection of styles is shown in the next section.

I am working to implement the ability to support all of these styles. But it is work in progress. I will update this section once this work is done.

8.41.2.1.1   Indentation of C pre-processor statements

All examples are using the bsd indentation style.

Style 1: no indentation

#ifdef SOMETHING
  #if SOMETHING_ELSE
    #define SOMEONE 1


      for (...)
      {
        if (foo)
        {
          if (bar)
          {
      #ifdef __WIN32__
            c = GetTickCount();
      #else
            c = clock();
      #endif
          }
        }
      }

Style 2: all indented

for (...)
{
  if (foo)
  {
    if (bar)
    {
      #ifdef __WIN32__
        c = GetTickCount();
      #else
        c = clock();
      #endif
    }
  }
}

Style 3: indented

for (...)
{
  if (foo)
  {
    if (bar)
    {
      #ifdef __WIN32__
      c = GetTickCount();
      #else
      c = clock();
      #endif
    }
  }
}

Style 4: anchored indented

for (...)
{
  if (foo)
  {
    if (bar)
    {
#     ifdef __WIN32__
        c = GetTickCount();
#     else
        c = clock();
#     endif
    }
  }
}
8.41.2.2   C Code Templates

PEL supports yasnippet for your basic templating needs. It also supports the built-in tempo skeleton system which provides a powerful templating system but requires Emacs Lisp knowledge. PEL provides a set of tempo skeleton templates inside the file pel-skels-c.el that are made available by the commands accessed via the pel:c-skel key prefix which is mapped to the <f12> <f12> key sequence in any c-mode buffer.

See the C PDF and related tables for more information on the various key sequences available.

8.41.2.2.1   PEL Tempo Skeleton Templates Flexibility

Most PEL tempo skeleton based templates use formats that are controlled by Emacs user option variables.

Emacs user options are just specially identified Emacs variables.

Since Emacs can read variables from information on a file and from the special .dir-locals.el file (which affects all files in the directory tree) it becomes possible to have a complete control of the various style elements for C files and you can have different ones inside different directory trees, have special settings for some files.

This is extremely flexible.

8.41.2.2.2   Controlling PEL Tempo Skeletons for C

The PEL tempo skeletons used to generate source code come in two major groups:

  • The generic skeletons which are programming language agnostic and produce generic code such as file module header blocks. These skeletons do not insert programming language specific specializations.
  • The programming or markup language specific skeletons. These skeletons are aware of the target programming or markup language and may insert specialized source code constructs.

Most of the PEL tempo Skeletons are controlled by a set of customization user option variables. These affect the generated code, the style, the format, etc...

To see or modify those user option variables the easiest way is to use the pel-browse-group command, bound to <f11> <f2> b and specify the name of the PEL customization group related to C programming, pel-c-code-style.

You can also look at it from the group pel-pkg-for-programming or from the pel-pkg-for-skeletons. The screenshot below shows 2 windows with the *Customize Browser* buffers showing these 2 groups within their context.

res/pel-customizing-skeletons.png

8.41.2.2.3   C file module/header block template

To insert a C file module/header block inside a C file, use the <f12> <f12> h key sequence. It will prompt for the purpose of the file. Once you hit the return key it inserts the comment block at the beginning of the C file according to the user options that are part of the pel-c-code-style customization group. See the example in the next section.

8.41.2.2.3.1   In a .c C file

For this example, the CC mode variables and user option variables are all set to their default values except the first 4 listed in the following table:

Variable Value Description
user-full-name ➽ Set your full name.
user-mail-address ➽ Set you email address in this variable. Emacs tries to infer it but it may only contain your user name and your computer name.
c-block-comment-flag nil Emacs internal variable. Use C-style comment: /* */. Change with <f12> M-;.
pel-c-skel-with-license t Insert a source code license into the module/header block.
pel-c-skel-with-license t Insert an open source license inside the module header. The license text is based on the lice external package and the license type must be identified in the lice:default-license.
pel-c-skel-with-license string You can also specify the name of license type as a plain string. That string will be inserted instead of the complete license text.
lice:default-license glp-3.0 Use the GPL V3.0 license.
pel-c-skel-comment-with-2-stars t Use ** as continuation comment.
pel-c-skel-use-separators t Use separator lines.
pel-c-skel-doc-markup nil Identifies the markup style in comment: none used.
pel-c-skel-insert-file-timestamp t Insert a time stamp that is updated automatically when the file is saved.
pel-c-skel-use-include-guards nil Used for C header files only: if set header files have include guards. You can select between no include-guard, include-guard using #pragma once statement, classic include guard with #ifdef pre-processor statement or an include-guard that uses a #ifdef pre-processor statement with a symbol that incorporates a UUID, making it unique.
pel-c-skel-module-header-block-style nil The selected style for the module header: use PEL's default style.
pel-c-skel-module-section-titles ➽

Use the module sections identified by PEL's default:

  • "Module Description",
  • "Header Inclusion",
  • "Local Types",
  • "Local Variables", and
  • "Code".

The value can also be set to nil to prevent insertion of the sections.

When typing the <f12> <f12> h key sequence inside the buffer of the file monitor.c, the command prompts for the file purpose, entering "process monitoring facilities" and hitting return the command inserts the following code in the buffer:

/* C MODULE: monitor.c
**
** Purpose   : Process monitoring facilities.
** Created   : Thursday, August 27 2020.
** Author    : Pierre Rouleau <[email protected]>
** Time-stamp: <2020-08-27 22:28:12, by Pierre Rouleau>
**
** Copyright (C) 2020  Pierre Rouleau
**
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation, either version 3 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program.  If not, see <http://www.gnu.org/licenses/>.
**
*/
/* ------------------------------------------------------------------------ */
/* Module Description
** ------------------
**
** Ⓜ️
**
*/

/* ------------------------------------------------------------------------ */
/* Header Inclusion
** ----------------
*/

Ⓜ️

/* ------------------------------------------------------------------------ */
/* Local Types
** -----------
*/

Ⓜ️

/* ------------------------------------------------------------------------ */
/* Local Variables
** ---------------
*/

Ⓜ️

/* ------------------------------------------------------------------------ */
/* Code
** ----
*/

Ⓜ️

/* ------------------------------------------------------------------------ */

Your name is written instead of mine, and your email address is used. Your email address is taken from the user-mail-address Emacs user option if it is set otherwise it attempts to compute it through other Emacs user option variables. See Emacs User Identification documentation for more information.

The Ⓜ️ in the code above identify the tempo marker locations. Once you use a PEL command to insert a PEL tempo skeleton template you also automatically activate the pel-tempo-mode, a minor mode where you can use C-c . to move to the next tempo marker and C-c , to move point to the previous tempo marker. When the pel-tempo-mode is active the ‡ lighter shows in the buffer's mode line. You can toggle the pel-tempo-mode minor mode with the <f12> <f12> <space> key sequence.

The comment block contains sections because the user option pel-c-skel-insert-module-sections is set to t. This always includes the section with the "Module Description" title. The following section names ("Header Inclusion", "Local Types", etc..) are identified by the user option pel-c-skel-module-section-titles.

8.41.2.2.3.2   In a C header file

If you use the exact same command inside a C header (.h) file, but with pel-c-skel-with-license set to nil to prevent the inclusion of license text, and with the pel-c-skel-use-include-guards set to with-uuid, the command will also prompt for the file purpose (and you can get the previous entry by typing M-p or the <up> cursor key), then you get the following code instead:

/* C HEADER: monitor.h
**
** Purpose   : Process monitoring facilities.
** Created   : Thursday, August 27 2020.
** Author    : Pierre Rouleau <[email protected]>
** Time-stamp: <2020-08-27 22:49:17, by Pierre Rouleau>
*/
/* ------------------------------------------------------------------------ */
#ifndef MONITOR__H_H0Z79D0F_DB8F_46BJ_FBBC_855167H0439Z
#define MONITOR__H_H0Z79D0F_DB8F_46BJ_FBBC_855167H0439Z /* include guard */
/* ------------------------------------------------------------------------ */
Ⓜ️
/* ------------------------------------------------------------------------ */
#endif

If you want to use C99 compatible line comment style instead, type <f12> M-; to toggle the comment style and then type the same command (<f12> <f12> h) and you'll get something like the following:

// C HEADER: monitor.h
//
// Purpose   : Process monitoring facilities.
// Created   : Thursday, August 27 2020.
// Author    : Pierre Rouleau <[email protected]>
// Time-stamp: <2020-08-27 22:57:51, by Pierre Rouleau>
// ---------------------------------------------------------------------------
#ifndef MONITOR__H_H0Z79D0F_DB8F_46BJ_IFBC_8551670H439Z
#define MONITOR__H_H0Z79D0F_DB8F_46BJ_IFBC_8551670H439Z /* include guard */
// ---------------------------------------------------------------------------
Ⓜ️
// ---------------------------------------------------------------------------
#endif

Again, Ⓜ️ is shown where the tempo markers are placed.

The UUID-based include guards eliminate the probability of include guard clashes when using your code with other's libraries in case the same C header file name is used somewhere. This technique is more portable than the #pragma once technique also used. Also note that even if you use // style comments, the code uses a C-style (block comment) following a C pre-processor include statement, again to increase code compatibility over compilers since the original C-style comment is always supported by C pre-processors.

If you have pel-c-skel-use-include-guards set to nil, the include guard code is not included, and you'll get something like this instead:

/* C HEADER: monitor.h
**
** Purpose   : Process monitoring facilities.
** Created   : Thursday, August 27 2020.
** Author    : Pierre Rouleau <[email protected]>
** Time-stamp: <2020-08-27 22:49:17, by Pierre Rouleau>
*/
/* ------------------------------------------------------------------------ */

or:

// C HEADER: monitor.h
//
// Purpose   : Process monitoring facilities.
// Created   : Thursday, August 27 2020.
// Author    : Pierre Rouleau <[email protected]>
// Time-stamp: <2020-08-27 22:57:51, by Pierre Rouleau>
// ---------------------------------------------------------------------------
8.41.2.2.3.3   Using user-specified module/header skeleton

The default module/header skeleton with all the user options PEL provides might still not generate exactly what you need. In that case, you can write your own skeleton template and get PEL to use it.

To replace PEL's generated code with a template of your own you must do the following:

  • Read and understand the provided example in the file custom/skeleton/custom-c-skel.el. See the explanations below. For this you will need a minimal understanding of the Emacs Lisp programming language. You'll need to learn more than what you need to learn to write yasnippet templates, but you can then take advantage of all Emacs Lisp power and use the PEL functions to prompt for function and purpose, check for function name validity, transform the function name and have the whole action already bound to a key sequence.
  • Write a Emacs Lisp Skeleton file that will define your skeleton template with something similar to what you found in the example:
    • Inside that file, create a Emacs Lisp defun for the function named pel-skels-c-header-module-block/custom.
  • Set the pel-c-skel-module-header-block-style user option to take a user defined skeleton instead of PEL's default: write the path name of the Emacs Lisp file where you wrote your own skeleton code.

Description of the Custom Skeleton Example:

First, the custom example takes advantage of the functionality provide by the PEL functions and the features it can customize further. Which means that your custom skeleton can be written to take advantage of PEL's user option variables to control some of the aspects of the generated code. These user options are the following:

  • pel-c-skel-insert-module-section which specifies whether or not code sections delimiters are inserted inside the generated code. Code sections that describe the purpose the sections of your file. If you want to have those sections you can define their titles inside the pel-c-skel-module-section-titles user option. The default is to include the following sections after the Module Description section:
    • Header Inclusion
    • Local Types
    • Local Variables
    • Code
  • pel-c-skel-comment-with-2stars which identifies whether one or two start characters will be used in the C continuation comment.

Assuming you set the user options to the following values:

  • pel-c-skel-insert-module-section set to nil to prevent generating sections.
  • pel-c-skel-comment-with-2stars set to nil to use the single star C style comment.
  • pel-c-skel-module-header-block-style set to the name of a file that contains the same code as in custom/skeleton/custom-c-skel.el

Assuming also that your name is Same One and you work for U-FooBar, typing the <f12> <f12> h in the file ufoobar.c, something like the following comment would be inserted in the buffer:

/* ufoobar.c : Process monitoring facilities.
 *
 * U-FooBar restricted an and confidential. Copyright © U-FooBar 2020.
 * Created   : Saturday, August 29 2020.
 * Author    : Same One  <[email protected]>
 * Time-stamp: <2020-08-29 17:47:38, updated by Same One>
 */

If you know Emacs Lisp, skip this section.

Notice the first line of the custom/skeleton/custom-c-skel.el file that specifies lexical binding.

Inside the file, the function pel-skels-c-header-module-block/custom is defined to take 3 mandatory arguments, and as described in the function docstring these are:

  • arg 1: fname, a string : the file name (without path)
  • arg 2: is-a-header, a boolean: is non-nil when the file is a C header file, and nil when it is a .c file.
  • arg 3: cmt-style, a list of 3 strings: (cb cc ce), where:
    • cb : comment begin string
    • cc : comment continuation string
    • ce : comment end string.

The code provided does not use the second argument, is-a-header. If you want to distinguish between code files and header files, use this argument. PEL code does.

The first lisp form of the function is a let form that defines local variables. The purpose variable is set with the result of the prompt asking the user the purpose of the C file. If no purpose is specified by the user, the function returns its default, the symbol p. That symbol is used in the tempo skeleton and means that the location of the purpose string will instead be a tempo marker (shown in the output example above with the Ⓜ️ characters) to remind the user to fill the file's purpose string.

The next 3 lines uses the nth function to extract the first second and third element of the cmt-style argument.

The last form of the function is the dynamic construction of a tempo-skeleton compliant insertion list. The first element of that list is the symbol l, and then each element is either a string, a function returning a string, a variable name that evaluates to a string or the symbol n that identifies the end of a line. The symbols are quoted otherwise they would be evaluated. For more information about the syntax of tempo skeleton templates see the docstring of the tempo-define-template function. To open a help buffer with it, type: <f1> o tempo-define-template RET.

The code calls several of PEL's functions. These functions are all documented. To get more info about them uses Emacs help system: move your cursor on the function name and hit <f1> o. Emacs will prompt with the function name you selected. Hit return and Emacs will show a help buffer with the description of the function. The first line of the help buffer will end with the name of the file where the function is defined. Hit tab to move point there and hit return again to open PEL's file where the function is defined.

8.41.2.2.4   C function template

Insert a C function definition block with the <f12> <f12> f key sequence.

The function definition block style is selected by the pel-c-skel-function-define-style user option. By default no style is selected. Customize that variable first. You can use the <f12> <f2> key sequence from a buffer in c-mode to open the PEL customization buffer for C, select the pel-c-code-style customization group and change the value of pel-c-skel-function-define-style. The following function template styles are available:

The default comment style is the C-style /* */ style (also called block style). But you can switch to the C++ // style (also called line style) using the <f12> M-; key sequence.

The pel-c-skel-function-name-on-first-column user option is set to t the function return type is written on the line above the function name. By default this is set to nil and the return type precedes the function name on the same line. The skeleton inserts void as the type but leaves a tempo marker on the first letter. You can quickly delete it with M-d and type the proper type.

The style selected by pel-c-skel-function-define-style identifies the style of the function comment block placed above the function definition code (if any).

The title of the sections included in the function comment block are identified by the pel-c-skel-function-section-titles user option.

Several styles are supported. You can also define your own with Emacs Lisp code stored in a file that you identify in the user option.

The following sections provide examples of the supported styles.

8.41.2.2.4.1   Function name and purpose prompts

All function definition template commands prompt for the function name and the purpose of the function. The prompt maintain an history of the accepted values which you can inspect with the following key sequences:

  • to see previous entry, use M-p or the <up> cursor,
  • to see the next entry, use M-n or the <down> cursor.

The function prompt transforms your entry a little:

  • it strips any leading or trailing whitespace from the entered string, and
  • replace all dash ('-') characters by underscores ('-') to help speed up entry.

It accepts only syntactically valid C function names, rejecting the others by erasing the string from the mini buffer prompt area. You can recall it using the previous entry history key.

The commands also prompt for a quick single sentence describing the purpose of the function. Before inserting that text the command strips whitespace off the front and end of the text, converts the first character to uppercase and ends the text with a period if it is not already present.

You can cancel any prompt with the usual C-g key.

8.41.2.2.4.2   C function definition with no comment block

This is the simplest style. The <f12> <f12> f command prompts for the function name and inserts something like this:

/* -------------------------------------------------------------------------- */
Ⓜ️void
register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

or:

/* -------------------------------------------------------------------------- */
Ⓜ️void register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

or:

// -----------------------------------------------------------------------------
Ⓜ️void
register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

or:

// -----------------------------------------------------------------------------
Ⓜ️void register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

It puts the type void and places a tempo marker (identified by Ⓜ️ ) just before to let you modify it if necessary (use M-d to delete it). It places the function name on the same or next line depending of the value of the pel-c-skel-function-name-on-first-column user option and inserts a C-style comment by default but you can switch to C++ style using the <f12> M-; key sequence.

The presence of horizontal separator lines is controlled by the pel-c-skel-use-separators user option. It is on by default. The length of the line is controlled by the pel-c-fill-column user option of it is set to an integer value, otherwise it is controlled by the Emacs global fill-column user option. You can changed the user option but you can also change the value for the current buffer with the C-x f command.

8.41.2.2.4.3   C function definition with basic comment block

This styles adds a comment block with the function purpose. The <f12> <f12> f command prompts for the function name and the function purpose and inserts something like this:

// -----------------------------------------------------------------------------
// register_process() -- Register a process ID to the monitored list.

Ⓜ️void
register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

As for all function definition blocks the user options in the pel-c-code-style group control whether the separator line is inserted, and whether the return type is placed on the same line as the function name or just above.

8.41.2.2.4.4   C function definition with Man-page style comment block

With C-style comments, pel-c-skel-function-name-on-first-column set to nil (the default), pel-c-skel-function-section-titles identifying the list ("DIAGNOSTIC" "SEE ALSO") (the default) typing <f12> <f12> f inside a buffer in c-mode will insert text following text after prompting for the function name and purpose. For this example, I typed register-process (with a dash) and then register a process ID in the list of monitored processes at the prompt. The command replace the dash in the function name with underscore and also converts the purpose text by capitalizing the first letter and ending it with a period if one is not already present.

/* -------------------------------------------------------------------------- */
/* r e g i s t e r _ p r o c e s s ( )     -- Register a process ID in the list of monitored process.
** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**
** DESCRIPTION
**
** register_process() Ⓜ️
**
**
** DIAGNOSTIC
**
** Ⓜ️
**
** SEE ALSO
**
** Ⓜ️
**
*/

Ⓜ️void register_process(Ⓜ️)
{
    Ⓜ️
}

Ⓜ️

/* -------------------------------------------------------------------------- */

It leaves tempo markers at the locations identified by Ⓜ️ . The indentation is controlled by the pel-c-indent-width user option. Use C-c . to move point to the next tempo marker and C-c , to the previous one.

With C++ style comments and pel-c-skel-function-name-on-first-column set to t, the code inserted is the following instead:

// -----------------------------------------------------------------------------
// r e g i s t e r _ p r o c e s s ( )     -- Register a process ID in the list of monitored process.
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//
// DESCRIPTION
//
// register_process() Ⓜ️
//
//
// DIAGNOSTIC
//
// Ⓜ️
//
// SEE ALSO
//
// Ⓜ️
//

Ⓜ️void
register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️
8.41.2.2.4.5   User selected template for C function definition

The default function definition header skeleton with all the user options PEL provides might still not generate exactly what you need. In that case, you can write your own skeleton template and get PEL to use it.

To replace PEL's generated code with a template for C function definition of your own you must do the following:

  • Read and understand the provided example in the file custom/skeleton/custom-c-skel.el. For this you will need a minimal understanding of the Emacs Lisp programming language. The code for creating a C function definition code is similar to the code that generates the C module/header, so if you're new to Emacs Lisp see the explanation inside the section titled Using user-specified module/header skeleton above.
  • Write a Emacs Lisp Skeleton file that will define your skeleton template with something similar to what you found in the example:
    • Inside that file, create a Emacs Lisp defun for the function named pel-skels-c-function-def/custom.
  • Set the pel-c-skel-function-define-style user option to take a user defined skeleton instead of PEL's default: write the path name of the Emacs Lisp file where you wrote your own skeleton code. The name of that file may be the same as what you might have defined inside the pel-c-skel-module-header-block-style user option.

The example taken from the file custom/skeleton/custom-c-skel.el generates code like the following, controlled by various PEL user options that identify whether the horizontal separator line is inserted, whether the C function return type is on a separate line (as in the example below) or on the same line as the function name, and you can also switch to C++ style comments. The indentation is also controlled by customization.

/* -------------------------------------------------------------------------- */
/* ================
 * register_process
 * ================
 *
 * Register a process ID in the list of monitored process.
 *
*/

Ⓜ️void
register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

Using a C++ style comment (via <f12> M-;) and setting pel-c-skel-function-name-on-first-column set to nil the code generated becomes:

// -----------------------------------------------------------------------------
// ================
// register_process
// ================
//
// Register a process ID in the list of monitored process.
//

Ⓜ️void register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

And then if you set pel-c-skel-use-separators to nil, the command does not insert the separator line, so you get the following instead:

// ================
// register_process
// ================
//
// Register a process ID in the list of monitored process.
//

Ⓜ️void register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

Finally, if you type return at the prompt for the function purpose, the purpose text is not inserted, instead a tempo marker (represented as Ⓜ️ in the generated code) is placed and point is left there:

// ================
// register_process
// ================
//
// Ⓜ️
//

Ⓜ️void register_process(Ⓜ️)
{
   Ⓜ️
}

Ⓜ️

As in the other styles, once you use a PEL command to insert a PEL tempo skeleton template you also automatically activate the pel-tempo-mode, a minor mode where you can use C-c . to move to the next tempo marker and C-c , to move point to the previous tempo marker. When the pel-tempo-mode is active the ‡ lighter shows in the buffer's mode line. You can toggle the pel-tempo-mode minor mode with the <f12> <f12> <space> key sequence.

8.41.3   PEL Support For C++

Language Family:

Curly-Bracket Programming Language
PDF Sheet:

𝕻𝔩- C++
PEL Customization:
  • Group: pel-pkg-for-c++
  • Activation: none
  • Configuration:
    • pel-c++-indent-width
    • pel-c++-tab-width
    • pel-c++-use-tabs
    • pel-c++-bracket-style
    • pel-c++-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-c++ : <f11> SPC C
  • From a buffer in c++-mode: <f12> and <M-f12>

PEL provides support for the C++ Programming Language via Emacs built-in c++-mode. No activation is necessary since the c-mode is built-in Emacs. However, configuration of important editor behaviour such as the indentation/bracket style and the indentation is completely controlled by user options listed above and can easily be changed using Emacs customize system. PEL also provides easy access to commands that can change the CC Mode behaviour on which the c++-mode is based via the pel:for-c++ key-map, bounded to the F12 key for each buffer in c++-mode.

8.41.4   PEL Support for Common Lisp

Language Family:

LISP Programming Language Family
PDF Sheet:

𝕻𝔩 - Common Lisp
PEL Customization:
  • Group: pel-pkg-for-clisp
  • Activation: pel-use-common-lisp.
  • Configuration:
    • pel-lisp-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-lisp : <f11> SPC L
  • From a buffer in lisp-mode: <f12> and <M-f12>

The file pel-commonlisp.el is in a very early stage. It only provides the pel-cl-init function that is used by pel-init to initialize support for Common Lisp when the pel-use-common-lisp customize variable is set to t. The pel-use-common-lisp function sets the indentation rule to the Common Lisp indentation style. The pel-init function also set the variable common-lisp-hyperspec-root to the directory "~/docs/HyperSpec/". You can then copy the HyperSpec files inside this directory and Emacs can access them locally.

8.41.5   PEL Support For D

Language Family:

Curly-Bracket Programming Language
PDF Sheet:

𝕻𝔩 - D
PEL Customization:
  • Group: pel-pkg-for-d
  • Activation: pel-use-d
  • Configuration:
    • pel-d-indent-width
    • pel-d-tab-width
    • pel-d-use-tabs
    • pel-d-bracket-style
    • pel-d-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-d : <f11> SPC D
  • From a buffer in d-mode: <f12> and <M-f12>

PEL provides support for the D Programming Language via the Emacs D-mode and related external packages that it activates when the pel-use-d user option is set to t. The selection of important editor behaviour such as the indentation/bracket style and the indentation is completely controlled by user options. The defaults are adapted to what is proposed by the D Style code guideline and can easily be changed using Emacs customize system. More information is available in the PEL PDF document for D . PEL also provides easy access to commands that can change the CC Mode behaviour on which the d-mode is based via the pel:for-d key-map, bounded to the F12 key for each buffer in d-mode.

8.41.6   PEL Support for Elixir

Language Family:

BEAM VM Programming Language
PDF Sheet:

𝕻𝔩 - Elixir
PEL Customization:
  • Group: pel-pkg-for-elixir
  • Activation:
    • pel-use-elixir
    • pel-use-alchemist
    • pel-use-elixir-exunit
    • pel-use-elixir-lsp
  • Configuration:
    • pel-elixir-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-elixir : <f11> SPC x
  • From a buffer in elixir-mode: <f12> and <M-f12>

PEL provides basic support for the Elixir programming language via the elixir-mode package. With it the file extensions .exs, .ex, and .elixir are automatically recognized as being Elixir files.

8.41.7   PEL Support for Emacs Lisp

Language Family:

LISP Programming Language Family
PDF Sheet:

⨋𝕻𝔩 - Emacs Lisp , ERT .
PEL Customization:
  • Group: pel-pkg-for-elisp
  • Activation: (none to use Emacs Lisp), but there are for other packages:
    • pel-use-macrostep
    • pel-use-esup
    • pel-use-re-builder
    • pel-use-highlight-defined
  • Configuration:
    • pel-elisp-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-elisp : <f11> SPC l
  • From a buffer in elisp-mode: <f12> and <M-f12>

The file pel-lisp.el contains command utilities that help edit Emacs Lisp code. Some of them can also be used for other types of Lisp as well.

  • pel-toggle-lisp-modes toggles between lisp-interaction-mode and emacs-lisp-mode.
  • pel-byte-compile-file-and-load byte compiles the file in the current buffer and then load it.
  • pel-lint-elisp-file runs Emacs Lisp lint on the current file.

8.41.8   PEL Support for Erlang

Language Family:

BEAM VM Programming Language
PDF Sheet:

𝕻𝔩 - Erlang
PEL Customization:
  • Group: pel-pkg-for-erlang. Use <f12> <f1> from and erlang mode buffer.
  • Activation:
    • pel-use-erlang
    • pel-use-edts
    • pel-use-erlang-ls
    • pel-use-helm-lsp
    • pel-use-lsp-ivy
    • pel-use-treemacs
    • pel-use-lsp-treemacs
    • pel-use-lsp-origami
    • pel-use-erlang-syntax-check
    • pel-use-hide-comnt
    • pel-use-iedit
    • pel-use-smart-dash
    • pel-use-smartparens
  • Configuration:
    • pel-erlang-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-erlang : <f11> SPC e
  • From a buffer in erlang-mode: <f12> and <M-f12>

PEL provides extensive support for the Erlang Programming Language using and integrating the following:

For Erlang, PEL provides several enhancements to the default behaviour provided by the erlang.el code, including the following:

  1. enhanced Erlang-specialized electric key behaviour,
  2. block sensitive deletion for Erlang,
  3. enhanced Erlang comment insertion,
  4. Erlang comments hiding control,
  5. outlining support for Erlang,
  6. Erlang-specific display rendering of hard tabs,
  7. Erlang-specific insertion of hard tabs for indentation,
  8. Erlang-specific Indentation control,
  9. enhanced navigation in Erlang code,
  10. Erlang-specific code transformation commands,
  11. enhanced Erlang symbol identification with superword-mode,
  12. enhanced tempo-based skeleton code templates.

PEL provides access to the Tempo skeleton and yasnippet template text insertion systems. PEL adds functionality to several of the Erlang skeletons, provides the ability to select several commenting styles via user option variables that can be customized (use the <f12> <f2> key from a buffer in erlang major mode to quickly gain access to the buffer to see and/or change those variables). Refer to the PEL Erlang PDF document for more information.

8.41.8.1   Enhanced Erlang-specialized Electric Key Behaviour

PEL integrates and enhances the electric key behaviour provided by erlang.el, smartparens and start-dash, adds electric behaviour to some keys and provides the ability to configure the electric behaviour of the various electric keys by customization but also dynamically during an editing session. The electric keys are:

RET:
Electric newline: inserts a new line and indents. Activated by default.
<
When smartparens-mode is active a << automatically inserts the closing >> and leaves the point in between.
>
When following a dash in -> automatically inserts a new line and indents. You can dynamically disable the electric behaviour for the instance of this character by typing M-1 > after the dash. Use this for writing code where the returned value is short.
.
If a period is typed following a dash, as in -. then -> is inserted in code (but not in comment or a string). This is another way from typing -> without automatically inserting an indented new line. This behaviour is disabled when the dash follows a $ so you can type $-. and it will not be converted.
,
  • A comma typed at the end of an Erlang expression automatically inserts a new indented line.
  • A comma inserted after an opening parens character (any of (, [, { or <) or inside a balanced pair of these characters can trigger the automatic insertion of a space when the pel-erlang-space-after-comma-in-block uer-option is turned one. If the behaviour is enabled by user-option it is possible to disable it for the next inserted comma by typing M-1 ,.
;
  • Insert a semicolon character and possibly a function clause head prototype on the next line.
    • Inserts a function clause head prototype when the selection criteria identified by erlang-electric-comma-criteria indicates that it should be done.
  • Behaves like the normal semicolon when supplied with a numerical arg, point is inside string or comment, or when there are non-whitespace characters following the point on the current line.
-
When the smart-dash mode is active, typing a dash inserts an underscore following any letter, digit or underscore. Inserts a dash otherwise.

With PEL, you can temporary toggle the electric behaviour of one of the above characters for the current Emacs editing session, either for the current Erlang buffer or for all Erlang buffers.

  • To toggle the electric behaviour of one of these characters in the current buffer only, type <M-f12> M-` followed by the character.
  • To toggle the electric behaviour for all Erlang buffers, type an argument prefix before that key sequence. For example, to disable the electric behaviour of the semicolon in all Erlang buffers, type M-- <M-f12> M-`.
  • You can also toggle the automatic insertion of spaces after comma inside blocks by typing <M-f12> M-` M-, or in all Erlang buffers with M-- <M-f12> M-` M-,.

All Electric key behaviour is controlled by customization: the pel-erlang-electric-keys and pel-erlang-space-after-comma-in-block user-options must be enabled to activate the electric behaviour. By default, everything is enabled except the automatic space after comma in block.

8.41.8.1.1   User-Options for Erlang Electric Key Behaviour
Group:pel-pkg-for-parens
Key:<f11> i <f2>, select Pel Pkg For Parens.

Activate pel-use-smartparens to add the << >> pair management as well as other behaviours described in the navigation and code transformation sections below.

Group:

erlang
Key:
  • Globally: <f11> SPC e <f3>
  • From erlang-mode buffer: <f12> <f3>
erlang-electric-semicolon-insert-blank-lines:
This variable controls the behaviour of ‘erlang-electric-semicolon’ when a new function header is generated. When nil, no blank line is inserted between the current line and the new header. When bound to a number it represents the number of blank lines which should be inserted.
erlang-new-clause-with-argument:

Non-nil means that the arguments are cloned when a clause is generated.

  • A new function header can be generated by calls to the function ‘erlang-generate-new-clause’ and by use of the electric semicolon.
erlang-next-lines-empty-threshold:

Number of blank lines required to activate an electric command.

  • Actually, this value controls the behaviour of the function ‘erlang-next-lines-empty-p’ which normally is a member of the criteria lists controlling the electric commands. (Please see the variables ‘erlang-electric-semicolon-criteria’ and ‘erlang-electric-comma-criteria’.)
  • The variable is bound to a threshold value, a number, representing the number of lines which must be empty.
  • Setting this variable to zero, electric commands will always be triggered by ‘erlang-next-lines-empty-p’, unless inhibited by other rules.
  • Should this variable be nil, ‘erlang-next-lines-empty-p’ will never trigger an electric command. The same effect would be reached if the function ‘erlang-next-lines-empty-p’ would be removed from the criteria lists.
  • Note that even if ‘erlang-next-lines-empty-p’ should not trigger an electric command, other functions in the criteria list could.
Group:

pel-erlang-code-style
Key:
  • Globally: <f11> SPC e <f2>, select Pel Erlang Code Style.
  • From erlang-mode buffer: <f12> <f2>, select Pel Erlang Code Style.
pel-erlang-electric-keys:

List of keys that should have electric behaviour for Erlang buffers.

  • By default PEL activates the electric behaviour of the 4 characters controlled by the erlang.el package: comma, gt, newline and semicolon. PEL also provides electric behaviour to the period, allowing typing ’->’ in code by typing '-.' instead.
  • To disable the electric behaviour of a character un-check the corresponding box.
  • PEL also supports dynamically toggling the electric behaviour of a key with the <M-f12> M-` prefix followed by the specific key.
  • Additionally PEL activates another electric behaviour to the comma, by automatically inserting a space after a colon typed inside blocks. This is controlled by ‘pel-erlang-space-after-comma-in-blocks’.
pel-erlang-space-after-comma-in-blocks:

When set the erlang-electric-comma inserts a space after comma in blocks.

  • For this to work, the pel-erlang-electric-keys must activate the electric comma.
  • You can also dynamically toggle the electric behaviour of the comma key by using the pel-erlang-comma command, mapped to <M-f12> M-` , in Erlang buffers.
  • If you want to keep the electric behaviour of the comma key, but temporary want to disable adding spaces after a comma inside the current Erlang buffer, use the <M-f12> M-` M-, to toggle this behaviour off and on.
8.41.8.2   Block Sensitive Deletion for Erlang
Group:pel-pkg-for-parens
Key:<f11> i <f2>, select Pel Pkg For Parens.

When smartparens-mode is active (as selected by the pel-use-smartparens user-option), the forward and backward delete keys do not delete a block delimiter character that is part of balanced block expression until the content of block is empty. Once the block is empty the delete key deletes the entire empty block.

8.41.8.3   Enhanced Erlang Comment Insertion

PEL improves the ability to control the number of '%' characters placed at the beginning of a comment based on the position into the buffer, the previous line and also provides the ability to force a fixed number of '%' characters.

The usual command comments a line or a region with % or %% depending on the location inside the buffer. PEL provides its own command, pel-erlang-comment-dwim, bound to the usual M-; key, that does the same and provides the supplemental behaviour:

  • Insert %%% comments on the very first line of a buffer and lines that follow a line that starts with %%% comments.
  • Accepts prefix argument to explicitly identify the number of '%' characters to use. For example, use M-3 M-; to use %%% comment style regardless of the position inside the buffer.
8.41.8.4   Erlang Comments Hiding Control
Group:pel-pkg-for-hide-show
Key:<f11> M-/ <f2>

When the pel-use-hide-comnt user-option is turned on PEL activates the hide-comnt library and provides the <f11 ; ; key binding to toggle the display of all comments in the active region or the complete buffer.

8.41.8.5   Outlining Support for Erlang

The erlang.el library supports simple outlining is supported by the outline-minor-mode provided by Emacs built-in outline library. No IDE-like package is required to use it; it's always available for the erlang-mode.

To us it in Erlang buffers you must first activate the outline-minor-mode. PEL provides the <f11> M-l key binding for that. Then you can use any of the outline commands to hide or expand the body of the Erlang functions and navigate through them easily. The default key binding for the key is under the C-c @ key prefix. PEL adds the <f2> key prefix for the same commands.

You can also modify the default key binding and select something else than C-c @ by modifying the outline-mode-minor-prefix user option. PEL provides the <f11> SPC M-l <f3> key binding to access the outline customization buffer.

More information on outline is available in the ⅀ Outline PDF.

8.41.8.6   Erlang-specific Display Rendering of hard tabs

The visual horizontal rendering of hard tab present in the Erlang source code is controlled by the value of the tab-width variable as seen by Emacs for an Erlang buffer. Emacs provides the tab-width global user-option for this and PEL provides the Erlang-specific pel-erlang-tab-width user-option and sets tab-width to the value of pel-erlang-tab-with in each erlang-mode buffer to control the display rendering of hard tab characters in Erlang source code.

Group:editing-basics
Key:<f11> <f2> g editing-basics RET
tab-width:

Distance between tab stops (for display of tab characters), in columns.

  • This controls the display width of a TAB character, and not the size of an indentation step. This should be an integer greater than zero.
  • PEL overrides this value with the value of pel-erlang-tab-width for all buffers using the erlang-mode.
Group:

pel-pkg-for-erlang, pel-erlang-code-style
Key:
  • Globally: <f11> SPC e <f2>
  • From erlang-mode buffer: <f12> <f2>
pel-erlang-tab-width:

Distance between tab stop for Erlang source code.

  • PEL stores this in tab-width when editing buffer with Erlang source.
  • This does NOT control the indentation in Erlang source code. It is used, however, to control the display rendering of hard tab characters inserted inside source code and by commands that move point to tab stop positions such as tab-to-tab-stop, and the display of hard TAB characters.
  • The indentation of Erlang code is mostly controlled by erlang-indent-level. If pel-erlang-tab-width differs erlang-indent-level then pel-erlang-tab-width should be a multiple of erlang-indent-level in case hard tabs have been inserted inside the source code.
  • Values in the [2, 8] range are accepted.
8.41.8.7   Erlang-specific Insertion of hard tabs for indentation

The insertion of hard tab characters (ASCII Horizontal Tab, 0x09) when horizontal indentation space is inserted inside the Erlang source code file is controlled by the value of indent-tab-mode variable in the current buffer. The default value is normally controlled by the customizable value it has globally. However, PEL provides the pel-erlang-use-tabs user-option and sets the value of indent-tab-mode with the value of pel-erlang-use-tabs in all erlang-mode buffers to explicitly control this behaviour in Erlang source code.

Group:indent
Key:<f11> TAB <f3> 1
indent-tabs-mode:
Indentation can insert tabs if this is non-nil.
Group:

pel-pkg-for-erlang, pel-erlang-code-style
Key:
  • Globally: <f11> SPC e <f2>
  • From erlang-mode buffer: <f12> <f2>
pel-erlang-use-tabs:

Value of ‘indent-tabs-mode’ for editing Erlang source code.

  • If set to nil: only spaces are used for indentation.
  • If set to t: hard tabs are used when possible.
8.41.8.8   Erlang-Specific Indentation Control

Indentation of Erlang source code is controlled by several user-options, listed below.

PEL provides an additional control for the Emacs fill-column which identifies the column where automatic wrapping is done: the pel-erlang-fill-column value is used for fill-column in erlang-mode buffers.

NOTE for new Emacs users:

New Emacs users may find the behaviour of the TAB key puzzling. Pressing the TAB key does not insert spaces to the location of the indentation level the way several editors handle it.

Instead, pressing TAB will adjust the horizontal indentation of the current line if the line indentation must be adjusted and will do nothing otherwise. However, you can press the TAB key anywhere on the line to adjust its indentation! You can also select a larger text section and hit TAB to adjust the indentation of all the lines!

It takes some time to get used to this behaviour but soon you will find it invaluable. Emacs automatically adjusts the indentation of the code using its knowledge of the Erlang syntax and the various user-options described below.

Group:

erlang
Key:
  • Globally: <f11> SPC e <f3>
  • From erlang-mode buffer: <f12> <f3>
erlang-argument-indent:

Indentation of the first argument in a function call.

  • When nil, indent to the column after the ‘(’ of the function.
  • Default: 2
erlang-icr-indent:

Indentation of Erlang if/case/receive patterns.

  • nil means keeping default behaviour.
  • When non-nil, indent to the column of if/case/receive.
  • Default: nil
erlang-indent-guard:

Indentation of Erlang guards.

  • Default: 2
erlang-indent-level:

Indentation of Erlang calls/clauses within blocks.

  • Default: 4
erlang-tab-always-indent:

Non-nil means the TAB key in Erlang mode should always re-indent the current line, regardless of where in the line point is when the TAB key is pressed. This is stored into the global tab-always-indent.

  • Default: t
Group:

pel-pkg-for-erlang, pel-erlang-code-style
Key:
  • Globally: <f11> SPC e <f2>
  • From erlang-mode buffer: <f12> <f2>
pel-erlang-fill-column:

Column beyond which automatic line-wrapping should happen in Erlang code.

  • Can either be nil or an integer value.
  • When set to nil, Emacs user option variable ‘fill-column’ value is used for ‘erlang-mode’ buffers, otherwise the integer value specified by this value is stored in ‘fill-column’ for Erlang source code files.
  • The default is 100, a value recommended by the Inaka’s Erlang Coding Standards & Guidelines.
Group:indent
Key:<f11> TAB <f3> 1
indent-tab-mode:
Indentation can insert tabs if this is non-nil.
tab-stop-list:

List of tab stop positions used by ‘tab-to-tab-stop’.

  • This should be nil, or a list of integers, ordered from smallest to largest.
  • It implicitly extends to infinity through repetition of the last step. For example, (1 2 5) is equivalent to (1 2 5 8 11 ...). If the list has fewer than 2 elements, ‘tab-width’ is used as the "last step". A value of nil means a tab stop every ‘tab-width’ columns.
  • For Erlang this is nil by default.

Additionally, the following non-customizable variable is used and set by erlang.el:

indent-line-function:

Function to indent the current line.

  • This function will be called with no arguments.
  • If it is called somewhere where auto-indentation cannot be done (e.g. inside a string), the function should simply return ‘noindent’.
  • Setting this function is all you need to make TAB indent appropriately. Don’t rebind TAB unless you really need to.
  • Default for Erlang buffers: erlang-indent-command
8.41.8.9   Enhanced Navigation in Erlang Code
Group:pel-pkg-for-parens
Key:<f11> i <f2>, select Pel Pkg For Parens.

PEL provides specialized navigation commands extending what erlang.el and smartparens provide when the pel-use-smartparens user-option is turned on. The extra commands include:

  • move backward and forward to blocks jumping over strings and comments,
  • move down and up a block tree (in and out of nested lists).

See the 𝕻𝔩 - Erlang PDF for more information and examples.

8.41.8.10   Erlang-specific Code Transformation Commands
Group:pel-pkg-for-parens
Key:<f11> i <f2>, select Pel Pkg For Parens.

PEL provides enhanced specialized code transformation commands for Erlang that smartparens provide. PEL enhances the smartparens code; smartparens by itself does not deal properly with comma separated blocks of values such as Erlang lists or function argument lists.

The additional commands operate on balanced pair blocks of ( ), [ ], { } and << >> for some of them. The commands include:

  • transpose
  • slurp and barf
  • wrap, re-wrap and unwrap blocks,
  • split and join blocks.

See the 𝕻𝔩 - Erlang PDF for more information and examples.

Group:pel-pkg-for-highlight
Key:<f11> h <f2> 1

PEL also provides access to the iedit-mode; a very-useful minor mode you can use to search and modify various names inside a buffer. Activate iedit by setting the pel-use-iedit user-option on.

8.41.8.11   Enhanced Erlang Symbol Identification With superword-mode
Group:pel-pkg-for-text-modes
Key:<f11> t <f2>

As Erlang uses snake-case, PEL automatically activates the superword-mode for Erlang by including the erlang-mode in the pel-modes-activating-superword-mode user variable default. PEL also provides key-bindings to the command that dynamically toggles the mode. Inside any erlang-mode buffer you can type <f12> M-p or the <M-f12> M-p key sequences to toggle the mode on and off.

Using the superword-mode helps searching for Erlang terms. It also helps selecting them when using the extremely useful er/expand-region command which is bound to the M-= key (and also the <f11> . = key sequence).

8.41.8.12   Enhanced Tempo-based Skeleton Code Templates

PEL enhances the Emacs Tempo-based skeletons code templates and provides a large set of specialized and customizable code templates for different types of Erlang source code files.

PEL provides a large set of customizable user-options, available inside two different customization groups:

Group:
  • pel-erlang-code-style
  • pel-erlang-skeleton-control
Keys:
  • globally: <f11> SPC e <f2>, select Pel Erlang Code Style
  • from erlang-mode buffer: <f12> <f2>, select Pel Erlang Code Style

If you have not already set your full name and email address in Emacs customization you will also want to set the following user-options as they are used in all PEL Tempo Skeleton templates for files. Use <f11> <f2> o and type the user-option name at the prompt to quickly access those user-options.

Variable Value Description
user-full-name ➽ Set your full name.
user-mail-address ➽ Set you email address in this variable. Emacs tries to infer it but it may only contain your user name and your computer name.

The commands to insert the Erlang code template are available via the Erlang section of Emacs menu (accessible via <f10> under PEL). It looks like this:

res/erlang-templates-menu.png

PEL also provide key bindings for all of the templates. They are all bound under the <f12> <f12> key prefix and listed inside the 𝕻𝔩 - Erlang PDF.

Examples of some of the possible templates for Erlang are available in the example/templates/erlang repo directory. For a complete description on how to work with PEL tempo skeleton templates see the description of the templates for the C language in the section titled C Code Templates. The same control mechanism are available for Erlang with Erlang specific code generated for various type of Erlang files.

8.41.9   PEL Support for Forth

Language Family:

Stack-Based, Concatenative Programming Language
PDF Sheet:

𝕻𝔩- Forth
PEL Customization:
  • Group: pel-pkg-for-forth
  • Activation: pel-use-forth
  • Configuration:
    • pel-forth-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-forth : <f11> SPC f
  • From a buffer in forth-mode: <f12> and <M-f12>

PEL provides basic support for the Forth programming language via the forth-mode package. With it the file extensions .f, .fs, .fth, and .4th are automatically recognized as being Forth files.

8.41.10   PEL Support for Gleam

Language Family:

BEAM VM Programming Language
PDF Sheet:

𝕻𝔩 - Gleam
PEL Customization:
  • Group: pel-pkg-for-gleam
  • Activation: pel-use-gleam
  • Configuration:
    • pel-gleam-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-gleam : <f11> SPC M-G
  • From a buffer in gleam-mode: <f12> and <M-f12>

PEL support for Gleam is experimental. See the Gleam PDF Sheet for more information.

8.41.11   PEL Support for Go

Language Family:

Curly-Bracket Programming Language
PDF Sheet:

𝕻𝔩 - Go
PEL Customization:
  • Group: pel-pkg-for-go
  • Activation: pel-use-go
  • Configuration:
    • pel-go-tab-width
    • pel-go-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-go : <f11> SPC g
  • From a buffer in go-mode: <f12> and <M-f12>

PEL support for Go is experimental using the go-mode, go-flymake and go-flycheck. See the Go PDF Sheet for more information.

8.41.12   PEL Support for Janet

Language Family:

LISP-like Programming Language
PDF Sheet:

𝕻𝔩 - Janet
PEL Customization:
  • Group: pel-pkg-for-janet
  • Activation:
    • pel-use-janet-mode
    • pel-use-ijanet-mode
    • pel-use-inf-janet
  • Configuration:
    • pel-janet-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-janet : <f11> SPC T
  • From a buffer in janet-mode: <f12> and <M-f12>

PEL support for Janet is experimental. See the Janet PDF Sheet for more information.

8.41.13   PEL Support for Julia

PDF Sheet:

𝕻𝔩 - Julia
PEL Customization:
  • Group: pel-pkg-for-julia
  • Activation: pel-use-julia
  • Configuration:
    • pel-julia-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-julia : <f11> SPC j
  • From a buffer in julia-mode: <f12> and <M-f12>

PEL provides basic support for the Julia programming language via the julia-mode package. With it the file extensions .jl are automatically recognized as being Julia files.

8.41.14   PEL Support for LFE

Language Family:
PDF Sheet:

𝕻𝔩 - LFE
PEL Customization:
  • Group: pel-pkg-for-lfe
  • Activation: pel-use-lfe
  • Configuration:
    • pel-lfe-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-lfe : <f11> SPC C-l
  • From a buffer in lfe-mode: <f12> and <M-f12>

PEL support for LFE, Lisp Flavored Erlang, inherits from Emacs Lisp support and some extra feature supported by PEL. See the LFE PDF Sheet for more information.

8.41.15   PEL Support for NetRexx

PDF Sheet:

𝕻𝔩 - NetRexx
PEL Customization:
  • Group: pel-pkg-for-netrexx
  • Activation: pel-use-netrexx
  • Configuration:
    • pel-netrexx-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-netrexx : <f11> SPC N
  • From a buffer in netrexx-mode: <f12> and <M-f12>

PEL support for NetRexx is experimental. See the NetRexx PDF Sheet for more information.

8.41.16   PEL Support for Nim

PDF Sheet:

𝕻𝔩 - Nim
PEL Customization:
  • Group: pel-pkg-for-nim
  • Activation: pel-use-nim
  • Configuration:
    • pel-nim-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-nim : <f11> SPC n
  • From a buffer in nim-mode: <f12> and <M-f12>

PEL support for Nim is experimental. See the Nim PDF Sheet for more information.

8.41.17   PEL Support for OCaml

Language Family:

ML
PDF Sheet:

𝕻𝔩 - OCaml
PEL Customization:
  • Group: pel-pkg-for-ocaml
  • Activation:
    • pel-use-ocaml
    • pel-use-caml-mode
    • pel-use-tuareg
    • pel-use-merlin
PEL Key Prefix:
  • Globally: pel:for-ocaml : <f11> SPC o
  • From a buffer in caml-mode: <f12> and <M-f12>

PEL support for OCaml is experimental. See the OCaml PDF Sheet for more information.

8.41.18   PEL Support for Perl

PDF Sheet:

𝕻𝔩 - Perl
PEL Customization:
  • Group: pel-pkg-for-perl
  • Activation: pel-use-perl
  • Configuration:
    • pel-perl-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-perl : <f11> SPC P
  • From a buffer in perl-mode: <f12> and <M-f12>

PEL support for Perl is experimental. See the Perl PDF Sheet for more information.

8.41.19   PEL Support for Python

PDF Sheet:

𝕻𝔩 - Python
PEL Customization:
  • Group: pel-pkg-for-python
  • Activation: pel-use-python
  • Configuration:
    • pel-python-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-python : <f11> SPC p
  • From a buffer in python-mode: <f12> and <M-f12>

PEL provides basic support for the Python programming language via the python-mode package. With it the file extensions .py, .pyi and .pyw are automatically recognized as being Python files.

8.41.20   PEL Support for REXX

PDF Sheet:

𝕻𝔩 - REXX
PEL Customization:
  • Group: pel-pkg-for-rexx
  • Activation: pel-use-rexx
  • Configuration:
    • pel-rexx-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-rexx : <f11> SPC R
  • From a buffer in rexx-mode: <f12> and <M-f12>

PEL provides basic support for the REXX programming language via the forth-mode package. With it the file extensions .rexx, .elx, .ncomm, and .cpr are automatically recognized as being REXX files.

8.41.21   PEL Support for Ruby

PDF Sheet:

𝕻𝔩 - Ruby
PEL Customization:
  • Group: pel-pkg-for-ruby
  • Activation: pel-use-ruby
  • Configuration:
    • pel-ruby-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-ruby : <f11> SPC U
  • From a buffer in ruby-mode: <f12> and <M-f12>

PEL support for Ruby is experimental. See the Ruby PDF Sheet for more information.

8.41.22   PEL Support for Rust

PDF Sheet:

𝕻𝔩 - Rust
PEL Customization:
  • Group: pel-pkg-for-rust
  • Activation:
    • pel-use-rust
    • pel-use-rust-mode
    • pel-use-rustic
    • pel-use-flycheck-rust
    • pel-use-emacs-racer
    • pel-use-cargo
  • Configuration:
    • pel-rust-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-rust : <f11> SPC r
  • From a buffer in rust-mode: <f12> and <M-f12>

PEL support for Rust is experimental using the rust-mode, rustic, flycheck-rust, emacs-racer and cargo.

See the Rust PDF Sheet for more information.

8.41.23   PEL Support for Unix Shell

PDF Sheet:

𝕻𝔩 - Unix Shell
PEL Customization:
  • Group: pel-pkg-for-sh
  • Activation: pel-use-sh
  • Configuration:
    • pel-make-script-executable
    • pel-shell-sourced-script-file-name-prefix
    • pel-shell-script-extensions
    • pel-sh-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-sh : <f11> SPC g
  • From a buffer in sh-mode: <f12> and <M-f12>

PEL support several Unix Shell using Emacs built-in support for them and extending it with some extra code.

See the Unix Shell PDF Sheet for more information.

8.41.24   PEL Support for V

PDF Sheet:

𝕻𝔩 - V
PEL Customization:
  • Group: pel-pkg-for-v
  • Activation: pel-use-v
  • Configuration:
    • pel-v-activates-minor-modes
PEL Key Prefix:
  • Globally: pel:for-v : <f11> SPC v
  • From a buffer in v-mode: <f12> and <M-f12>

PEL support for the emerging V language is experimental using the v-mode.

See the V PDF Sheet for more information.

8.42   PEL Prompt Utilities

PDF Sheet:none
PEL Customization:none
PEL Key Prefix:none

The file pel-prompt.el is a utility file and for now only contains one function: pel-y-n-e-or-l-p which prompts and accepts various types of responses. It is used by the pel-find-file-at-point-in-window command. It's a rather specialized prompting utility with a rather strange name...

8.43   PEL Project Management Utilities

PDF Sheet:Projectile Project Interaction Manager.
PEL Customization:pel-use-projectile
PEL Key Prefix:projectile-command-map : <f8>

PEL supports the projectile external package when the pel-use-projectile user option is set to either t or use-from-start. If you set it to t it makes it available but does not activate it when Emacs starts. If you set it to use-from-start it activates it when Emacs starts.

PEL uses the <f8> key as the projectile prefix and adds some key bindings into it. You can toggle the activation of this prefix key via the <f11> <f8> key sequence.

The use of projectile activates more grep facilities, as described in the PEL Grep Support section.

More information is available inside the Projectile Project Interaction Manager PDF documentation.

8.44   PEL Rectangle Support

PDF Sheet:Rectangles.
PEL Customization:none
PEL Key Prefix:none

PEL adds a couple of key bindings to support the rectangle area editing. More information about Emacs rectangle area editing is available in the Rectangles PDF document.

8.45   PEL Register Management Utilities

PDF Sheet:Registers.
PEL Customization:none
PEL Key Prefix:pel::register : <f11> r

The file pel-register.el provides the following commands to help manage registers:

  • pel-filename-to-register,
  • pel-point-to-register,
  • pel-copy-to-register,
  • pel-copy-rectangle-to-register,
  • pel-window-configuration-to-register,
  • pel-frameset-to-register,
  • pel-number-to-register,
  • pel-kmacro-to-register.

The Registers PDF document provides more information.

8.46   PEL Scrolling

PDF Sheet:Scrolling.
PEL Customization:pel-smooth-scrolling.
PEL Key Prefix:pel:scroll : <f11> |

The pel-scroll file provides a set of window scrolling facilities.

The following 2 commands are used to scroll the current window, and other windows that may be placed inside the PEL window scroll group:

  • pel-scroll-up which scrolls text up,
  • pel-scroll-down which scrolls text down.

The file also provides the creation and management of a group of windows into the PEL window scroll sync group, a list stored inside the pel-in-scroll-sync variable identifying windows that will be scrolled together.

The following commands are used to activate and manage the PEL window scroll sync group:

  • pel-toggle-scroll-sync toggles scroll lock on/off. When turning it on it locks scrolling of the current and the next window.
  • pel-add-window-to-scroll-sync adds the current window to the already existing group of scroll locked windows. If there is none it locks scrolling of the current and the next window.
  • pel-remove-window-from-scroll-sync removes the current window from the group of scroll locked windows. Removing the last one disables the window scroll sync. If only one window is left in the group the command informs the user but allows it. That way another window can be added to the group.

The scrolling of multiple windows is currently only performed when the following commands are used:

  • pel-scroll-up which scrolls text up,
  • pel-scroll-down which scrolls text down,
  • pel-home and pel-end, defined in pel-navigation, which move point the the beginning or end of current field, line, window or buffer. See PEL Navigation Support.

When the smooth scrolling package is available and pel-smooth-scrolling user option is set to t, PEL provide a key binding to toggle smooth scrolling on and off. See the Scrolling PDF table for more info.

8.47   PEL Search and Replace Support Utilities

PDF Sheet:

Search and Replace.
PEL Customization:
  • pel-initial-regexp-engine
  • pel-initial-search-tool
  • pel-use-anzu
  • pel-use-pcre2el
  • pel-use-regex-tool
  • pel-use-swiper
  • pel-use-visual-regexp-steroids
  • pel-use-visual-regexp
  • pel-use-xr
PEL Key Prefix:

pel:search-replace : <f11> s

The pel-search.el file provides 2 commands to change the value of two Emacs variables that control the search behaviour: case-fold-search and search-upper-case, and 1 command to display and interpret their current value:

  • pel-toggle-case-fold-search toggles search case sensitivity in the current buffer.
  • pel-toggle-search-upper-case changes the sensitivity behaviour of yank in search prompt between the following:
    • nil : upper case don't force case sensitivity,
    • t : upper case force case sensitivity,
    • not-yanks : upper case force case sensitivity, and lower case text when yank in search mini-buffer.
  • pel-show-search-case-state displays the search behaviour in the current buffer.

PEL also integrates several search enhancement packages when their corresponding user option variable are set to t. See the above Customization list. With those you can set the regular expression engine and the search tool you want to use by default and you can change them dynamically during editing.

See the PDF Search and Replace document for more information.

8.48   PEL Session Support

PDF Sheet:Sessions.
PEL Customization:pel-use-desktop.
PEL Key Prefix:pel:session : <f11> S

PEL can activate several packages that manage sessions (also called desktops): a set of buffer and windows setting that can be stiored and restored later. All activation is done by the pel-use-desktop user option variable. See the Sessions PDF document for more information and the key bindings: they all use the pel:session key prefix, which PEL binds to <f11> S.

8.49   PEL Shell Support

PDF Sheet:Shells.
PEL Customization:pel-use-erlang.
PEL Key Prefix:pel:execute : <f11> z

PEL provides the pel:execute (<f11> z) key binding to provide access to various types of shells, terminals and REPL buffers from within Emacs as described in the Shells PDF table.

PEL also provides access to several the REPL of several programming languages, via the pel:repl key prefix, mapped to <f11> z r. The programming language REPLs are also accessible via the <f12> z key of their respective major mode.

8.50   PEL Sorting Support

PDF Sheet:Sorting.
PEL Customization:none
PEL Key Prefix:pel:order : <f11> o

PEL provides the pel:order (<f11> o) key binding to provide access to Emacs commands you can use to sort (order) text in various ways as described in the Sorting PDF table.

8.51   PEL Speedbar Management

PDF Sheet:

Speedbar.
PEL Customization:
  • Group: pel-pkg-for-speedbar
  • Activation: pel-use-speedbar
  • Configuration: pel-prefer-sr-speedbar-in-terminal
PEL Key Prefix:

pel:speedbar : <f11> M-s

The file pel-speedbar.el manages the accessibility and use of Emacs speed-bars: both Emacs native Speedbar and the SR-Speedbar external package. When the pel-use-speedbar user option is set to t PEL provides key bindings for activating the speed-bars and provide some management facilities. As shown in the PDF Speedbar table, Plus default key bindings for those use the <f11> M-s prefix.

PEL manages what type of speed-bar is used. And that depends on whether Emacs is running in graphics mode or in terminal (TTY) mode and whether SR-Speedbar is available. Note that once one type of speed-bar has been opened inside an Emacs session it is currently not possible to use the other type.

In graphics mode, both are equally functional, but in terminal mode SR-speedbar is clearly superior because Speedbar will take over the entire frame while SR-Speedbar uses only one of the windows.

  • To open a speed-bar, use the open-close-speedbar command.
    • If SR-speedbar is not available, Speedbar is used.
    • If SR-speedbar is available, when Emacs runs in graphics mode, then pel-open-close-speedbar prompts the first time it's called to select which one to use. When Emacs runs in terminal mode, pel-open-close-speedbar prompts only if the customization variable pel-prefer-sr-speedbar-in-terminal is nil, otherwise it automatically selects SR-Speedbar, which is more convenient.
  • To close the currently opened speed-bar, use open-close-speedbar again.
  • When using a the SR-Speedbar you can use the pel-toggle-to-speedbar command to quickly move point between your current window and the SR-Speedbar window.
  • Force a refresh of the speed-bar contents with the pel-speedbar-refresh command.
  • By default the speed-bar does not show the Emacs level-1 and level-2 hidden files. To toggle the display of the level-1 hidden files, use the pel-speedbar-toggle-show-all-files command. It will warn if no speed-bar is opened.
  • The speed-bar can display the source code file tags. To toggle sorting of the tags use the pel-speedbar-toggle-sorting command. It will warn if no speed-bar is opened.
  • When Emacs is running in graphics mode, it can use icons for the speed-bar nodes. Toggle between the use of icons and simple ASCII characters with pel-speedbar-toggle-images. It will warn if no speed-bar is opened.

8.52   PEL Spell Checking Support

PDF Sheet:Spell Checking.
PEL Customization:pel-spell-check-tools
PEL Key Prefix:pel:spell : <f11> $

To use spell checking in Emacs, you must first configure it. See the section titled Configure Spell Checking.

The file pel-spell.el contains spell checking utilities that detect and display what spell check mode is active, and initialization code that fixes a problem with Flyspell pop-up menu when Emacs runs in terminal (TTY) mode.

One of the goal of this file is to avoid loading either Ispell or Flyspell until they are actually required while providing a function that can configure these utilities with the information stored inside the pel-spell-check-tools user option variable: the function pel-spell-init-from-user-option.

This sets up the path to your spell checking dictionary and if Emacs is running in terminal (TTY) mode, it allows flyspell pop-up menus to work properly by defining and using the function pel-spell-flyspell-emacs-popup-textual that contains the fix.

The file also provides the pel-spell-show-use command, which displays information about the spell checking programs used, their version and the path to the main dictionary and your personal dictionary

  • Limitations:

    Extraction of spell programs version string done by the function pel-spell-program-version-string works if the version text is printed on the first line only. That works for the followings:

    Earlier versions of these programs were not tested, YMMV.

8.53   PEL Text Alignment Support

PDF Sheet:

Align.
PEL Customization:

none
PEL Key Prefix:
  • pel:align : <f11> t a

PEL provides the pel:align key binding <f11> t a to Emacs text alignment commands.

8.54   PEL Text Filling and Justification Utilities

PDF Sheet:

Filling and Justification, Text-modes.
PEL Customization:

none
PEL Key Prefix:
  • pel:fill : <f11> t f
  • pel:justification : <f11> t j
  • pel:textmodes : <f11> t m

The pel-fill.el provides two simple utilities:

  • pel-auto-fill-only-comments activates/de-activates automatic filling in source code comments only.
  • pel-show-fill-columns displays value of relevant fill columns for current buffer.

PEL also provides several key bindings to Emacs text filling and justification commands, as shown in the Filling and Justification PDF table. PEL uses the <f11> t f, <f11> t j and <f11> t m key prefixes to provide access to several relevant commands.

8.55   PEL Text Insertion Utilities

PDF Sheet:

Inserting Text.
PEL Customization:
  • pel-use-lice.
  • pel-use-smart-dash
  • pel-use-smartparens
  • pel-use-yasnippet
  • pel-use-yasnippet-snippets
  • pel-c-code-style-group : <f11> i <f2>
  • pel-pkg-generic-code-style : <f6> <f2>
  • Also available in the style/skeleton groups of several programming languages.
PEL Key Prefix:

pel:f6: <f6> pel:insert : <f11> i pel:yasnippet : <f11> y

PEL provides a set of generic and specialized insertion commands as well as access to several external packages as described by the Inserting Text table.

For example, PEL provides the following commands:

  • pel-generic-file-header, bound to <f6> h, prompts the user for the purpose of the file and then inserts a file header at the top of the buffer with that information and some other as specified by the user-options in the pel-pkg-generic-code-style. See examples below in the section titled Example of Generic File Header Generation below.
  • pel-insert-line inserts a (commented) line. The length of the line is controlled by the pel-linelen customization variable, which defaults to 77.
  • pel-insert-filename inserts the name of the file in the current or specified window.

Commands like pel-generic-file-header and pel-insert-line are generic commands in the sense that they can be used in several major modes and adapts to them by using the comment style of the major mode to respectively produce a commented-out file header or line. It works for all major modes that identify a command style. PEL does not have to explicitly support the major mode for this to work.

Another very useful feature is the use of the smart-dash-mode provided by the smart-dash external package. PEL provides the <f11> M-- binding to toggle this useful mode on and off. When the smart-dash-mode is activated, you can insert underscore characters by hitting the dash ('-') key without having to press the Shift key. And for programming languages identified by the smart-dash-c-modes user option you can insert -- and -> normally.

The smartparens-mode allows inserting balanced block pairs in various major modes. PEL specialized smartparens for some major mode to extend its usefulness.

The PEL binding include more commands, some are Emacs standard commands, other are from other packages. All are listed in the Inserting Text PDF documentation.

8.55.1   Date & Time Text Insertion

  • The following 8 commands insert time/date format for the local or the UTC time:
    • pel-insert-date inserts the current date at point.
    • pel-insert-date-wkd inserts the current date and week-day at point.
    • pel-insert-date-time inserts the current date and time at point.
    • pel-insert-date-wkd-time inserts the current date, week day and time at point.
    • pel-insert-iso-date inserts the current date at point.
    • pel-insert-iso-date-wkd inserts the current date and week-day at point.
    • pel-insert-iso-date-time inserts the current date and time at point.
    • pel-insert-iso-date-wkd-time inserts the current date, week day and time at point.

The format of the inserted strings are controlled by customized variables in the pel-date-time-insertion group. The default format for the first four commands correspond to free-standing formats you can change. The second group of fours commands are also configurable but they should correspond to valid ISO-8601 standard format strings.

8.55.2   Template Text Insertion

PEL supports two different template mechanisms: the Emacs built-in tempo skeleton system and the popular yasnippet external library.

8.55.2.1   Generic Tempo-based Templates

PEL supports insertion of generic templates that take advantage of the comment style of the current major mode and the identification of various template elements selected from the user-options in the pel-pkg-generic-code-style group accessible via:

  • <f11> i <f2> and selection of the group button at the bottom of the buffer,
  • more directly from M-x customize-group pel-pkg-generic-code-style RET,
  • or its equivalent <f11> <f2> g pel-pkg-generic-code-style RET.

The group allows activation of various template elements:

  • header block style:
    • a default provided by PEL
    • a customized one provided by a tempo-skeleton file created by the user (see more information in the docstring of the user-option),
  • insertion of file time-stamp,
  • Insertion of open source software license,
  • insertion of section titles identified by the user-option,
  • insertion of section separators.

The templates identify locations where more information must be typed. After inserting the template use C-c . to move point to the next location and C-c , to the previous one. If the user types RET on the file purpose prompt, the location for the file purpose is a target accessible with these keys.

See examples in the next sub-section.

8.55.2.1.1   Example of Generic File Header Generation
8.55.2.1.1.1   Generic file header in C

The following is the generic template for C created with the defaults along with the sentence This is where the purpose goes typed as purpose.

/* C FILE: example.c
**
** Purpose   : This is where the purpose goes.
** Created   : Wednesday, October  6 2021.
** Author    : Pierre Rouleau <[email protected]>
** Time-stamp: <2021-10-06 11:49:17, by Pierre Rouleau>
*/
/* -------------------------------------------------------------------------- */
/* Module Description
** ------------------
**
**
*/


/* -------------------------------------------------------------------------- */
/* Dependencies
** ------------
**
**
*/


/* -------------------------------------------------------------------------- */
/* Code
** ----
**
**
*/


/* -------------------------------------------------------------------------- */

Note that PEL also provides specialized templates for C described in the section titled Controlling PEL Tempo Skeletons for C.

For C the comment style can be selected by customization. For instance, the pel-c-skel-comment-with-2stars identifies whether one or two start characters will be used in the C continuation comment. That setting is also affecting the generic templates, making it possible to generate this instead:

/* C FILE: another_style.c
 *
 * Purpose   :
 * Created   : Wednesday, October  6 2021.
 * Author    : Pierre Rouleau <[email protected]>
 * Time-stamp: <2021-10-06 14:10:02, by Pierre Rouleau>
 */
/* -------------------------------------------------------------------------- */
/* Module Description
 * ------------------
 *
 *
 */


/* -------------------------------------------------------------------------- */
/* Dependencies
 * ------------
 *
 *
 */


/* -------------------------------------------------------------------------- */
/* Code
 * ----
 *
 *
 */


/* -------------------------------------------------------------------------- */
8.55.2.1.1.2   Generic file header in FORTRAN

PEL does not support FORTRAN explicitly but Emacs identifies the comment style of FORTRAN code.

C FORTRAN FILE: example.for
C
C Purpose   : This is where the purpose goes.
C Created   : Wednesday, October  6 2021.
C Author    : Pierre Rouleau <[email protected]>
C Time-stamp: <2021-10-06 13:46:49, by Pierre Rouleau>
C ----------------------------------------------------------------------
C Module Description
C ------------------
C
C


C ----------------------------------------------------------------------
C Dependencies
C ------------
C
C


C ----------------------------------------------------------------------
C Code
C ----
C
C


C ----------------------------------------------------------------------
8.55.2.1.1.3   Generic file header in Pascal 
{ PASCAL FILE: example.pas
|
| Purpose   :
| Created   : Wednesday, October  6 2021.
| Author    : Pierre Rouleau <[email protected]>
| Time-stamp: <2021-10-06 13:53:10, by Pierre Rouleau>
}
{ ---------------------------------------------------------------------------}
{ Module Description
| ------------------
|
|
}


{ ---------------------------------------------------------------------------}
{ Dependencies
| ------------
|
|
}


{ ---------------------------------------------------------------------------}
{ Code
| ----
|
|
}


{ ---------------------------------------------------------------------------}
8.55.2.1.1.4   Generic file header in Ruby 
# RUBY FILE: example.rb
#
# Purpose   :
# Created   : Wednesday, October  6 2021.
# Author    : Pierre Rouleau <[email protected]>
# Time-stamp: <2021-10-06 13:58:03, by Pierre Rouleau>
# ----------------------------------------------------------------------------
# Module Description
# ------------------
#
#


# ----------------------------------------------------------------------------
# Dependencies
# ------------
#
#


# ----------------------------------------------------------------------------
# Code
# ----
#
#


# ----------------------------------------------------------------------------
8.55.2.2   Using Tempo Skeleton

To complement the generic tempo templates, PEL also implements specialized tempo skeletons for several major modes, including:

  • C,
  • C++
  • erlang,
  • emacs lisp,
  • reStructuredText.

The PEL tempo skeletons implement relatively large templates like file header blocks that insert the boiler plate code for a given type of file. The format of most of these templates are controlled by PEL user options that control things like:

  • Prompt of file and function purpose
  • Insertion of comment documentation formatting like Edoc and Doxygen
  • Insertion of code block separator lines
  • Insertion of automatically updated file timestamp
  • Insertion of open source code license
  • Use and generation of unique C file header include guard (with UUIDs)

PEL binds keys to the commands that insert and expand tempo skeletons: they are bound to major mode specific <f12> <f12> key sequence, trying to use the same sequence for a concept in all supported modes. For example the key sequence <f12> <f12> h inserts a file header in the supported modes but does it differently for each mode.

Since user options are used to control the format of the tempo skeleton templates, you can set the format globally using customization (use the <f12> <1> key sequence to quickly gain access to customization of the current mode). You can also control the format of all files in a directory tree by storing the relevant user options inside a .dir-locals.el file or control a single file by setting the user options as Emacs file variable.

The tempo skeletons commands for each supported mode are described in the PDF document of the relevant mode.

8.55.2.3   Using YASnippet

PEL also supports the popular yasnippet templating system and the official yasnippet-snippets templates when the pel-use-yasnippet and pel-use-yasnippet-snippets user options are set to t. If you want yasnippet activated when Emacs starts set the pel-use-yasnippet user option to use-from-start otherwise you can activate (and de-activate) the YASnippet minor mode by using the <f11> y y key sequence.

Aside from keys to manage snippets, bound inside the pel:yasnippet key prefix (<f11> y) PEL does not provide any special binding to YASnippet: just type the snippet name abbreviation (called the Yasnippet key) and hit the tab key to expand.

8.56   PEL Text Modes Support

PDF Sheet:Text-modes.
PEL Customization:none
PEL Key Prefix:pel:textmodes : <f11> t m

PEL provides a set of bindings to commands that activate various text modes under the pel:textmodes key prefix, bound to <f11> t m. This includes the following:

  • text overwrite mode,
  • subword-mode,
  • superword-mode,
  • whitespace-mode,
  • picture-mode,
  • artist-mode.

See the Text-modes PDF sheet.

8.57   PEL Text Transformation Utilities

PDF Sheet:Case Conversion, Text-modes.
PEL Customization:none
PEL Key Prefix:none, standard Emacs keys rebound.
  • The pel-text-transform.el file provides commands that handle case conversions taking the case of the word into consideration when performing the operation to help reduce the number of key bindings required to perform the tasks. The provided commands are:
    • pel-upcase-word-or-region upcases the word(s) unless the first two characters are upper case characters, in which case the command capitalize the word(s).
    • pel-downcase-word-or-region downcases the word(s) unless the first two characters are already lower case characters, in which case the command capitalize the word(s).
    • pel-capitalize-word-or-region capitalize the word(s).
  • Emacs has several text modes. The pel-show-text-modes command provides information about them by displaying a description of the modes and their state.
  • The pel-toggle-sentence-end command toggles the number of spaces that identify the end of a sentence for Emacs between 1 and 2. It displays the new value.

8.58   PEL Text Transpose Support

PDF Sheet:Transpose.
PEL Customization:none
PEL Key Prefix:pel:text-transpose : <f11> t t

PEL provides the pel:text-transpose key prefix (<f11 t t) to a set of Emacs commands that transpose text, as shown in the Transpose PDF table.

8.59   PEL Undo Support

PDF Sheet:Undo, Redo, Repeat and Prefix Arguments.
PEL Customization:pel-use-undo-tree, pel-use-goto-last-change.
PEL Key Prefix:pel:undo : <f11> u

PEL provides the pel:undo key prefix (<f11> u) to Emacs undo commands. If the pel-use-undo-tree customization variable is set to t, it uses the undo-tree package to control undo and binds its keys. If the pel-use-goto-last-change customization variable is set to t it also provides access to the goto-last-change command and binds it. All key binding details are in the Undo, Redo, Repeat and Prefix Arguments PDF table.

8.60   PEL (D)VCS Support

PDF Sheet:Mercurial.
PEL Customization:pel-use-magit, pel-use-monky.
PEL Key Prefix:pel:vcs : <f11> v

PEL documents the use of Emacs Version Control support in the Mercurial document, one of several documents that will be written on VCS support (a document for Git will also be written in the future). PEL provides the pel:vcs key-map that gives access to Emacs standard VC (Version Control) directory command but also to Magit for Git and Monky for Mercurial Software.

8.61   PEL Web Browsing Support

PDF Sheet:Web.
PEL Customization:none
PEL Key Prefix:pel:file : <f11> f

Emacs provides several commands that launch a web browser. PEL provides a set of bindings to commands provided by Emacs and some extra commands implemented by PEL code to open a URL or file at point in a browser. The list of these commands and the corresponding Emacs customization groups are described in the Web PDF table.

8.62   PEL Window Management Support

PDF Sheet:Windows.
PEL Customization:pel-use-ace-window.
PEL Key Prefix:pel:window : <f11> w

The file pel-window.el provides a set of window management utilities. Some of these utility commands use or extend the features provided by the windmove library, a library packaged with standard GNU Emacs.

The file provides the following features:

  • Buffer management utilities:

    • pel-show-window-previous-buffer shows the name of the buffer that was previously used in the current window.
    • pel-switch-to-last-used-buffer switch the buffer in current window to the buffer that was previously used.

  • Dedicated window management utilities:

    • pel-show-window-info displays the dedicated status of the current window: ie. whether the current window is dedicated or not.
    • pel-toggle-window-dedicated toggles the dedicated status of the current window. Use it to dedicate the current window or turn dedication off.

  • Creating new windows:

    The following 4 commands allow creating cursor bindings to create windows pointed by a cardinal direction:

    • pel-create-window-down
    • pel-create-window-left
    • pel-create-window-right
    • pel-create-window-up

  • Closing windows:

    The following 4 commands allow creating cursor bindings to close windows pointed by a cardinal direction:

    • pel-close-window-down
    • pel-close-window-left
    • pel-close-window-right
    • pel-close-window-up

  • Window splitting:

    • The function pel-split-window-sensibly attempts to improve window splitting logic by selecting an orientation that takes the frame size into account with a different heuristic than what is normally used by Emacs. The function is used by other PEL commands when windows are created. The logic gives priority to splitting vertically if the available area is wide enough.

  • Changing orientation of 2 windows:

    The commands pel-2-vertical-windows and pel-2-horizontal-windows flip the orientation of the current and next window from horizontal to vertical and vice-versa.

  • Moving to windows by direction or context:

    Two functions provide services to move point to other window by direction or to create a new one. These functions are used by other PEL commands. The functions are:

    • pel-window-valid-for-editing-p move point to the identified direction as long as the target window can be used for editing. This excludes the mini-buffer or any dedicated window.
    • pel-window-select move to the window specified by a direction argument or to the other window (the next one) or create a new window. This is also a utility function used by other PEL commands.

  • Moving to other (next) or previous window:

    • The pel-other-window is just explicitly calling the Emacs other-window command that might be hidden by the use of ace-window.
    • The pel-other-window-backward moves to the previous window.

  • Showing information about current window:

    • pel-show-window-filename-or-buffer-name displays the name of the file or buffer used in the current window.
    • pel-show-window-info displays the height and width of the current window, whether the window is dedicated, fixed in size, etc...

9   PEL Implementation

9.1   Emacs Lisp Files

PEL code is spread across several Emacs Lisp files. The file names have been selected with the following constraints:

  1. Conform to the Emacs Lisp Packaging rules. However, because of the nature of PEL it is currently not distributed via an Elpa-compliant repository. It currently provides the files pel-pkg.el and pel-autoloads.el but these are unused and may be removed in the future.
  2. Control byte-compilation under several scenarios, including the following:
    • Manual installation by cloning the PEL Git Depot and then using the PEL Makefile to create a local package archive, and compile all files locally.
    • Dynamic byte-compilation of pel_keys.el, pel__hydra.el and some files not normally byte-compiled like the autoloads.el file of the pel-bundle pseudo-package used in fast startup mode as well as the package-quickstart files on request.

The PEL Emacs Lisp files types are the following:

  1. Local files, used by all other PEL files.
    • These files have a name that starts with pel-- and sort before all other files.
    • These files can be byte-compiled independently within an emacs -Q session and will not generate any warning.
    • These include:
  2. PEL feature files.
    • These files have a name that starts with pel-.
    • These files can be byte-compiled independently within an emacs -Q session and will not generate any warning.
    • These files implement PEL specific convenience features. Some are independent from external packages, others provide a logic layer on top of external packages and a dynamically control access to the external package features enabled via the PEL option pel-use- configuration variables as described in the PEL Customization section.
    • The PEL features implemented by these files are described inside some of the sub-sections of PEL Convenience Features.
      • As an example of one of the PEL convenience feature file, the file pel-navigate.el provides extra navigation facilities such as the use of multi-hit <home> and <end> keys similar to what is available by editors in the Brief family (such as CRiSP) but also aware of Emacs concepts such as text fields, shift-key selection and Emacs mark and region. This is detailed in PEL Navigation Support.
    • These files are mostly independent from each other.
    • Several of these files can be used as stand-alone libraries when someone does not want to use the entire PEL system.
    • It is possible to use one or several of these PEL features without using the PEL key bindings. To do that, just use the files that contain the features you need and write your own key bindings for them inside your Emacs init file. Just don't call pel-init.
  3. PEL key binding file: pel_keys.el.
    • This file has a name that starts with pel_, using the unusual underscore for Emacs Lisp files. The underscore is used as a simple way to ensure that this file has a name that sorts after the files of the other two types above.
    • This file is only loaded and used by the file pel.el.
    • This file defines all PEL key bindings. It also contains the logic to install external packages lazily when the corresponding PEL option activates it.
    • This file holds content similar to what users would put inside their Emacs init.el file.
      • This file is, however, byte-compiled. But it is byte-compiled after every other PEL file has been byte-compiled.
        • The byte-compilation line for this file inside the Makefile loads the user's init.el file. The Makefile identifies it with the EMACS_INIT macro, and it is defined by default to be located inside "~/.emacs.d/init.el".
    • The file pel_keys.el loads the file pel-autoload.el to define the auto-loading of all PEL features.
  4. PEL top level file: pel.el.
    • This file holds the pel-init command. That loads the pel_keys.el file, in a similar manner that a init.el file would be loaded.
    • This is the only file auto-loaded by the standard package auto-load control file: pel-autoloads.el.
  5. The other Emacs Lisp files are not part of the PEL package itself. They are tools used to help automate installation of PEL:
    • The file install-pel.el controls the creation of a local Emacs package archive which is then used to install PEL on local computers from a cloned Git depot.

PEL loads only what is needed based on commands executed. It uses several Emacs Lisp macros to control package detection and package loading with emphasis on delayed execution whenever possible. These are all used in the code of Pel_keys.el which is loaded by the pel-init command.

PEL also auto-loads its code as much as possible but does not rely on the package.el autoload cookies to do so because it does not support automatic installation. Instead it provides auto-loading declarations inside the pel_keys.el and inside pel-autoload.el

  • The pel-init command loads pel_keys.el explicitly.
  • The pel_keys.el code loads pel-autoload.el and then calls pel--autoload-init. That function defines the auto-loading of all pel- files, the PEL feature which are mostly independent from each other.

Currently, PEL uses its own logic on top of the built-in package library to control the installation of missing package if the corresponding feature is activated via PEL customization pel-use- customization variable. PEL mechanism to control external package is similar to what the use-package library provides but also provides support for non-Elpa packages and includes logic specific to PEL that is aware of PEL fast-startup mode.

The list of external packages used by PEL is shown in the Credits section.

9.2   Naming Conventions

  • All PEL "public" functions and variables have a name that start with the prefix "pel-".
    • This includes all PEL commands.
  • All PEL "private" functions and variables have a name that start with the prefix "pel--".
    • Those are meant to be used from with PEL code exclusively.
    • The same convention also applies to the Emacs Lisp file names; the files pel--base.el, pel--macros.el and pel--options.el are used by the other PEL files.
  • All PEL customization variables that control whether PEL uses or provides a given feature have a name that starts with the prefix "pel-use-".
  • Most PEL key-maps have a name. All of those name start with the prefix "pel:".
    • Using named key-maps help shows the key prefix purpose when using which-key to display the available key following a prefix or typing C-h or <f1> after typing a prefix key to see the list of available keys and their meanings.
    • The only key prefix that does not have a name is the one used for F12, the mode sensitive prefix key (I did not find a way to name it, so if you have an idea, let me know! :-)
  • All Emacs Lisp files that are part of the PEL package have a name that starts with the "pel-" prefix.
  • Emacs Lisp test files are stored in the test sub-directory and have names that have the "pel-" prefix and the "-test" suffix.
  • Other Emacs Lisp files are included in this repository, such as build-pel.el and install-pel.el. These file are not part of PEL itself and may be removed in the future. These files contain code that is not part of PEL but are used to develop PEL. The names of these files do not start with "pel-" but they end with "-pel". That should be enough to prevent clash with other packages. If this is not enough for you, since these files are not required to use PEL, feel free to move or erase those files in your local directory and let me know; I'll try to find a better way. Note that these files, and none of the build related files, are not part of the PEL package distribution tar file.

9.3   Code Guidelines

9.3.1   General Guidelines

Overview

The Emacs Lisp code is written to comply with the standard GNU Emacs code guidelines. PEL code follows most of the points promoted by bbatsov/emacs-lisp-style-guide except in some few places. PEL code also follows several ideas outlined in Jari Aalto Emacs Lisp Guideline, an older but still valid guideline.

Line Length

The maximum line length is 80.

Use of tabs

PEL source code does not use hard tabs. All indentation uses space characters.

Settings enforced by directory local variables

The file .dir-locals.el imposes the line length and the use of spaces for indentation. See the GNU Emacs Manual Per-Directory Local Variables for more information about this file.

Used Tools

To ensure conformance, the code is checked with the following tools:

  • GNU Emacs elint-file command from Standard GNU Emacs elint.el.
  • The external package elisp-lint which uses the following other tools:
    • Emacs Lisp byte-compiler,
    • Emacs Lisp checkdoc,
    • indent (to confirm indentation inside a file).

The file pel.el is also checked with package-lint to verify the presence of package version.

9.3.2   Variable Scoping

PEL code uses lexical scope in all Emacs Lisp files. Each of these file sets the lexical-binding local variable to t.

For more information on why this is done, read Chris Wellons' article titled "Some Performance Advantages of Lexical Scope" written in December 2016.

Aside from the advantages outlined by the article, linting Emacs Lisp code finds more issues when lexical scope is in effect.

9.3.3   Licensing

The license information is stored in each .el file.

9.3.4   Checking PEL Code

The included Makefile provide rules to byte-compile and lint all files and then run the regression tests. The following commands are used to test the code, issued from PEL root directory:

make clean
make compile
make lint
make test

There should be no error, no warning and all tests should pass.

9.4   Emacs Lisp Regression Test

At this point just a small portion of PEL is covered by ERT-based testing. The test code is located inside the test sub-directory. As everything in PEL for this early version: 🚧 more to come here...

9.5   Building PEL

Note:
You must build PEL to use it. PEL uses the byte-compiler and macros to activate specific parts of the code and to speed it all up. Building is easy with make: just run make.
Note 2:
At this moment, for this early version of PEL, I did not submit PEL package into Emacs Lisp archives like MELPA. I may do this later, but the nature of PEL differs from a stand-alone package.

Use the Makefile to control command line build of the PEL distribution package, the byte compilation of all PEL Emacs Lisp source files.

To see what you can do with the Makefile, move to the directory where it is located and issue the make help command which lists the available top-level targets and their purpose.

9.6   PDF Documentation

The list of documentation files are currently published as several tables in PDF topic-oriented reference sheets with a top-level PEL Index PDF with links to all the PEL PDF files.

Although this is not the best way since this is an output format file as opposed to the source of the document, these files were created in PDF format because I wanted to be able to pack a lot of information about Emacs as I was learning it. I considered using a markup language like markdown or reSTructuredText. The latter is more powerful, and it would have been possible to generate tables with some of the attributes of what I was able to generate but it would have most probably needed its own web site to be able to completely control the CSS as well as write extensions in Python for what I needed. And I did not have time for that. I needed to concentrate on Emacs and jot down notes on something that, at the beginning of my learning period, was not Emacs. So I compromised and used the macOS Numbers program to create a large spreadsheet with multiple tabs and tables. I used that to generate the PDF files.

This is far from ideal. I know. And once PEL gets to the point where support for several other programming languages is integrated, I might find ways to use a markup language that might be flexible enough to generate the same kind of output.

As an temporary work-around, I tried to export the file to CSV or TSV (tab separated value). That generates the text but the hyperlinks are not part of the CSV/TSV output files. I might consider producing those files if there is any interest, but I'd prefer to be able to publish the source of something that can generate the kind of output that's available in those PDF files.

I am open to suggestions. In the mean-time, I push a copy of that Numbers file regularly in the pel-pdf-spreadsheet repo.

9.7   Planning and Future

At this point there's no formal planning for this project.

I have mainly been writing this as a way for me to learn and remember Emacs as a tool and Emacs Lisp as a programming language. But I am planning to use it for most of my upcoming work and will continue to document what I learn and what I use when developping in various programming languages and doing various tasks.

9.8   Override or change PEL key bindings

As of this release PEL key bindings and key prefixes are hard coded. If you want to change a key binding that PEL uses, you can define your own key bindings after the execution of pel-init. You can also change PEL prefix keys.

The following code re-assign the F6 key to undo and uses the F9 key to be used as what PEL normally uses for F6:

(global-set-key (kbd "<f6>") 'undo)
(global-set-key (kbd ("<f9>") pel:f6)

The Function Keys Mappings PDF table provides and overview of the way PEL uses the function keys. See also the section titled PEL Function Keys Bindings.

Since PEL is using more keys over time, it might be difficult to change the bindings without affecting PEL's bindings. If you have a specific request, please describe your request on the PEL wiki, I'll take a look and see what I can do.

10   How to Modify the Terminal Keyboard Shortcut Keys

PEL makes extensive use of function keys such as F11 but some other function keys too. In some environment these keys are used by the terminal emulator programs you may want to use to run Emacs in terminal (termcap) mode. Fortunately most environments provide ways to change the shortcut keys used by their terminal.

When running in terminal mode, there are several key modifier combinations that PEL never uses because they are normally not accessible to programs running under a terminal. These combinations are, however, accessible to top-level programs such as the terminal emulator themselves and therefore good candidate for shortcut replacements. The following modifier key combinations are never used by PEL:

  • Control-Function key
  • Shift-Control-Function key
  • Super-Function key
  • Shift-Super-Function key

10.1   Disable Ubuntu HUD use of the Alt Key

The Ubuntu Linux distributions that use the Unity user interface also support the HUD (which stands for Heads-up display) which unfortunately uses the Alt key as a hotkey. This is very annoying with Emacs (and several other applications) as it forces you to type the Alt key twice for Emacs Meta key modifiers.

To disable the HUD shortcut key:

  • Open Ubuntu System Settings application
  • Select the Keyboard settings
  • Open the Launchers tab
  • Select the Key to show the HUD line, double click on the shortcut (which is Alt-L by default), then press backspace to disable the shortcut.

The Alt key will then become available inside Emacs as the Meta key.

See the popular AskUbuntu question "How do I modify or disable the HUD's use of the Alt key?" for snapshots and more information.

10.2   Modify GNOME Terminal Shortcut Keys

Configure the GNOME Terminal keyboard shortcuts by opening its Preference dialog, and select the Shortcut tab:

res/gnome-terminal-01-02.png

You will probably want to modify the F1, F11 and some other keys. Select the Action that is assigned to the key shortcut that you want to free and double click on the Shortcut Key column for it. Then hit the key modified combination that PEL does not use and that you want to use.

res/gnome-terminal-03.png

You also might want to configure the several key shortcuts to prevent clashes with Emacs. The pdf titled Ubuntu 16.04 Linux Desktop Keys on macOS Host lists a set of key shortcuts that might be useful.

11   Credits

PEL integrates with several great Emacs Lisp packages. Some of them are required, the others are used only if they are present and are activated by the PEL customization. PEL's code is written to operate despite the absence of external packages that have not been activated but it expects presence of packages that are distributed with GNU Emacs.

First PEL would not exists without GNU Emacs. Most of the text in the PDF documentation comes from Emacs own documentation, both from the code docstrings and from the Emacs manuals.

PEL uses the following libraries distributed with GNU Emacs and several others listed below. The list is unfortunately incomplete as it grows continuously when PEL supports new packages.

  1. bookmark
  2. cc-vars
  3. cua-rect
  4. delsel
  5. elint
  6. ert library
  7. ffap
  8. flyspell
  9. goto-addr
  10. hippie-exp
  11. hl-line
  12. ido
  13. imenu
  14. isearch
  15. ispell
  16. kmacro
  17. lisp-mode
  18. newcomment
  19. org
  20. paragraphs
  21. re-builder
  22. rect
  23. rst
  24. simple
  25. subr-x
  26. subword
  27. skeleton
  28. time-stamp
  29. tempo
  30. thingatpt
  31. uniquify
  32. webjump
  33. winner

It also provides access to the features of the libraries listed in the following table when the corresponding PEL user option is set to t. This table is currently incomplete. The link to the original projects are available in the source code and inside the customization buffers.

Package Name & Archive link Archive Site
ace-link MELPA
ace-window MELPA
adoc-mode MELPA
ag MELPA
alchemist MELPA
all-the-icons MELPA
all-the-icons-ibuffer MELPA
all-the-icons-dired MELPA
all-the-icons-ivy MELPA
anzu MELPA
apples-mode MELPA
ascii-table MELPA
auto-complete MELPA
avy MELPA
bind-key MELPA
bm MELPA
c-eldoc MELPA
cargo MELPA
centimacro MELPA (see [4])
company MELPA
counsel MELPA
d-mode MELPA
desktop+ MELPA
desktop-registry MELPA
dired-narrow MELPA
dumb-jump MELPA
edts MELPA
elixir-mode MELPA
elmacro MELPA
elpy MELPA
erlang.el MELPA
esup MELPA
expand-region MELPA
flycheck MELPA
flycheck-plantuml MELPA
exunit MELPA
fill-column-indicator MELPA
forth-mode MELPA
framemove Emacsmirror
free-keys MELPA
goto-last-change MELPA
graphviz-dot-mode MELPA
helm MELPA
hide-comnt.el Emacsmirror
highlight-defined MELPA
hydra MELPA
iedit MELPA
ivy MELPA
julia-mode MELPA
julia-snail MELPA
js2-mode MELPA
keycast MELPA
key-chord MELPA
key-seq MELPA
lfe-mode MELPA
lice MELPA
lispy MELPA
lpy MELPA
macrostep MELPA
multiple-cursors MELPA
Magit MELPA
Monky MELPA
neotree MELPA
nhexl-mode ELPA
parinfer MELPA
pcre2el MELPA
plantuml-mode.el MELPA
popup MELPA-STABLE
popup-kill-ring MELPA
projectile MELPA
python-mode MELPA
racer MELPA
rainbow-delimiters MELPA
regex-tool MELPA
rexx-mode EmacsAttics
ripgrep.el MELPA
rg MELPA
rust-mode MELPA
slime MELPA
smart-dash MELPA
smooth-scrolling MELPA
sr-speedbar MELPA
swiper MELPA
undo-tree ELPA
v-mode MELPA
visual-regexp MELPA
visual-regexp-steroids MELPA
vline Emacsmirror
vterm MELPA
which-key MELPA
xr ELPA
yasnippet MELPA
yasnippet-snippets MELPA
ztree MELPA

For developing PEL, the following extra packages are used.

Package Name & Archive link Archive Site
benchmark-init MELPA
elisp-lint MELPA
package-lint MELPA

Thanks to everyone that has worked in the software listed above. Hopefully you will find PEL useful for using these packages.

Note: the fill-column-indicator package is not required when running Emacs 27.1 and later versions.

Also, note that several ideas came from various blogs and discussion on the web. There are references the these pages inside the PDF tables in the reference sections, or also inside this manual. This includes the following (non exhaustive list):

[4]Currently using my fork of centimacro until a bug fix I submitted gets integrated.