NGender Emacs Configuration Directory
This Directory Tree is a Git Repository.
- 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
- Radical Productivity Tools Users Group
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
~/.emacs.d/ – these locations can be changed if
another arrangement is more convenient.
- links, loads or forks
- your Emacs Customization Directory
- links, loads or forks
- extension modules shared with Emacs Community
- establishes paths & gets things started
- loads user module
- core module loaded by
- module providing extension NAME
- individual extensions
- automatically loaded by
- Emacs Customization System settings
- modules shared with group/project Group-Name
- snippets to copy/paste into
- script to help set up the above links
In most cases our provided
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
This arrangement allows you to use separate Git repositories to
- Add to and improve modules under
- 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
- cp old new
# copies things
- your home directory is
- the comment character is
- some familiarity with Emacs and/or another editor
- simple understanding of Emacs-Lisp
- the comment character is
- Commands are
(enclosed in parentheses)
- Arguments separated by spaces NOT commas
- Strings in “double quotes”
- One single quote ‘(quotes the following object)
- the comment character is
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!
README.organd other files under NGender/
- 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
.emacs.d/User-Me/ in these instructions. If you
change this name you’ll need to create your own versions of
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
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.
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.
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 .
Customizations for Projects and Groups can be created as
separate repositories just as shown in the Individual Level
above. They can live under
User-Me. Activate them by
- adding to your
- (ngender-group-subdirectory “Group-YOUR-GROUP-NAME”)
- adding other customizations for them to
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.
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
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 )
- load module
- 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 xto 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.
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
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
- no mechanism for tagging changes with
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
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
User-Me/ directory and protect them with readability
restrictions and/or encryption.
How do we ensure that byte-recompilation happens automatically?
Consider adding code to
.emacs to call
NGender/ with suitable
options and similar code in
init.el for the
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.
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
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
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
~/.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.