Index Emagician Base Install Meta Interface Programming Text Org Lamp Journal Snippets jonnay.netFork on Github


Table of Contents

1 And technomancy said

Emacs outshines all other editing software in approximately the same way that the noonday sun does the stars. It is not just bigger and brighter; it simply makes everything else vanish.

– Neal Stephenson, "In the Beginning was the Command Line"

Let there be light

(and it was good)

1.1 And eschulte described the light so it shall be understood and organized.

(and it was awesome)

1.1.1 And thus did Jonnay expand upon for himself. If I have seen further, it is by standing on the shoulders of giants.

While this quote is attributed to Sir Issac Newton, it was initially said by

"Bernard of Chartres used to compare us to dwarfs perched on the shoulders of giants. He pointed out that we see more and farther than our predecessors, not because we have keener vision or greater height, but because we are lifted up and borne aloft on their gigantic stature."

Metalogicon: John of Salisbury 1159


2 Running Code blocks

Installing this thing should be as easy as reading through the relevant sections to get used to how the kit works, and then running the code blocks inside. Running a code-block is as easy as typing C-c C-c inside the relevant code block, and answering "yes" if it asks you whether or not you want to run said code block.

If you can't run the shell blocks, try executing this:

(require 'ob-sh)

3 Installation

You need emacs 24. I am sure you can get it and install it, if you haven't already.

3.1 Initialize Submodules

git submodule init 
git submodule update

3.2 Who the fuck are you?

Who you are and the set of emacs configurations that you will want, will probably relatively remain consistent across machines, user accounts, etc. At the same time, will need some differentiation amongst emacs starter kits. This is your "true name". Make it quazi-original. If you are boring, a machine-readable fullname will do.

We'll use the true name in the naming of your branch, loading your customizations, etc.

Replace "jonnay" with your name!

(defvar emagician/true-name "jonnay" 
  "  -|-+-|-  The Magician using these tools upon this altar.  -|-+-|-  ")

3.3 Make the init files

Making the init file is a two stage process.

3.3.1 Step One: Where are we?

The first is to tell the Emagician Starter kit which directory is in. Run the next code block, and watch how it writes a new one below. You don't need to run the second one.

If there already is code below the "results:" block, then just delete it.

(concat "#+name: set-this-dir-as-var\n"
        "#+begin_src emacs-lisp\n"
        "(defvar emagician/dir\n"
        "        \"" (file-name-directory (buffer-file-name)) "\"\n" ;BAM! 
        "        \"Automagically generated variable where the emagicians kit is located\")\n"
        "#+end_" "src\n")

3.3.2 Step Two: Making it go.

Then this next code block creates the init.el file by running the next code block. What this does is it takes the embedded elisp in this file (especially the parts where it determines how you are, and were the emagicians starer kit is) and weaves it together into a file called init.el.


if you are interested, you can have a look at it:

(pop-to-buffer (find-file-other-window "./init.el"))

3.4 Branching for great justice

This next code block sets up a git branch. Change the branch name to your own name. hit C-C C-C on the next block for branchy git goodness.

This also adds an entry to the .gitignore file that contains an entry to your private customization file. More on this later

(shell-command (concat "git branch " emagician/true-name))
(shell-command (concat "git checkout " emagician/true-name))
(shell-command (concat "echo \"" emagician/true-name "\" >> .gitignore"))

I shouldn't have to tell you why this is a good idea.

3.5 Customizing and Configuration

In the original starter kit, there were 2 different kinds of custom files. Emacs Magicians uses 4.

The only file you need to create is your personal one. All others are optional.

3.5.1 Your personal file

This next command is an invokation. Even if you are going to use the Emagician starter kit as is, you need to run the next code block. This defines a function that is used to create custom files for you.

The first one it creates is based on the identity you specified above. After that there are other customizations based on your login name, machine name and OS type.

But you need to run this one first.

There is also the possibility of you needing to store passwords and such. The default is to do so in a directory called in your personal directory that is already in your .gitignore file.

Another option is to store them in a file.

(defun emagician/invoke-custom-file (name) 
  "Create the customiztaion file, and load it up in emacs.
This function is actually created when the emagician identifies themself"
  (let ((filename (concat "./" name)))
    (find-file-other-window (concat name ".org"))

(emagician/invoke-custom-file emagician/true-name)

3.5.2 Your System-Type file

If you end up using differnet OS's, you may want to have this set up. This would handle per-os level customization. We use the "system-type" variable for determining which system type to use. We do munge it a little by replacing any / with a -.

                       (replace-regexp-in-string "/" 
                                                 (symbol-name system-type)))

3.5.3 Your machine file(s)

Different machines are not nessicarily on differnet OS's. Different OS's aren't nessicarily different machines. Now you can get more granular if need be.

(emagician/invoke-custom-file system-name)

3.5.4 Your account file

Then again, maybe you need to separate customizations out by user account. Why not?

(emagician/invoke-custom-file (user-login-name))

3.6 The Testening

To properly test your magicians kit, you should build the tester, by running the elisp below. If you don't know Emacs Lisp, you need to learn to become a magician. If you know emacs lisp, but don't know org-babel, you are about to learn. Be prepared for some high-lamp magick. (No, not Linux Apache MySQL PHP.)

Run the next code block. It will emit a new code block below that will properly run the emacs starter kit as a shell command. You can then run this new code block.

Note that you will need to quit the new instance of emacs, so control can return to this instance of emacs.

#+source make-a-tha-test-script

(concat "#+begin_src sh :results silent\n"
        "  # run this code block to test your emacs starter kit\n"
        "  "invocation-directory invocation-name " --no-init-file --load="
        (file-name-directory (buffer-file-name))
        " &"
        "#+end" "_src" ; don't want the parser to prematurely end here

3.6.1 No org-babel-execute function for sh?

If you get the message org-babel-execute-src-block: No org-babel-execute function for sh! then you need to enable shell mode for babel. Do that by running this code block:

(require 'ob-sh)

3.6.2 what you should see when it works

If it is working properly, the *Messages* buffer of the new emacs instance should read something like:

Loading /home/jonny/emagicians-starter-kit/Emagician.el (source)...done
loaded /home/jonny/emagicians-starter-kit/Emagician.el

3.6.3 A note about some magic… Wait, what just happened there?

Ok, check it out, the source block just spits out a string, that gets inserted verbatim into the org-mode buffer. I don't have to worry about where you put the starter kit it just builds itself a shell script. It's kinda like macros, but cross-lingual macros.

In fact, when the starter kit builds itself, it will use this cross-lingual aspect to figure out where it is.

3.7 Taking the plunge

One you run the next source block, you will have fully installed the Emagicians starter kit.

Since we're going to over-write your .emacs.d/init file, we'll back it up first.

NOW=$(date +"%Y-%m-%d_%H-%M-%S")
mv -v ~/.emacs.d/init.el $FILE
cp -v ./init.el ~/.emacs.d/

4 The actual Init file

This is the init file that is tangled by the org-babel-tagle command, and then copied over to where you need it to be. You don't really need to read it… but you can if you like!

;;; init.el --- Where all the magic begins
;; Part of the Emagicians Starter Kit. 
;; This is the first thing to get loaded.
;; Note, this file is automagickally summoned from

(defvar emagician/true-name "jonnay" 
  "  -|-+-|-  The Magician using these tools upon this altar.  -|-+-|-  ")
(defvar emagician/dir
        "Automagically generated variable where the emagicians kit is located")
;; This sucks, but we need org mode properly running
(setq package-user-dir (concat emagician/dir "elpa"))
(require 'org)
(require 'org-install)
(require 'ob-tangle)
(message "Loaded with org version: %s" (org-version))
(org-babel-load-file (expand-file-name "" emagician/dir))

5 That's All folks!

Emacs is the ground. We run around and act silly on top of it, and when we die, may our remnants grace its ongoing incrementation. – Thien-Thi Nguyen, comp.emacs


Author: Jonathan Arkell

Created: 2018-05-18 Fri 10:31