This is a Beginners Guide to writing CAVI-ART's CLIR files using Emacs, for people who has never used Emacs.
Emacs is a editor very leaned to using the keyboard as the primary input method. Thus, most commands on Emacs can be entered through the keyboard, although most can also be entered through the toolbar with the mouse.
Emacs 24.4 or Emacs 25.
Most commands on emacs take more than one keystroke. So, for
example, save is Ctrl.+S in most editors. In Emacs, it's
Ctrl.+x, Ctrl.+s.
In Emacs literature, you'll find that key chords like that are
abbreviated as C-x C-s. C- means Control+following key. The
space means that the two combinations must be pressed, one after the
other (the space bar is noted SPC to avoid confusion).
M-x is the same but with the Meta key. The Meta key depends on your
X11 implementation, but on Linux it is usually the Alt key. In
keyboard without a Meta key you can press ESC to achieve the same
effect. Thus, M-x and ESC x will have the same effect.
M-x is the main key binding of Emacs. It takes you to the
minibuffer, a magical place where you can send commands to the
editor.
Emacs (24+) comes with a set of utilities called package.el, which
implement a sort of package management system for Emacs, in order to
download stuff to better enhance and improve the Emacs editor.
There is a free software repository configured by default called GNU ELPA, which contains software that is accepted by GNU to be part of Emacs.
We will install paredit-mode, a mode to edit files with balanced parentheses.
For that, we'll invoke the package manager list, with M-x package-list-packages RET (that is, M-x, followed by those letters
--you can autocomplete with TAB--, and then the Return key to send the
command).
That should download the latest indices for ELPA. You can search in
the list with C-s paredit RET. When you find the one, go to it and
press install with the mouse (or with the keyboard, select it to be
installed with i and then execute the installation with x).
If that was already too much Emacs for today, you can always exit the
editor with C-x C-c. If that does not happen (because maybe Emacs is
waiting for your input on something else), you can tell Emacs to abort
everything it is asking you with C-g C-g C-g (one should be enough,
three is the most number of times you will need it).
By default, Emacs does not know anything about a .clir extension.
Thus, it will open the file in fundamental-mode, which is a rather
rudamentary mode for editing plain text.
We want to use lisp-mode in order to gain the indentation knowledge
of Emacs for indenting parentesized code.
Thus, we enable lisp-mode by typing M-x lisp-mode RET.
Emacs knows about something called file-local variables, and you can instruct Emacs to open a file with a certain mode from the file itself.
So, you can add a comment to your file with the following content:
;; Local Variables:
;; mode: lisp
;; End:
You can also instruct Emacs to add this for you (when you are already
in lisp-mode) by typing M-x add-file-local-variable RET mode RET lisp-mode RET.
You also have to enable paredit-mode by typing M-x paredit-mode RET.
Once you have paredit-mode enabled you should see "Paredit" on the bottom of the screen (that is called the modeline). If you type that again, it will disappear. If you ever have a disbalanced parenthesis, paredit should not be enabled in order for you to fix the typo.
Paredit automatically balances parenthesis and double quotes on lisp modes. You can never insert accidentally a closing parenthesis without a corresponding opening one (and when opening a parenthesis, paredit closes it already for you).
You can navigate to after the parenthesis by typing it, as you would naturally if paredit wasn't there, but it will take care for you not to add additional parenthesis.
It takes a moment to get used to it.
Try for example in an empty buffer to type the following:
(Well, first, type in M-x lisp-mode RET M-x paredit-mode RET)
( h e l l o , SPC w o r l d ). You will find out that Emacs
highlights the closing parenthesis but the cursor point just goes over
it without typing anything, as if you pressed the right arrow on the
keyboard. That is the behaviour you should expect.
You can paste the following in your ~/.emacs to instruct Emacs to
always load paredit-mode when entering lisp-mode.
(autoload 'enable-paredit-mode "paredit" "Turn on pseudo-structural editing of Lisp code." t)
(add-hook 'emacs-lisp-mode-hook #'enable-paredit-mode)
(add-hook 'lisp-mode-hook #'enable-paredit-mode)In Lisp-mode Emacs indents nodes automatically depending on how nested they are on the parentheses.
The default modes are ok enough, but for CLIR, let expressions do
not hold the same indentation pattern as in Common Lisp, and thus you
should paste the following in your ~/.emacs file:
(put 'letfun 'lisp-indent-function
'((&whole 4 &rest (&whole 1 &lambda 4 &body)) &body))
;; Default for LISP (uncomment and eval to undo the effect)
;; (put 'let 'lisp-indent-function '((&whole 4 &rest (&whole 1 1 2)) &body))
(put 'asserts 'lisp-indent-function '(4 &body))
(put 'let 'lisp-indent-function
'((&whole 4 &rest (&whole 1 &lambda 2 &body)) 6 &body))
(put 'define 'common-lisp-indent-function
'(4 &lambda &lambda &body))
When you want to re-indent a CLIR file (or any file in Emacs), press
M-q. The text will reflow to its intended place.
Also, pressing TAB will indent the current line to where it is expected, according to how the previous line (but if the previous line is not correctly-indented it will not escalate to fix that).