3. Installation

3.1 Basic installation
3.2 .ultex file
3.3 Customization variables

3.1 Basic installation

Once you have the package in front of you, you should look at the file `INSTALLATION'. That tells you how to byte-compile the Emacs lisp code and how to produce the documentation in various formats. It also has basic instructions for how to modify your `.emacs' file. Here are more details about `.emacs':

• Make sure the directory `ultratex-0.60/lisp' is in your load path. It might be good to make a symbolic link from `ultratex-0.60' to `ultratex' and then put `ultratex/lisp' in your load-path, so that if this package ever gets upgraded to `ultratex-0.61' and you choose to install it, you only have to change the symbolic link, not your `.emacs' file. For example, I have the following line in my `.emacs' file.

  (setq load-path (cons "/home/palmieri/emacs/ultratex/lisp" load-path))

• Put the files `textree.el', `greek.el', and `skeleton.tex' someplace. They start in the directory `ultratex/user', but if you change them from their defaults, you might want to move them elsewhere so they don't get overwritten when you install a new version of the Ultra-TeX package.
• Put the following line in your `.emacs' file:

  (require 'ultex-setup)

Now the next time you start Emacs, whenever you find a TeX file, you will automatically be put into Ultra-TeX mode.

3.2 .ultex file

When Ultra-TeX starts up, it loads the file `.ultex'. This was useful in versions of Ultra-TeX before 0.50, when one would set many options by hand and then wanted to avoid cluttering up the `.emacs' file with various Ultra-TeX settings. This is not so useful in version 0.50 (or later) of the Ultra-TeX package, since all of the features can be customized, and the customizations get stored in `.emacs' automatically.

The name of the `.ultex' file is given by the variable ultex-init-file, so if you'd rather give this file a different name, like `.ultra-tex-stuff.el', then customize this variable accordingly.

3.3 Customization variables

Many of the features of Ultra-TeX mode are customizable. The best way to change this is with the customization feature of Emacs: run

M-x customize-group GRP

where GRP is one of the Ultra-TeX customization groups, to each of which we devote a subsection.

3.3.1 ultra-tex		Basic settings for Ultra-TeX mode
3.3.2 ultra-tex-init		Initialization options for Ultra-TeX mode
3.3.3 ultra-tex-files		Files used by Ultra-TeX mode
3.3.4 ultra-tex-commands		TeX/LaTeX commands in Ultra-TeX mode
3.3.5 ultra-tex-parens		Parentheses, braces, brackets
3.3.6 ultra-tex-environments
3.3.7 ultra-tex-misc		Ultra-TeX mode miscellany
3.3.8 ultra-tex-auctex		Using AUC-TeX commands with Ultra-TeX mode See the variable ultex-use-auctex.
3.3.9 ultra-tex-auctex-files		File names and paths in Ultra-TeX/AUC-TeX.
3.3.10 ultra-tex-auctex-commands		External commands in Ultra-TeX via AUC-TeX.
3.3.11 ultra-tex-auctex-latex		LaTex stuff for Ultra-TeX/AUC-TeX.

3.3.1 ultra-tex

To change these:

M-x customize-group ultra-tex

All of the other Ultra-TeX mode groups can be accessed from this one, also.

ultex-complete-idle-time

Default value: 0.5. Effect: After this much idle time has elapsed, try to complete. Measured in seconds. See section 2.2 Lightning completion.

ultra-tex-mode-hook

Default value: nil. Description: Hook for Ultra-TeX mode. This is a list of commands, each of which is executed whenever Ultra-TeX mode starts.

3.3.2 ultra-tex-init

To change these:

M-x customize-group ultra-tex-init

ultex-init-file

Default value: `~/.ultex'. Description: The Ultra-TeX Emacs lisp startup file. If you are setting Ultra-TeX options with customize, this file may be superfluous. If a file with the .el or .elc suffix exists, it will be read instead. See section 3.2 .ultex file.

ultex-use-color

Default value: nil. Effect: Toggle use of color in Ultra-TeX mode. This is pretty, but it can add a noticeable delay when starting Ultra-TeX mode.

ultex-use-font-latex

Default value: nil. Effect: Toggle use of the font-latex package for colorization. This variable is only relevant if ultex-use-color is `on'. One version of the file `font-latex.el' is distributed with Ultra-TeX. The most recent version is available from ftp://ftp.phys.ocean.dal.ca/users/rhogee/elisp/font-latex.el

ultex-use-auctex

Default value: nil. Effect: Toggle use of files from AUC-TeX distribution. This has one main effect: several commands are added to Ultra-TeX to allow one to typeset the current TeX document, spawn an external viewer, jump to the next error, etc.

This option requires the use of the file `tex-buf.el' from the AUC-TeX distribution. This file is included with Ultra-TeX, but if you want the most up-to-date version, the AUC-TeX package is available from http://sunsite.auc.dk/auctex/. See section 3.3.8 ultra-tex-auctex, for options related to this one.

ultex-use-imenu

Default value: nil. Effect: Toggle use of imenu package in Ultra-TeX mode. The `imenu' package lets you pop up a menu giving an outline of the buffer, so that you can move around to various section headings and theorem statements and so forth. If this option is on, then S-mouse-3 (hold down the shift key, and hit (and release) the right mouse button) runs the command imenu, which pops up the aforementioned menu.

ultex-use-bib-cite

Default value: nil. Effect: Toggle use of bib-cite package in Ultra-TeX mode. The bib-cite package does stuff with your labels and citations -- highlights them, lets you jump to them, etc. This option is not well-tested, and may yield unpredictable results. The latest version of bib-cite is available from ftp://ftp.phys.ocean.dal.ca/users/rhogee/elisp/bib-cite.el.

3.3.3 ultra-tex-files

To change these:

M-x customize-group ultra-tex-files

ultex-tree-file

Default value: The file `user/textree.el' in the Ultra-TeX distribution. Description: This is the pathname for your textree file, the file containing a list of TeX commands on which to complete. See section 2.3 Making a list.

ultex-extra-tree-files

Default value: nil. Description: This is a list of triples. The first element of each triple should be the name of a class, style, or package, the second the name of an associated file of TeX commands, the third a flag (t or nil). When that class, style, or package is used in any given document, the associated file of TeX commands is loaded. If the flags are nil for every class, style, and package used in the document, then the main TeX command file (ultex-tree-file) is not loaded. See section 2.3 Making a list.

ultex-greek-keys-file

Default value: The file `user/greek.el' in the Ultra-TeX distribution. Description: This is the pathname for your greek keys file, the file containing mappings for the Greek keyboards in Ultra-TeX mode. See section 2.8 Greek keyboards.

ultex-latex-skel-file

Default value: The file `user/skeleton.tex' in the Ultra-TeX distribution. Description: This is the pathname for a file containing a template for a LaTeX document. This file is inserted when the function get-latex-skel is run. See section 2.9 Everything else.

ultex-skel-hook

Default value: nil. Description: This hook is called when the function get-latex-skel is run. See section 2.9 Everything else.

3.3.4 ultra-tex-commands

To change these:

M-x customize-group ultra-tex-commands

ultex-alist-local-flag

Default value: t. Effect: When non-nil, each Ultra-TeX buffer maintains its own list of TeX commands on which to complete. See section 2.3 Making a list.

ultex-rescan-after-new-label

Default value: nil. Effect: When non-nil, Ultra-TeX rescans the buffer for labels whenever you enter a new label. This is useful if you change labels a lot and you don't want Ultra-TeX completing on old labels that you have removed.

ultex-return-checks-for-new-commands

Default value: t. Effect: When non-nil, Ultra-TeX checks the current line to see if the user just entered a new command, new environment, etc.; if so, it adds the new definition to its list of commands on which to complete.

ultex-no-grab-if-space

Default value: nil. Effect: When non-nil, Ultra-TeX will ignore all \newcommands (etc.) that do not start at the beginning of the line.

ultex-append-space-to-defs

Default value: t. Effect: When non-nil, Ultra-TeX adds a space to any TeX control sequence names it grabs from a file or buffer.

3.3.5 ultra-tex-parens

To change these:

M-x customize-group ultra-tex-parens

ultex-match-braces

Default value: t. Effect: If non-nil, hitting { inserts `{}'. See section 2.9 Everything else.

ultex-match-brackets

Default value: nil. Effect: If non-nil, hitting [ inserts `[]'. See section 2.9 Everything else.

ultex-match-parens

Default value: nil. Effect: If non-nil, hitting ( inserts `()'. See section 2.9 Everything else.

ultex-blink-matching-bracket

Default value: t. Effect: If non-nil, hitting ] will briefly highlight the matching `['. More to the point, if this is nil, then the syntax type of brackets is changed from the default, in which case Ultra-TeX might do a better job of determining when the point is in math mode. If you don't want to mess with the syntax table, but you do want to control the blinking of matching parentheses, look at the variable `blink-matching-paren' instead.

ultex-blink-matching-paren

Default value: t. Effect: If non-nil, hitting ) will briefly highlight the matching `('. More to the point, if this is nil, then the syntax type of parentheses is changed from the default, in which case Ultra-TeX might do a better job of determining when the point is in math mode. If you don't want to mess with the syntax table, but you do want to control the blinking of matching parentheses, look at the variable `blink-matching-paren' instead.

3.3.6 ultra-tex-environments

To change these:

M-x customize-group ultra-tex-environments

ultex-array-environs

Default value:

(array tabular eqnarray eqnarray* align gather alignat aligned gathered alignedat split CD matrix smallmatrix pmatrix bmatrix vmatrix Vmatrix xalignat xxalignat cases)

Description: List of symbols of array environments. See section 2.9 Everything else.

ultex-math-start

Default value: some long regular expression. Description: Regular expression to match the start of math mode.

ultex-math-end

Default value: some long regular expression. Description: Regular expression to match the end of math mode.

ultex-itemizing-environments

Default value: (list trivlist itemize description enumerate). Description: List of symbols of LaTeX environments which use `\item'. When the point is in one of these environments, hitting \\ inserts a new line and the text `\item []' (but see the next variable). See section 2.9 Everything else.

ultex-item-insert-brackets

Default value: t. Effect: When non-nil, hitting \\ in an itemizing environment inserts `\item []'; when nil, `\item ' is inserted instead.

ultex-math-cs-regexp

Default value: nil. Description: Regular expression to match TeX commands whose arguments are set in math mode.

ultex-non-math-cs-regexp

Default value: "\\\\[a-z]*box{\\|\\\\text[a-z]*{". Description: Regular expression to match TeX commands whose arguments are not set in math mode.

ultex-def-regexp

Default value: some long regular expression. Description: Regular expression to match TeX commands whose arguments may or may not be in math mode (e.g., `newcommand').

ultex-dollar-array-cursor

Default value: "|". Description: String to use to mark the cursor position in ultex-dollar-array. See section 2.5 Dollar signs.

ultex-dollar-array

Default value:

"$|$" "\[\n|\n\]" "\begin{equation}\label{|}\n\n\end{equation}" "\begin{equation*}\n|\n\end{equation*}" "\begin{align}\label{|}\n\n\end{align}" "\begin{align*}\n|\n\end{align*}" "\begin{gather}\label{|}\n\n\end{gather}" "\begin{gather*}\n|\n\end{gather*}" "\begin{multline}\label{|}\n\n\end{multline}" "\begin{multline*}\n|\n\end{multline*}"

where I have written `\n' for `newline'. Description: List of strings inserted by hitting $. The first time you hit $, the first string is inserted. Hitting it again replaces the first string with the second, etc. After inserting each string, the cursor is placed at the spot marked by the string ultex-dollar-array-cursor. If you do not include the string ultex-dollar-array-cursor anywhere, Emacs will try to guess where to put the cursor.

(Warning: customization sets the variable ultex-dollar-array-external, which has the above default value. If you want to set this directly, not via customize, then you should set ultex-dollar-array, which has a different syntax. Read the documentation for that variable for help.) See section 2.5 Dollar signs.

ultex-dollar-back

Default value: 1. Description: Which element of ultex-dollar-array to start over with once the elements have been cycled through once. The elements are numbered starting with 0. See section 2.5 Dollar signs.

3.3.7 ultra-tex-misc

To change these:

M-x customize-group ultra-tex-misc

ultex-slash-dollar-is-not-math

Default value: t. Effect: If non-nil, then typing $ right after `\' does not start math mode.

ultex-dont-use-completion

Default value: nil. Effect: If non-nil, Ultra-TeX will not use lightning completion on TeX commands. Instead, things will work sort of like regular Emacs completion: the TAB key will try to complete on command sequences, etc.

ultex-subscript-delete-leading-space

Default value: t. Effect: If non-nil, Ultra-TeX will delete leading spaces before inserting a subscript, inserting a superscript, or hitting RET to exit math mode. For example, suppose this variable is non-nil; if you have typed `$\alpha $' and the point is after the space, then hitting ^ deletes the space, producing this: `$\alpha^{}$', with the point inside the braces.

ultex-display-pictures

Default value: t if Emacs can display pictures in xpm or gif format; nil otherwise. Effect: if non-nil, Greek keyboards are displayed with pictures of symbols rather than their names.

ultex-picture-type

Default value: 'xpm, 'gif, or nil, depending on what sort of pictures Emacs can display. Effect: what format to use for picture files.

ultex-picture-directory

Default value: The directory `symbols' in the Ultra-TeX distribution. Description: Emacs looks for picture files in subdirectories `xpm' or `gif' of this directory.

3.3.8 ultra-tex-auctex

Except for ultex-ignore-auctex-tex.el, the rest of these come from AUC-TeX. To change them:

M-x customize-group ultra-tex-auctex

ultex-ignore-auctex-tex.el

Default value: t. Effect: If non-nil, then the AUC-TeX file `tex.el' will not be loaded by `tex-buf.el'. In fact, if you want to load it, you have to do it with a load command (rather than require). If the only piece of AUC-TeX you ever use is the part that comes with Ultra-TeX, then you have nothing to worry about. If you use other parts of the AUC-TeX distribution, then you might want to set this variable to nil. I can't guarantee that Ultra-TeX and AUC-TeX will interact well in that case, though.

TeX-display-help

Default value: t. Effect: If non-nil, then pop-up help when stepping thrugh errors with TeX-next-error.

TeX-debug-bad-boxes

Default value: nil. Effect: If non-nil, then also find overfull/underfull boxes warnings with TeX-next-error.

3.3.9 ultra-tex-auctex-files

These options all come from AUC-TeX. To change them:

M-x customize-group ultra-tex-auctex-files

TeX-master

Default value: t. Description: The master file associated with the current buffer. If the file being edited is actually included from another file, you can tell Ultra-TeX and AUC-TeX the name of the master file by setting this variable. If there are multiple levels of nesting, specify the top level file. If this variable is nil, Emacs will query you for the name. If the variable is t, Emacs will assume the file is a master file itself. If the variable is `'shared', Emacs will query for the name, but not change the file. See section 2.3 Making a list.

TeX-one-master

Default value: "\\.tex$". Description: Regular expression matching ordinary TeX files.

TeX-file-extensions

Default value: `'("tex" "sty" "cls" "ltx" "texi" "texinfo")'. Description: List of file extensions used by manually generated TeX files.

TeX-macro-global

Default value: `'("/usr/local/lib/texmf/tex/")'. Description: Directories containing the sites TeX macro files and style files.

TeX-macro-private

Default value: obtained from environment variables TEXINPUTS and BIBINPUTS. Description: Directories where you store your personal TeX macros.

TeX-check-path

Default value: all elements from TeX-macro-private and TeX-macro-global, as well as the current directory. Description: Directory path to search for dependencies.

BibTeX-file-extensions

Default value: `("bib")'. Description: List of valid file extensions for BibTeX files.

BibTeX-style-extensions

Default value: `("bst")'. Description: List of valid file extensions for BibTeX style files.

TeX-default-extension

Default value: "tex". Description: Default extension for TeX files.

3.3.10 ultra-tex-auctex-commands

These options all come from AUC-TeX. To change them:

M-x customize-group ultra-tex-auctex-commands

TeX-command-BibTeX

Default value: "BibTeX". Description: The name of the BibTeX entry in TeX-command-list.

TeX-command-Show

Default value: "View". Description: The default command to show (view or print) a TeX file.

TeX-command-Print

Default value: "Print". Description: The name of the Print entry in TeX-command-Print.

TeX-command-Queue

Default value: "Queue". Description: The name of the Queue entry in TeX-command-Queue.

TeX-print-command

Default value: "dvips %s -P%p". Description: Command used to print a file. First `%p' is expanded to the printer name, then ordinary expansion is performed as specified in TeX-expand-list.

TeX-queue-command

Default value: "lpq -P%p". Description: Command used to show the status of a printer queue. First `%p' is expanded to the printer name, then ordinary expansion is performed as specified in TeX-expand-list.

TeX-printer-list

Default value:

(("Local" "dvips -f %s | lpr" "lpq") ("lw") ("ps"))

Description: List of available printers. The first element of each entry is the printer name. The second element is the command used to print to this printer. It defaults to the value of TeX-print-command. The third element is the command used to examine the print queue for this printer. It defaults to the value of TeX-queue-command. Any occurence of `%p' in the second or third element is expanded to the printer name given in the first element, then ordinary expansion is performed as specified in TeX-expand-list.

TeX-printer-default

Default value: Derived from the environment variable PRINTER, or if that is not set, the car of TeX-printer-list, or if that is not set, "lw". Description: Default printer to use with TeX-command.

TeX-view-style

Default value:

(("^a5$" "xdvi %d -paper a5") ("^landscape$" "xdvi %d -paper a4r -s 4") ("." "xdvi %d"))

Description: List of style options and view options. If the first element (a regular expresion) matches the name of one of the style files, any occurrence of the string `%v' in a command in TeX-command-list will be replaced with the second element. The first match is used, if no match is found the `%v' is replaced with the empty string.

TeX-expand-list

Default value: a long list of things of the form

("%s" file nil t)

Description: List of expansion strings for TeX command names. Each entry is a list with two or more elements. The first element is the string to be expanded. The second element is the name of a function returning the expanded string when called with the remaining elements as arguments. The special value `file' will be expanded to the name of the file being processed, with an optional extension.

TeX-command-list

Default value: a long list of things of the form

("LaTeX" "%l '\\nonstopmode\\input{%t}'" TeX-run-LaTeX nil t)

Description: List of commands to execute on the current document. Each element is a list of five elements, whose first element is the name of the command as it will be presented to the user. The second element is the string handed to the shell after being expanded. The expansion is done using the information found in TeX-expand-list. The third element is the function which actually start the process. Several such hooks has been defined; see the function documentation for a description. If the fourth element is non-nil, the user will get a chance to modify the expanded string. The fifth element is obsolete and ignored.

3.3.11 ultra-tex-auctex-latex

These options all come from AUC-TeX. To change them:

M-x customize-group ultra-tex-auctex-latex

LaTeX-version

Default value: "2e". Description: Default LaTeX version. The only choices are "2" and "2e".

LaTeX-command-style

Default value: if LaTeX-version is "2e", then (("." "latex"))). If LaTeX-version is "2", then a longer list. Description: List of style options and LaTeX commands.