README.org

Emacs Initialization

This is my working emacs configuration, currently used for Emacs 25+ but should work for Emacs 24+. The installation process described below will install the required emacs packags, will open a tool to let you quickly personalize the data and customizations used in the init file, and will offer a tutorial on notable features of this init-file configuration.

Installation

Running the installation script installs the initialization files in a chosen target directory, along with a root initialization file that is loaded first and loads the others. The main files, as cloned from the github repository, must be in the init subdirectory of the traget directory.

The recommended method is to install the repository in your emacs initialization directory (e.g., ~/.emacs.d/). This is the default expectation. But you can also install these files in a different location by specifying the target directory with --target=DIR in what follows. Indeed, with a combination of the --target and --init-file options, you can install the entire setup independently of your default emacs directory.

To install, take the following steps.

1. Choose your target directory and move to it. In the typical case, this will be your emacs initialization directory (e.g., ~/.emacs.d/).

   Replace ’TARGET_DIRECTORY’ in the following with the path to your chosen directory and enter this at the shell prompt:

   cd TARGET_DIRECTORY
       

2. Clone this repository.

   git clone https://github.com/genovese/emacs-init.git
       

   This will create a sub-directory emacs-init in your target directory.

3. Rename emacs-init to init in this directory.

   mv emacs-init init
       

4. Change to the init directory.

   cd init
       

5. Run the install script.

   If the target directory is your emacs initialization directory, there is no need to set the --target option as it will be correct (..) by default for this case. Otherwise, append --target=TARGET_DIRECTORY to what follows, where again TARGET_DIRECTORY is replaced by the absolute path to the target without a trailing ‘/’.

   Enter the following command at the shell prompt:

   bash Extras/Install.sh
       

   This will install the base code and all extras, including overwriting ../emacs-custom.el and .emacs.el in the home directory. This will also install and compile the required emacs packages in ../elpa or ../.cask (depending on the setting of --package) These packages are needed to use this emacs init-file configuration.

The script has a variety of options; a few notable ones are:

a. --safe prevents ovewriting any files that already exit

b. --package sets the package system used to install the emacs packages for the init file to run.

Allowed values for this option are package, cask, cask-homebrew, or auto, with auto being the default. For example, --package=package uses the package.el system. The cask setting requires the cask package manager to be installed, with cask-homebrew indicating to use the homebrew version of cask. The auto setting attempts to deduce the proper package system from the availability of executables.

c. The initialization files are installed in the init sub-directory of the target directory, and a root init file – which is loaded first and loads the rest – is installed as .emacs.el in the user’s home directory. (If the file already exists, it is backed up first.) The name and location of this file can be customized with the option --init-file=FILENAME, or the root file installation can be suppressed with --no-init-file, in case one wants to customize loading.

d. On Mac OS X, the --homebrew option indicates to prefer the homebrew version of various tools. In particular, this affects which emacs is used for package installation and the data review step.

e. By default, this script will install all the emacs packages that are needed for this initialization to run, using your chosen method. This can take a few minutes to complete.

If you have already installed those packages or would like to install those packages some other way (only do this if you are know what you are doing), then you can suppress package installation with the --no-install option. If the emacs packages are already installed when you run this script and you give --no-install, you will probably want to supply the --force-review option to get full functionality from the review tool.

By including the --dry-run flag with any set of other options, you can see what the script will do without it taking any action. The --verbose flag can also be helpful here.

For more details and options, run the script with

bash Extras/Install.sh --help

Note that emacs package installation can take a few minutes. Progress is indicates to the terminal, with additional information printed when --verbose is supplied.

1. The script evokes an application (within emacs of course) for personalizing some of the settings and data in this configuration. This includes:
   • Editing the preferences data in the file data/preferences.el, to reflect your personal settings. The most important settings to change are user-home-page, user-email-address, shell, and theme-function. Simply edit the values for each key, as instructed in the application.
   • Editing the customization settings in emacs-custom.el. The application lists the variables and faces in the custom file, showing the current setting, and giving a button to push to open a customization buffer for that setting. View and change the settings as you like, hitting the ‘Apply and Save’ button in the respective customization buffers. This will set these values for future emacs sessions.
   • Viewing some tutorial information about the configuration.

   When complete, hit the ‘All Done’ button, and the Install script will continue. If the emacs packages are not installed, the customization portion of the review step will have reduced functionality. If emacs packages have been pre-installed, supply the --force-review flag to get the full customization review.

If you maintain this config outside your emacs initialization file, you might find the shell script Extras/Update.sh useful. It provides for simple updating of the Extras files (e.g., Cask) from the working initialization directory.

Appendix: Install script overview

For reference purposes, the Extras/Install.sh script roughly does does the following, with TARGET set by the –target option:

1. Create directory $TARGET/init if it does not exist.
2. Recursively copy all files starting with a lower-caser letter from this directory to $TARGET/init, unless that is the current directory.
3. Copy Extras/home-dot-emacs.el to ~/.emacs.el, transforming it based on the --package and --target options to set the package source. (This can be package, cask, or cask-homebrew)
4. If $TARGET/site-lisp does not exist, create it and copy files from this site-lisp directory there.
5. If $TARGET/themes does not exist create it and copy files from this themes directory there.
6. If --install is given, move to $TARGET directory temporarily and install the packages, either with the included tool (that uses emacs’s package.el facility) or with the cask package manager.

If –package is not supplied, the script will attempt to auto-deduce it based on your system, on whether it can find the cask tool, and on whether the --homebrew option is supplied.

Usage Overview

A few notable features are described below. See also the file Extras/tutorial.org for some more detail; this tutorial is displayed during the review step of initialization.

• Keybindings: Help

  Default emacs keybindings reserve C-h for help. While help is important and commonly used, it does not need a top-level (control) key. Instead, we do the following:

  • C-h – delete-backward-char
  • M-h – backward-kill-word
  • C-M-h – help

  This is much more efficient than the defaults (no more need for backspace and backward-kill-word is very commonly useful). The main complication is that most modes (and to some extend emacs itself, see help-char) assume C-h for help, which requires additional effort to configure.

• Keybindings: Scrolling and Cutting

  Also in the default keybindings use C-v and M-v for scrolling up and down. This cuts across levels (control to meta) for a comparable-level operation and is slow, as a result. It also leaves C-w, non-mnemonically, for a kill operation. Instead, the keybindings here do the following:

  • C-w – scroll down
  • C-v – scroll up
  • M-w – beginning of buffer
  • M-v – end of buffer
  • M-C-w – scroll down other window
  • M-C-v – scroll up other window
  • C-k – kill line
  • M-k – kill region
  • M-C-k – kill sexp

  Again, this requires some remapping in configuring some common modes.

• Help Navigation

  To make the Emacs help system even easier to use, this adds two mechanisms for navigating. First C-M-h g from any buffer moves to the help buffer, where g moves back to the previous location. Second, C-M-h followed by various navigation commands moves the help buffer without changing the active buffer. These commands are as follows:

  • C-w – scroll down
  • C-v – scroll up
  • M-w – go to beginning of buffer
  • M-v – go to end of buffer
  • C-b – back to previous help page
  • C-f – forward to next help page
  • RET – push button
  • TAB – forward-button
  • S-TAB – backward-button
  • q – quit help
• Server start

  This initialization always starts the emacs-server so you can interact with a running instance using emacsclient.

• Components and Mods

  The components directory contains files that each load and configure a cluster of related packages and/or modes.

  The mods directory contains mode- or tool-specific modifications and code. These represent structural changes or code that offers new/improved functionality. This includes improved help navigation, directory tracking systems for tcsh and zsh (separately), extensions to dired, and some extra tools for AucTeX and Org. Some of the earlier mods have been spun off into their own packages (e.g., win-switch) or into existing emacs code (e.g., ibuffer).

• Zenburn+ Theme

  A modified zenburn theme, zenburn+, is available in Extras/themes.

• Local Code and Modifications

  The local/ subdirectory (and the subdirectories therein) is intended for user code, including code to modify or override the code in this config. Any .el or .elc files in local/ are loaded; any subdirectories are added to the load path; and any .el or .elc files in such subdirectories are also loaded. This happens after all other code in the config is executed. Files beginning with ‘-’ are excluded from loading.

File Manifest

File or Directory	Description/Notes
dot-emacs.el	Main entry point
macros.el	Utility macros used in the configuration
ops.el	A few user-level operational functions
utils.el	A small collection of elisp utilities
theme-support.el	Configuration and utilities for custom themes
keybindings.el	Keybindings
translations.el	Keyboard translations and mouse emulation
frames.el	Commands and tools for manipulating frames
hooks.el	Hook settings for built-in commands/tools
data	Directory containing preferences and other user-level data
data/preferences.el	User preferences data used throughout the configuration
data/user-system.el	User, platform, and system level constants
components	Directory containing code to configure various emacs tools and packages
components/*.el	Individual component loaders and configurations
mods	Directory containing mode- or tool-specific modifications
mods/*.el	Code for individual mods, arranged by tool
locals	Directory for installing local files; loaded after existing code
prototypes	Experimental or pre-packaged code
prototypes/*.el	Individual prototype modules (give file name ‘-’ prefix to disable)
Extras	Directory with supplementary files to be installed in target or home
Extras/Install.sh	Installation shell script (use –help for details)
Extras/Update.sh	Shell script to update Extras from target when repo stored elsewhere
Extras/Cask	Current, though non-minimal, Cask file
Extras/themes	Current custom themes
Extras/site-lisp	Current extra elisp
Extras/home-dot-emacs.el	Init file for home directory that loads packages and this code
Extras/emacs-custom.el	My current emacs-custom.el, read during config.
Extras/my-env.el	My current environment settings, use –with-env to install this
Extras/packages.el	Package installer tool for emacs, used during Install script
Extras/review.el	Application for personalizing configuration, used during Install script
Extras/tutorial.org	Tutorial document, used during Install script
README.org	This file