My Emacs Setup Suite

A.J.Hurst

Version 1.3.2

Table of Contents

1. Introduction

This is the .emacs file as customized for John Hurst.

The .emacs file, which should reside in your home directory, allows you to customize the behavior of Emacs. In general, changes to your .emacs file will not take effect until the next time you start up Emacs. You can load it explicitly with `M-x load-file RET ~/.emacs RET'.

There is a great deal of documentation on customization in the Emacs manual. You can read this manual with the online Info browser: type `C-h i' or select "Emacs Info" from the "Help" menu.

2. The .emacs file

A major issue to resolve at the start is whether we are setting up to run Xemacs or GNU Emacs. The basic approach I am settling upon is to not make a top level branch, but to put switches in whatever specific customization is occuring. This may contradict some of the statements and code below, since the process of conversion is not yet complete.

This is revisited (20030120:094835) because under mac OSX 10.2.3 running Apple X11 beta, emacs does not work under X11, but does as an Aqua application. XEmacs on the other hand works as X11, but not Aqua. So I need both once again.

2.1 Emacs or XEmacs?

Since there is just the one .emacs file, we have to parameterize things with respect to which system of emacs we are running, Emacs or XEmacs. While in earlier versions I tened to switch between them, the recent GNU Emacs versions (20.3 on) have provided all the facilities I need, so I'm sticking with that for the moment. We can pick which emacs we are in from the variable emacs-version, and this is used to set one of the variables running-xemacs and running-emacs to true (obviously not both!). These variables are subsequently used wherever there needs to be a distinction made in the setup or customization.

2.2 UTF-8

I know very little about what UTF-8 means to emacs, so I just copied this from a web page. I think it works! Note that I had to move it up to the front of the file - again I don't know why this has to be.

2.3 Setting the load path

This is akin to setting the PATH variable at the shell level. The emacs variable load-path determines where any load files are searched. The load-path is set to different things depending upon whether we are xemacs or not.

These are the default ones: both emacs and xemacs use this. If a file is defined in both the emacs and xemacs subdirectories, the latter will be found first and override the emacs version.

The XEmacs only ones.

Finally, include a nil at the start of the list. This indicates we want to search the current directory first.

2.4 Basic Customization

Enable the commands narrow-to-region (C-x n n) and eval-expression (M-ESC, or ESC ESC). Both are useful commands, but they can be confusing for a new user, so they can be commented out if necessary.

Make the sequence C-x w execute the what-line command, which prints the current line number in the echo area. I use kp-insert t l for this function, so it is commented out.

2.5 Time zone customization

Xemacs has a bug that when using pre-built binaries, it uses the time zone under which it was built, not the local time zone. (See XEmacs FAQ, http://www.xemacs.org/faq/xemacs-installation.html\#Q2_1_19)

It also does not respond correctly to the ``Australia/Victoria'' rule. Why, I don't know. You have to change manually the GMT-10 to GMT-11 when it is daylight savings time because of this.

2.6 Face and Colour customization

I like to have pretty background colours and stuff. Here's where we set all that.

2.7 Load Macro Collections

Now get various collections of macros.

I was going to add a link to pull up some handy definitions of PUBLIC identifiers through sgml-catalog-links, but it all got a bit too hard for me thinking how to do it. Perhaps another time.

Identify where terminal parameters are located. Commented out, since we don't have differing terminals. (I think.)

Control use of version numbers for backup files. t means make numeric backup versions unconditionally. nil means make them for files that have some already. `never' means do not make them.

Handle various windowing methods.

This used to perform a call on getenv to collect three environment variables set by my bash_profile. Since moving to xdm, which doesn't run

2.8 Setup Hooks

Set my hook and other variables

Note the subtle difference between Emacs and XEmacs in setting the background colour

I like to have some additional features provided in xml-mode.

Make a server hook to create new frames when emacsclient called.

Set up autoloads and automodes. These are modes that are triggered automatically by file suffixes. The modes themselves are autoloaded as necessary.

Define various global key bindings and other settings.

1. C-c f fills a paragraph (like insert t f)
2. Change C-n to my version of next line.
3. Set the tabs to be four spaces apart, not 8.
4. indent-tabs-mode is turned off. If this is true, indentation will use tab characters. I prefer spaces.

Finally, setup keyboard. The following code determines the style of keyboard. It would be nice if there some way of determining the keyboard type. I can't think of any way of extracting this from environment variables or the like.

(version 1.1.7) Now I have the server and host variables, we can test for the keyboard type. We do it like so:

2.9 Multiple Frames

I find it handy when Emacs is fired up to make a number of frames immediately. The frame parameters of this initial frame set are adjusted to make the frames appear on the desktop below the default one.

Rev up a <number of additional initial frames 2.30>. I do this because I have not yet worked out how to send a signal from the external environment into emacs to cause it to spawn a new window. Hence I just make some spares, and drag around the desktop as necessary.

The spare frames are made iconic initially, but it seems that the positioning parameters don't work in this case. However, I have left them in, to indicate where I want the frames to appear! (This would seem to be a bug in something?) (v1.2.5) Problem solved! The addition of the user-position parameter and setting it non-nil fixed this. See the ELisp manual page 528.

2.10 XEmacs customization

Change the values of some variables. (t means true; nil means false.) Use the "Describe Variable..." C-h v keystrokes to find out what these variables mean.

When running ispell, consider all 1-3 character words as correct.

Change the way the buffer name is displayed in the modeline. The variable for this is called modeline-buffer-identification but was called mode-line-buffer-identification in older XEmacsen.

Code which applies only when running emacs under X goes here. (We check whether the function device-type exists before using it. In versions before 19.12, there was no such function. If it doesn't exist, we simply assume we're running under X -- versions before 19.12 only supported X.)

Uncomment this to enable ``sticky modifier keys'' in 19.13 and up. With sticky modifier keys enabled, you can press and release a modifier key before pressing the key to be modified, like how the ESC key works always. If you hold the modifier key down, however, you still get the standard behavior. I personally think this is the best thing since sliced bread (and a *major* win when it comes to reducing Emacs pinky), but it's disorienting at first so I'm not enabling it here by default.

This changes the variable which controls the text that goes in the top window title bar. (However, it is not changed unless it currently has the default value, to avoid interfering with a -wn command line argument I may have started emacs with.)

If we're running on display 0, load some nifty sounds that will replace the default beep. But if we're running on a display other than 0, which probably means my NCD X terminal, which can't play digitized sounds, do two things: reduce the beep volume a bit, and change the pitch of the sound that is made for "no completions."

(Note that sampled sounds only work if XEmacs was compiled with sound support, and we're running on the console of a Sparc, HP, or SGI machine, or on a machine which has a NetAudio server; otherwise, you just get the standard beep.)

(Note further that changing the pitch and duration of the standard beep only works with some X servers; many servers completely ignore those parameters.)

Define a variable to indicate whether we're running XEmacs/Lucid Emacs. (You do not have to defvar a global variable before using it -- you can just call `setq' directly like we do for `emacs-major-version' below. It's clearer this way, though.)

Load the auto-save.el package, which lets you put all of your autosave files in one place, instead of scattering them around the file system. This is xemacs specific.

Now that we have auto-save-timeout, we crank this up for a better interactive response.

We load this afterwards because it checks to make sure the auto-save-directory exists (creating it if not) when it's loaded.

2.11 Emacs customization

The first thing to set is transient-mark-mode, which makes the region get highlighted regardless of whether selected by mouse drag of point and mark positioning.

I run an emacs client for handling exmh mail editing. Here we start that emacsclient.

2.12 Various Application Customizations

2.12.1 The PSGML SGML editing mode

This is the READ ME file for psgml.el version 1.0

PSGML is a major mode for editing SGML documents. It works with GNU Emacs 19.19 and later or with XEmacs 19.13.

This distribution should contain the following source files:

psgml.el
psgml.texi
psgml-other.el
psgml-lucid.el
psgml-edit.el
psgml-parse.el
psgml-dtd.el
psgml-info.el
psgml-charent.el
psgml-api.texi	-- internals documentation
psgml-api.el	-- Extra functions for the API
iso88591.map
Makefile.in
        

sh configure
make

make install

2.12.1.1 New in version 1.0

• Support for general entities
• Support for short reference
• Support for catalog files
• New mechanism for caching parsed DTD
• Includes commands to list various aspects of the DTD

• Command: `sgml-expand-entity-reference' Insert the text of the entity referenced at point.
• Command: `sgml-expand-all-shortrefs' Expand all short references in the buffer. Short references to text entities are expanded to the replacement text of the entity, other short references are expanded into general entity references. If argument, `to-entity', is non-nil, or if called interactive with numeric prefix argument, all short references are replaced by generally entity references.
• Command: `sgml-normalize' Changed to expand short references also. Normalize buffer by filling in omitted tags and expanding empty tags. Argument `to-entity' controls how short references are expanded as with `sgml-expand-all-shortrefs'.

• If the entity has a system identifier, the entity manager will first try and call the functions on `sgml-sysid-resolve-functions' with the system identifier as argument, and if any function returns non-nil assume that the function has handled the entity.
• If the entity has a system identifier and `sgml-system-identifiers-are-preferred' is non-nil, the system identifier will be used as a file name relative to the file containing the entity declaration.
• Next the entity manager will try the catalog, and
• if not found there use the `sgml-public-map'.
• Finally if the entity has not been found and it has a system identifier, this will be used as a file name. Note: `sgml-system-path' is no longer used for entity lookup. The catalog files searched is given by the variable `sgml-local-catalogs' and `sgml-catalog-files'. The `sgml-catalog-files' variable is initialized from the environment variable `SGML_CATALOG_FILES' (should be a colon separated list of files). The `sgml-local-catalogs' variable is assumed to be set in a files local variables. File names for external entities (e.g system identifiers) are relative to the directory containing the file declaring the entity. The `sgml-public-map' is initialized from the environment variable `SGML_PATH'. `sgml-system-path' defaults to nil. Supports most of sgmls substitutions for sgml-public-map. Supported: %%, %N, %P, %S, %Y, %C, %L, %O, %T, %V. Unsupported: %D, %X, %A, %E, %I, %R, %U. Note: that %D is and alias for %C in PSGML (historical accident).

• `sgml-recompile-out-of-date-cdtd'
• New options for insert-element: `sgml-insert-missing-element-comment' and hfil break `sgml-insert-end-tag-on-new-line'.
• `sgml-validate-files' and slight change of `sgml-validate-command' The variable `sgml-validate-command' can now be a list of strings. The strings can contain %-sequences that will be expanded: %b to buffer file name, %s to SGML Declaration file, either the value of sgml-declaration variable or SGML Declaration file for parent document or DOCTYPE file or SGMLDECL from catalog. %d value of `sgml-doctype'.
• `sgml-set-face' Now automatically sets faces for all visible text, with a delay of 1s.
• `sgml-exposed-tags' The list of tag names that remain visible, despite `M-x sgml-hide-tags'. Each name is a lowercase string, and start-tags and end-tags must be listed individually.
• `sgml-auto-activate-dtd' PSGML was behaving inconsistent when a new file was loaded. If the variable `sgml-set-face' was true the DTD would automatically be activated (loaded or parsed), but only if psgml-parse already loaded. Rather than let `sgml-set-face' decide if the DTD is activated, there is now a distinct option for this. This option works even the first time. If non-nil, loading a sgml-file will automatically try to activate its DTD. Activation means either to parse the document type declaration or to load a previously saved parsed DTD. The name of the activated DTD will be shown in the mode line.

• Tracing catalog lookup To help debug entity lookup there is a new option `sgml-trace-entity-lookup'. If this option is t messages will be logged in *SGML LOG* buffer when external entities are looked up. These messages shows entity, catalogs searched, and entry type in catalog where entity was found.
• Translating between characters and entity references Set the variable `sgml-display-char-list-filename' to a file that contains mappings between all characters present in the presentation character set, and their "standard replacement text" names, e.g. "(a umlaut)" -> "[aring ]", e.t.c. The default value for this variable is `iso88591.map'. Use the functions (also in the Modify menu) `sgml-charent-to-display-char' and `sgml-display-char-to-charent' to translate between entities and characters.
• Handling of missing DOCTYPE If the document prolog does not contain a document type declaration, PSGML will try to supply one on the form `&lt;!DOCTYPE DocTypeName SYSTEM>' If the variable `sgml-default-doctype-name' is defined this will be used for the document type name, otherwise the GI of the first start tag will be used. I.e., if the document starts with `&lt;book>', a document type declaration `&lt;!DOCTYPE book SYSTEM>' will be assumed.
• Handling of tags for undefined elements
  • Start-tags for undefined elements will either be ignored, if `sgml-ignore-undefined-elements' is `t', or assumed to be acceptable in the current element and defined with `O O ANY'.
  • An end-tag for an element that is not currently open will be ignored.
• Cleaned up Markup menu The removed entries can be added with sgml-custom-markup:

  (setq sgml-custom-markup
      '(("<!entity ... >" "<!entity \r>\n")
        ("<!attlist ... >" "<!attlist \r>\n")
        ("<!element ... >" "<!element \r>\n")
        ("<!doctype ...>" "<!doctype \r -- public or system --\n[\n]>\n")
        ("Local variables comment" "<!--\nLocal variables:\n\rEnd:\n-->\n")
        ("Comment" "<!-- \r -->\n") ))
  

• New commands Thanks to David Megginson the custom menus are now reachable from the keyboard: `C-c C-u C-d' (`sgml-custom-dtd') `C-c C-u C-m' (`sgml-custom-markup')

• New hooks
• `sgml-close-element-hook' The hook run by `sgml-close-element'. These functions are invoked with `sgml-current-tree' bound to the element just parsed.
• `sgml-new-attribute-list-function' This hook is run when a new element is inserted to construct the attribute specification list. The default function prompts for the required attributes.
• `sgml-doctype-parsed-hook' This hook is called after the doctype has been parsed. It can be used to load any additional information into the DTD structure. Example: add description to element types

  (defun set-help-info ()
    (let ((help '(("para" "A Paragraph")
  		("q"    "A Quotation")
  		("date" "A Date")))
  	(dtd (sgml-pstate-dtd sgml-buffer-parse-state)))
      (loop for h in help do
  	  (setf (sgml-eltype-appdata (sgml-lookup-eltype (first h) dtd)
  				     'help-string)
  		(second h)))))
  (add-hook 'sgml-doctype-parsed-hook 'set-help-info)
  (defun sgml-help-for-element ()
    (interactive)
    (let* ((el (sgml-find-element-of (point)))
  	 (help (sgml-element-appdata el 'help-string)))
      (and help
  	 (message "%s" help))))
  

• sgml-sysid-resolve-functions This variable should contain a list of functions. Each function should take one argument, the system identifier of an entity. If the function can handle that identifier, it should insert the text of the entity into the current buffer at point and return t. If the system identifier is not handled the function should return nil. Example use: Support URLs as system identifiers

  (defun sgml-url-sysid (sysid)
    (cond ((string-match "^\\([a-z]+\\):" sysid) ; looks like url
  	 (require 'url)
  	 (set-buffer (prog1 (current-buffer)
  		       (url-retrieve sysid)))
  	 (insert-buffer url-working-buffer)
  	 t)))
  (add-hook 'sgml-sysid-resolve-functions 'sgml-url-sysid)
  

• New file psgml-api.el This file contain API-functions that are not used by other parts of psgml. Use `(require 'psgml-api)' to use the API functions (psgml-api includes the rest of the psgml files).

2.12.2 XML Support for PSGML

I'm still experimenting with these declarations (v1.1.12), but these are here to control the validation process, and make it use XML4C2 instead of nsgmls.

------------------------------------------------------------------------
  Variable			Value	Explanation
------------------------------------------------------------------------
  sgml-omittag			nil	(OMITTAG forbidden by XML.)
  sgml-shorttag			nil	(SHORTTAG forbidden by XML.)
  sgml-minimize-attributes	nil	(Forbidden by XML.)
  sgml-always-quote-attributes	t	(Required by XML.)
  sgml-namecase-general		nil	(Required by XML.)
------------------------------------------------------------------------

(The last one is a new variable that is also available in sgml-mode, corresponding to NAMECASE GENERAL NO in an SGML declaration.)

Furthermore, the parser will add or alter some of the delimiters to conform to XML.

2.12.3 Note on System Identifiers

XML emphasises system identifiers rather than public identifiers, so document exchange can be tricky. This new version of PSGML makes better use of the `sgml-system-path' variable to allow you to make files available from any directory on your system. For example, if you put the file `spec.dtd' in the directory `/home/david/xml/dtds', and then include in your .emacs file

you can simply use

<!DOCTYPE spec SYSTEM "spec.dtd">

in your XML document, and PSGML will find spec.dtd even if it is not actually in the current directory.

Nsgmlsv already uses a similar mechanism with its SGML_SEARCH_PATH environment variable; in fact, if you have SGML_SEARCH_PATH set, PSGML will use it automatically to set the initial value of `sgml-system-path'.

• names and keywords are case sensitive
• understands /> TAGC for empty elements, and inserts it by default
• requires ?> PIC for processing instructions
• always quotes attribute value literals
• Reports the following DTD errors:
  • use of AND-connector in content model in element declaration
  • use of name group for element type in element declaration
  • use of omitted tag minimization in element declaration
  • use of CDATA or RCDATA declared content
  • use of inclusion or exclusion exceptions
  • declaration of external CDATA, SDATA, or SUBDOC entities
  • declaration of internal CDATA, SDATA, PI, STARTTAG, ENDTAG, MS, or MD entities
  • declaration of data attributes
  • use of name group for associated element type in ATTLIST
  • declaration of NAME, NAMES, NUMBER, NUMBERS, NUTOKEN, or NUTOKENS attributes
  • declaration of #CURRENT or #CONREF attributes
  • a public identifier that is not accompanied by a system identifier (except for notations)
• Reports the following general errors:
  • data entity references in data
  • nested comments (enforces XML-style comments)
  • use of tag minimization

The first two need to be fixed for Emacs in general, and not just for a single mode:

• Unicode support
• allow SYSIDs to be URLs

The remainder can be caught by using a fully conforming XML parser, like XP, in tandem with PSGML:

• full well-formedness checking
• validate that mixed content follows XML restrictions
• validate that marked sections in DTD are either INCLUDE or IGNORE
• validate that marked sections in content are CDATA (no parameter entities)
• probably many others that I've missed

2.12.4 Ulrich Windl's Code

This bit of code was posted to the SGML Tools mailing list. I haven't done anything with it yet, but put it here for future reference.

2.13 The Makefile

The Makefile handles the nitty-gritty of copying files to the right places, and setting permissions, etc.

Note the nifty use of ${HOST} as parameter to nutweb to get the right version of things for the current platform created. This is used in all the @@&lt;$1@@] references in macros such as (not used).

3. Date and Time

This file provides dates and times in a modified ISO 8601 format (change 'T' to ':' for improved readability).

Document History

4. Indices

4.1 Files

4.2 Chunks

4.3 Identifiers