Installing the Emacs Ado-mode

Basic Installation Instructions

Emacs is getting more user-friendly all the time (especially Aquamacs Emacs on the Mac), but it still has some unixy ways of doing things which allow great freedom at the price of obscure installation instructions.

1. Download the current zip file from http://stata.com/users/brising/ado-mode-1.10.1.2.zip, and unzip it.
2. Put the ado-mode-1.x.x.x folder in a place where Emacs will find it.
• If you are installing this for yourself only, put the ado-mode folder in the place you keep your other emacs customizations. If you have no customizations, make an emacs folder in a useful place, move the ado-mode folder into it, and remember where you put the ado-mode folder. (For the instructions, I'll assume you put the folder in /Universal/Custom/emacs/ado-mode.)
• Add the following two lines to your initialization file:
  (setq load-path (cons "/Universal/Custom/emacs/ado-mode/lisp" load-path))
(require 'ado-mode)
  (The initialization file used to be called the .emacs file, but what is named on your system depends on the type of Emacs you are running. If you are unfamiliar with such files, open up Emacs and use C-h i to bring up info, then type m em RET m init file (emacese for menu emacs, and then menu init file) to read the docs on initialization files.)
3. This ado-mode is very customizable—it is made to automatically store new ado-files in a special directory designated by you, put your name and affiliation at the end of any help files you write, and the like. It also needs to be able to find its templates for do-files, ado-files and help files. You can set all these from within Emacs by using M-x customize-group RET ado, and pay close attention to the group called Ado Essentials.

If you would rather work with customization files directly, there are three files in the ado-mode folder called site_scrap.el, personal_scrap.el, and hacker_scrap.el It might be worth peeking at these so that you can see what is set.

site_scrap.el
contains the code needed for ado-mode to run, but nothing for individual usage.
personal_scrap.el
contains a very few of the variables you might want to set—you will still want to work inside the built-in customizations
hacker_scrap.el
contains code needed in your customization file if you ever what to edit ado-mode.el (the source code) and have it compile properly.

Changing appearance

You will likely want to change the default colors for the font highlighting. Here is a screen-shot of the highlighting I use, and which I find quite readable:

The font-locking can be changed either by customizing the ado-mode faces directly using M-x customize-group ado-font-lock, or by changing the font-lock faces which are inherited by the ado-mode via M-x customize-group font-lock-highlighting-faces. I prefer the latter. In any case, here are the actual colors from the above screen-shot:

• comment: firebrick
• string: magenta
• harmful: red
• harmless: blue
• subcommands: DeepSkyBlue2
• macros: green3
• functions: OrangeRed2
• constants: purple2
• obsolete: background -- grey80, foreground -- red bold

Note that specifiying the font is system specific. I use the apple-dejavu sans mono font, because I like it. Others like other fonts. You should set the font from within emacs by using M-x customize, and then clicking the Faces, Basic Faces, and then click the show button next to Default face. This will avoid all the platform specific methods for referring to fonts.

Troubleshooting

If you run into trouble, because you keep getting Symbol's function definition is void: line-number-at-pos errors, put the following into your .emacs file: (require 'ado-hacks). This should cause the proper function get loaded without having it interfere with future updates. (This problem seems to happen for emacs 21.something and earlier.)

If you have any trouble with the installation instructions, drop me a line so that I can fix them.

If you'd like to be notified when the package gets updated, click here to send an email to me. Please don't change the subject. Privacy? You bet. When the advertising trolls come around, I'll give them everybody's name except yours. Seriously: I won't use it for anything but notifications of new ado modes.