How I've customized Emacs for my needs
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.emacs
.gitignore
LICENSE.md
Makefile
README-modules.org
README-status.org
README.org
beacon.el
c.el
cedet.el
clisp.el
clojure.el
completion.el
elisp.el
evil.el
font.el
haskell.el
init-examples.el
init.el
magit.el
module-example.el
module-test.el
mozart.el
ngender-compile-log
ngender.el
org-list-files
org-tlist-files
org.el
ox-tiki.el
php.el
prolog.el
rust.el
scala.el
shell.el
sql-accounts.el
sql.el
tcl.el
workgroups.el
workspace.el

README.org

NGender Emacs Configuration Directory

This Directory Tree is a Git Repository.

Summary: TL/DR

  • This is an Emacs Profile
  • It is for the use of Emacs by Power Users
  • You need to be somewhat comfortable with
  • What you’ll get if you use this Profile:
    • Ease in setting up many powerful packages
    • Ease in establishing many useful customizations
  • If you want to try it out, follow the directions in
    • Installing This Profile (below)

The Purpose of this Profile

Much of the power of Emacs is due to its extraordinary customizability through settings and extentions. Many of the most powerful extensions are in the form of Packages, typically available from Emacs Package Archives. Emacs Packages are themselves highly configurable. Many of these extensions are also designed to be combined and/or layered.

We would like to make configuring and extending Emacs easier for Users, especially Power Users who are willing to do some simple editing of configuration files.

We would also like to make it easier for these Power Users to share what they have done with other members of their Projects, Groups and with the Emacs Community at large. This is what Git enables.

We designed this repository to make Customizing Emacs more convenient by

  • adding additional package archives
  • adding and configuring additional packages
  • setting variables to further customize Emacs features
  • defining additional functions and variables
  • adding keymappings to quickly invoke functions

We intend that the customizations in this repository can be

  • shared by many people
  • improved by many users for the benefit of all
  • independent of any individual user’s tastes
  • easily configured to each user’s taste!

This is a project of RPTUG, the

It is expected to work well

  • on any account
  • on any operating system supporting Emacs
  • with any up-to-date Emacs

Layout of the Repository

We assume here that your .emacs file is stored in your home directory, denoted by ~ and that your Emacs Customization Directory is ~/.emacs.d/ – these locations can be changed if another arrangement is more convenient.

~/.emacs
links, loads or forks .emacs.d/NGender/.emacs
~/.emacs.d/
your Emacs Customization Directory
~/.emacs.d/init.el
links, loads or forks NGender/init.el
~/.emacs.d/NGender/
extension modules shared with Emacs Community
~/.emacs.d/NGender/.emacs
establishes paths & gets things started
~/.emacs.d/NGender/init.el
loads user module
~/.emacs.d/NGender/ngender.el
core module loaded by .emacs file
~/.emacs.d/NGender/NAME.el
module providing extension NAME
~/.emacs.d/User-Me/
individual extensions
~/.emacs.d/User-Me/init-me.el
automatically loaded by init.el
~/.emacs.d/User-Me/custom-file.el
Emacs Customization System settings
~/.emacs.d/Group-NAME/
modules shared with group/project Group-Name
~/.emacs.d/NGender/init-examples.el
snippets to copy/paste into init-me.el
~/.emacs.d/Makefile
script to help set up the above links

In most cases our provided .emacs and init.el files will meet your needs well enough that you can just link to them. Otherwise, you can provide your own which can still load ours. Yours should live in your User-Me/ directory and only be linked to from ~ and .emacs.d/ directories.

This arrangement allows you to use separate Git repositories to

  • Add to and improve modules under NGender/ and User-Me/
  • Quickly clone this arrangement to new computers and accounts

Installing This Profile

These installation instructions assume

  • a Unix-Like system, e.g. Unix, BSD, Linux, MacOS
  • some familiarity with using a command shell, e.g. Bash
    • the comment character is # (hash)
    • cp old new # copies things
    • your home directory is ~ (tilda)
  • some familiarity with Emacs and/or another editor
  • simple understanding of Emacs-Lisp
    • the comment character is ; (semicolon)
    • Commands are (enclosed in parentheses)
    • Arguments separated by spaces NOT commas
    • Strings in “double quotes”
    • One single quote ‘(quotes the following object)

If you’re using an Apple Macintosh or a Microsoft Windows system you’ll need to install appropriate command-line tools and/or figure out an equivalent to the steps detailed below.

It would be helpful to the community if you were to record any adjustments that you had to make to get this to work in your environment and send us a pull request describing them!

Instructions with example commands:

# 1. You will need a modern Emacs installed, version 25 or later
which emacs # should find your emacs program
emacs --version # should be version 25 or higher
# 2. Find your existing Emacs Customizations
# Typically you'll find them here:
ls -ld ~/.emacs*
ls -l ~/.emacs		# Your Emacs initialization file
ls ~/.emacs.d/		# Your Emacs Home directory
# 3. Clone our repository under your Emacs Home
cd ~/.emacs.d
git clone https://github.com/GregDavidson/EmacsProfile.git
# 4. Rename it and go into it
# Our code assumes it's called NGender
mv EmacsProfile NGender
cd NGender
# 5. Examine .emacs, init.el and the Makefile
less .emacs init.el Makefile
make -n prepare
make -n install
# 6. If the paths are ok, you can just
make install
# and then continue with Step #8
# 7. If any of these files are NOT OK, create your own versions
# You probably want to start with
make prepare
# If you need to change .emacs and/or init.el we suggest you
# create your own versions under User-Me/ and link them in
# to ~ and ~/.emacs.d respectively so you can manage their
# evolution along with your other personal customizations.
# If, e.g. your .emacs extends our .emacs then use
#	(load-file "~/.emacs.d/NGender/.emacs")
# in your .emacs file where appropriate.
# 8. Test your installation
emacs --debug-init
# If no problems, go to Step #10
# Carefully examine any complaints it gives
# 9. Fix any problems and return to Step #8
# 10. Make a file for your personal customizations
emacs ~/.emacs.d/User-Me/init-me.el &
# 11. As you grow this, test after adding each new feature.
# You can pull features from init-examples.el, from your old
# config files (saved under Limbo) or anywhere else.
# 12. Evolve, Share and enjoy your and our extensions!

Post-Installation Possibilities

  • read README.org and other files under NGender/
  • study init-examples.el for ideas
  • submit an issue reporting problems or requested features
  • submit a pull request with your improvements
    • respecially for things you’ve added under NGender/

Although Macintoshes are based on BSD they have a number of deviations from the family. You’ll need to customize these instructions appropriately. Typically you start by installing the Unix-like BSD command-line tools from Apple. Please consider submitting a pull request with instructions for how to do that and anything else you had to do to make things work.

If you’re installing this Emacs Profile under Microsoft Windows and you’re successful, please consider submitting a pull request with instructions for how to do that. Typically you start by installing the Unix-like tools from Microsoft or Cygwin (now part of Red Hat Linux).

Status of this Project

See the separate file README-status.org

Customizing Your New Profile

Any files which are specific to your individual needs and tastes go under a sibling subdirectory which we’ve been calling .emacs.d/User-Me/ in these instructions. If you change this name you’ll need to create your own versions of the .emacs and init.el files.

If you are collaborating with partners on various projects, there may be some Emacs extensions which you may want to share with members of your group. Consider putting those changes in a directory beginning with Group-/NAME/.

Individual vs. (Project) Group vs. Community

As your improvements mature you may find it appropriate to share them with others by creating them as modules under a Group-NAME directory or under the NGender/ directory. If you do the latter, then please send us a pull request so we can share your contributions with the community.

Community Level

Everything under NGender is intended to be helpful for any Emacs User. Where a policy is applied we try to have a variable or function which can alter it coherently. We all collectively contribute to the improvement of these files via Git.

Individual Level

Keep your personal extensions under User-Me/ so you can easily copy them to other computers and accounts. Consider turning it into a Git Repository with something like

cd ~/.emacs.d/User-Me
git init
cp ../NGender/.gitignore .

Project/Group Level

Customizations for Projects and Groups can be created as separate repositories just as shown in the Individual Level above. They can live under ~/.emacs.d alongside NGender and User-Me. Activate them by

  • adding to your init.el or init-me.el file:
    • (ngender-group-subdirectory “Group-YOUR-GROUP-NAME”)
  • adding other customizations for them to init-me.el file

Host the Project/Group repository where other members of the Project or Group can find it. Ask the other members to participate in the improvement of it. Move anything which is more generic than the Project or Group to the NGender repository and submit a pull request!

Individual to Group to Community

Many improvements start out at the Individual Level. After some generalization they (or parts of them) may percolate to the Group Level. Finally they (or parts of them) are generalized enough to become modules under NGender.

Current Challenges

Requiring packages vs. requiring symbols

We need to ensure that we have all requisite packages downloaded. Only after that we need to load them via require on the appropriate symbols. When can we assume that the root of the package name is the same as the require symbol? What’s a convenient (succinct and easy to follow) s-exp syntax to specify the desired packages and the desired requires?

This is a slippery slope to an s-exp syntax which expresses packages, requires, settings and keymaps. If we choose to slide down this slope, we should review previous efforts and consider borrowing from them before rolling our own.

As an example, we could extend the ngender macro along the lines of this example desired enhancements, e.g.

(ngender-load cider
	:package (apple-cider :require granny-smith)
	:require foo
	:set bar baz
	:map "C-M-S-x" drink )

would

  • load module NGender/ngender-cider which would
  • load packages cider AND apple-cider
  • (require 'granny-smith) in addition to the usuals for apple-cider
    • unless we know granny-smith replaces one of the usual requires
  • would load foo in addition to the usuals for cider
    • unless we know foo replaces one of the usual requires for cider
  • would set the configuration variable bar to baz
  • would map Control-Meta-Super x to call function drink

Again, we should look at existing solutions before rolling our own, but we’re implying being able to associate any require, set or map with the top-level context of a module OR with an optional package, which then requires that the module know a lot about what works which then requires that we maintain that knowledge against the package as a moving target which one needs to do anyway with init scripts.

Autoloading

It would be nice where currently various functions are set to autoload packages directly to have them instead autoload our module which then loads the package and configures it the way we like.

Our attempts to do this have so far just resulted in odd error messages claiming that the loaded module did not define the function even though it did.

Emacs Customization System Issues

The Emacs Customization System is the natural mechanism for Emacs Users who are reluctant to use Emacs Lisp to make their changes.

Should we use defcustom for the ngender-* module variables? We’re currently not doing so because of our discomfort with the Emacs Customization System.

Some of our issues with the Emacs Customization System

  • It’s difficult to browse changes vs. defaults
    • it does not play nicely with git
  • It’s difficult to know the purpose and scope of changes
    • no mechanism for tagging changes with
      • which project(s) needed it
      • which system or location needed it
      • the scope, i.e. individual/project,community
    • it doesn’t capture comments or notes

Currently custom-file.el is going into the git repository

  • handy for propagating all such to all one’s accounts
  • yet not everything there is appropriate everywhere
  • and it’s pretty volatile

Ideally customizations settings would be moved into module files which would also contain clear documentation of all of the module’s features and configurable options.

Sensitive Data, e.g. External Accounts and Databases

There are some account-specific parts of various files, e.g. information on external accounts including logins, port numbers, passwords, etc. None of these things belong under the NGender/ directory.

Access information shared by groups would ideally live in modules under an appropriate Group-NAME/ directory. Other parts need to be under the User-Me/ directory. Either these modules or directories have carefully restricted permissions and/or the modules involved should be encrypted, e.g. with GPG which Emacs knows how to decrypt.

A module could be created to stich together the Individual (account/password) and Project (database names, database password?) parts of this sort of senstive data.

Unless and until a nice module is available in the NGender/ directory to manage all of these things, we recommend that users simply keep any sensitive modules in their User-Me/ directory and protect them with readability restrictions and/or encryption.

Automating Byte-Recompilation

How do we ensure that byte-recompilation happens automatically?

Consider adding code to .emacs to call byte-recompile-directory on NGender/ with suitable options and similar code in init.el for the User-Me/ directory, etc.

NGendering use of Emacs-Server

Let’s add an ngender-emacs-server.el file which does byte-recompiles and any other slow things and then starts the Emacs Server.

Consider using systemd or login scripts to start and maintain an Emacs Server at all times.

Rationale for the Curious

Emacs Thrives on Extensibility & Configurability

An early Emacs Manual described Emacs as “A Beautiful Flower that Smells Bad”. On the Beautiful side, Emacs is

  • Elegant - Great Power with Simplicity
  • Open - Easy to Understand and to Adapt to your needs

The bad “Code Smell” comes from insufficient structure

  • Buffers are mutable arrays with unstable integer indices
  • Emacs-Lisp inherited some of the worst features of early lisps
    • no module system, everything mutable, dynamic binding

To take advantage of Emacs’ power one must add extensive customizations and load many packages most of which also require significant customizations.

Some Worthy Approaches

The Emacs Package System

Although Emacs-Lisp doesn’t have modules, it’s possible to add structure providing some of the features of proper modules. One of these approaches has evolved into the current Emacs Package System. A package is a chunk of Emacs-Lisp code with metadata (name, description, date, version, dependencies, etc.) which can be stored in public Package Archives or distributed as tarballs. Emacs now comes with a tool for browsing available packages and installing or removing them. Limitations include

  • The user must write code listing one or more archives
  • Most packages require additional code to configure them well
  • Many packages are not available from public archives
  • It’s not always clear which package version is appropriate
  • Package dependencies can be difficult to resolve
  • Packages can interfere with one another - they’re not true modules

The Emacs Customization System

Emacs comes with a Customization System which allows the user to browse Settings and Options from structured Emacs Custom-Mode Buffers. Limitations include

  • It’s often difficult to find the right Setting or Option
  • Customizations may interact badly with one another and with other code
  • Customizations are stored without any context as to where they’re applicable

An Emacs Prelude

You can put all of your extensions, including lists of Package Archives, the Packages one wants to download from them and all of the configuration options in one well-documented, well structured file, generally referred to as a Prelude. Others can copy that Prelude, delete what they don’t want and change what they want to change. This works well as long as the user is a good Emacs-Lisp hacker, not only knowing the language well but also being well steeped in the way Emacs does things. Some examples:

These are all a good source of ideas for our configurations!

More Advanced Approaches

You can impose a layered architecture to Emacs Extensions. A good example of this is

Alas, the packages spacemacs uses don’t always cooperate well with the layering system.

You can write a new, more ambitious Package Manager such as

Configuration Files

When emacs starts up Emacs will look for a configuration file in your Home Directory as specified by the environment variable HOME. Emacs understands that any path beginning with tilde slash ~/ starts from your Home Directory.

Emacs will take the first file it finds in the list

  1. ~/.emacs
  2. ~/.emacs.d/init.el

and load it, i.e. Emacs will treat the contents of that file as Emacs-Lisp code (so it better be that) and Emacs will execute that code.

Therefore, if you have both files, Emacs will, by default, ignore your ~/.emacs.d/ directory and everything in it!

It would seem that it’s simpler to just not have a ~/.emacs file but unfortunately that will interfere with the Emacs Customization System.

Thus, we use a .emacs file to get everything started.