DOCUMENTATION.org

Lambda-Emacs Documentation

Lambda-Emacs (𝛌-Emacs, or LEM) is intended to serve three goals. First, as a useful starting point for the user’s own custom configuration. Second, and relatedly, as providing enough commentary on configuring Emacs such that it might be useful to those new to emacs or even text-editors generally. Third, as a “starter-kit” for writing and academic work in the humanities.

𝛌-Emacs File-Directory Structure

– NOTE: The directory structure has changed in the most recent version, so please be careful updating! –

The configuration consists of a set of files specific to the user (all stored in the value of lem-user-dir (“lambda-user” by default)) and more general files for 𝛌-Emacs (init.el and the setup files in the value of lem-setup-dir (“lambda-setup” by default)). The structure is as follows:

• Directory Structure:
  • Emacs directory (.emacs.d)
    • Library directory (lambda-library)
      • Lambda-Emacs setup files (lambda-setup)
      • User directory (lambda-user)
        • user config.el file
        • lambda-/user/ setup-files
        • user custom themes directory
    • “Variable” directory (var) – contains files that are often changed by the system
      • Volatile storage (cache)
      • Non-volatile storage (etc)
      • External packages (straight)
• File structure:
  • early-init.el
  • early-config.el (in lambda-user, supplied by user, if any)
  • init.el
  • config.el (in lambda-user, supplied by user, if any)

Ideally the user will not need to do anything to the files early-init.el, init.el, and those in lambda-setup, though they should read the code to get a sense of what each file/module does. I have tried to annotate the code sufficiently so that it does not assume familiarity with elisp to understand the basics of what is going on.

All personal configuration by the user should go in config.el in the lambda-user directory. This includes setting all variables, such as theme, font, and bibliography and notes files.

𝛌-Emacs Customizable Variables

Variable	Purpose
lem-prefix	Prefix for personal keybinds
lem-ui-default-font	User default font
lem-ui-variable-width-font	Variable width font
lem-persistent-scratch	Whether to make scratch buffer persist across sessions
lem-scratch-save-dir	Where to save scratch file
lem-scratch-default-dir	Default dir for scratch buffer
lem-ui-theme	User prefererred theme
lem-custom-themes-dir	Directory for custom lambda-themes
lem-bib-notes	File for reference notes
lem-bibliography	User bibliography used in citations
lem-notes-dir	Directory for user notes
lem-citar-note	Template for citar notes
lem-project-dir	Directory for user projects
lem-user-elisp-dir	Directory for personal elisp projects
lem-splash-footer	Splash footer message

lem-prefix defaults to C-c C-SPC and lem-ui-theme defaults to lambda-themes. The other variables need to be set by the user in the config.el file in the lem-user-dir.

In any case, be sure to set these variables in your config.el file before loading any specific modules.

Package Management

Lambda-Emacs uses straight.el to manage ”packages” (i.e. lisp libraries that enhance and extend Emacs’ functionality). This easily allows the user to add packages from any source (melpa, elpa, gituhub, gitlab, etc.). It is an alternative to package.el, so the user should use it instead of the built-in Emacs package manager. To browse and temporarily install packages use M-x straight-use-package and type the name of the relevant package.

Otherwise any packages you would like you can install yourself using straight. You “declare” these packages in your config.el file like so, integrating with use-package:

(use-package my-package
  :straight (:type git :host github :repo "my-package")
  :config
  (setq my-package-setting))

Straight only loads packages that are explicitly declared in your config (and in the overall Lambda-Emacs setup). You can also “freeze” your package state, which is extremely helpful if you like to update frequently and run into problems with a package. Use M-x straight-freeze-versions. For further details consult the manual.

When updating packages use straight-pull-all for all packages or straight-pull-package to update a specific package. See the manual for further details. Before installing a package be sure it isn’t already installed and configured in lem-setup-dir. To see if a package is already installed use M-x find-library and type the package name.

Modules

Lambda-Emacs provides a series of “modules” for allowing the user to get up and running with using Emacs productively. Each module configures a package (or set of packages) and provides some reasonable defaults. The modules should be thought of as a starting point for scaffolding the user’s configuration. A module only provides such configuration if it is loaded, either in the user’s config.el file or by default if there is no such file.

The user can override a module in one of two ways. They can load it and change settings in the user config.el file. This is perhaps the best way to make small tweaks to any setting in an lem-setup-* file. Alternatively, if the user wants to make more elaborate changes, the best thing to do is copy over any desired setup from the original module to a new user module (which the user creates in the lem-user-dir) and to load that module instead. This allows the user to easily keep track of any upstream changes to the Lambda-Emacs setup files while also providing whatever custom configuration the user wants.

Code Conventions

• Where appropriate, use custom-set-variable rather than setq when dealing with defcustom variables. For some discussion see this stack exchange discussion.
• Please consult the elisp style guide for all style conventions with regard to naming, etc.
  • Note that all functions and variables are prefixed with the “lem” namespace.
  • Internal functions have their namespace delineated by “--” while user-facing functions have only a single “-“.
• Provide defcustom variables for things we expect the user to modify and make sure it is in the appropriate group.
• Prefer customize-set-variable instead of setq for defcustom values. This helps make sure constructors or setters attached to the variable are run when the value is set.
• Provide verbose doc-strings for defvar, defcustom, defun, defmacro, etc to clearly document what is going on.
• Make sure to follow doc-string guidelines (see Documentation Tips or elisp#Documentation Tips)
• Add comments for blocks of code, especially to describe why the code is present, or the intention. These comments serve as documentation when reading the code where a doc-string is not an option.
• Add appropriate headers for sections of code
• Where appropriate, order packages alphabetically, e.g., in a setup file.
• Add or update documentation in the docs folder.
• If your PR addresses an issue, whether it closes or fixes the issue, or is just related to it, please add the issue number in your commit message or the description of your PR so they can be linked together.