% -*-latex-*-
% Document name: /u/beebe/ltxmode.ltx
% Creator: Nelson H. F. Beebe [beebe@rios.math.utah.edu]
% Creation Date: Sat Jul 27 15:49:18 1991

%%% ====================================================================
%%%  @LaTeX-file{
%%%     author          = "Nelson H. F. Beebe",
%%%     version         = "1.07",
%%%     date            = "05 September 1993",
%%%     time            = "11:28:34 MDT",
%%%     filename        = "ltxmode.ltx",
%%%     address         = "Center for Scientific Computing
%%%                        Department of Mathematics
%%%                        University of Utah
%%%                        Salt Lake City, UT 84112
%%%                        USA
%%%                        Tel: +1 801 581 5254
%%%                        FAX: +1 801 581 4148",
%%%     checksum        = "31268 4364 16697 136831",
%%%     email           = "beebe@magna.math.utah.edu (Internet)",
%%%     codetable       = "ISO/ASCII",
%%%     keywords        = "LaTeX, emacs",
%%%     supported       = "yes",
%%%     docstring       = "This document is intended for publication
%%%                        in the TeX Users Group journal, TUGboat,
%%%                        volume 13, number 1 or 2.
%%%
%%%                        There is also companion document, called
%%%                        ltxinfo.ltx, derived from this one.  It is
%%%                        in LaTeXinfo format from which both a
%%%                        typeset manual and an on-line Emacs info
%%%                        node can be produced, the latter by the
%%%                        function latexinfo-format-buffer.  It omits
%%%                        the early sections that introduce the
%%%                        reader to Emacs.
%%%
%%%                        Because of the limitations of LaTeXinfo and
%%%                        the on-line display of typeset material as
%%%                        printable 95-character ASCII data, there
%%%                        are some minor differences in these documents.
%%%
%%%                        The author's intent is that both documents
%%%                        will be kept strictly synchronized, and both
%%%                        will be freely available electronically.
%%%
%%%                        The LaTeXinfo version, and latex.el, will
%%%                        become the property of the Free Software
%%%                        Foundation to ensure legal protection and
%%%                        wide distribution of this work, which has
%%%                        been supported financially by taxpayers, who
%%%                        support higher education, by IBM Corporation
%%%                        through the loan of an RS/6000 workstation,
%%%                        and by the many colleagues around the world
%%%                        who have helped in the beta testing.
%%%
%%%                        The author retains responsibility for errors
%%%                        of fact, typography, or programming, and
%%%                        desires to be informed of all such errors so
%%%                        that they can be corrected in future
%%%                        revisions of this work.
%%%
%%%                        The checksum field above contains a CRC-16
%%%                        checksum as the first value, followed by the
%%%                        equivalent of the standard UNIX wc (word
%%%                        count) utility output of lines, words, and
%%%                        characters.  This is produced by Robert
%%%                        Solovay's checksum utility.",
%%%  }
%%% ====================================================================

%=================================================
%=========> See NOTE TO THE EDITOR below <========
%=================================================
% TO DO:
% [08-Aug-1991] Add copy of Makefile for letter
%               mode with brief description.
%               NO: that is a subject for another
%               article, and would take us too far
%               afield in this one.
%=================================================
% Change log after 1 Aug 1991 0:31 printing
%
% Sun Sep  5 11:26:07 1993
% 	Revise description of mouse-based indexing
% 	to reflect new button binding.
%
% Sat Jul 25 12:26:36 1992
%       Augment Bibliographies subsection to discuss
%       BibTeX citation tag completion support.
%
% Fri May 29 08:04:57 1992
%       Insert load of tex-mode.el in .emacs file
%       to ensure override by latex.el.  Change
%       \documentstyle to use new ltugboat as major
%       style.
%
% Sun Oct  6 09:32:22 1991
%       Final index polishing and verification that
%       all functions and variables have been
%       documented (a couple were missing).
%
% Fri Oct  4 13:33:51 1991
%       Make minor index enhancements, change
%       ``see'' to ``see also'' in index entries,
%       and move them to the end of this file so
%       they occur after the list of page numbers
%       in the index.
%       Correct ``Redo'' to
%       ``repeat-complex-command''.
%
% Thu Oct  3 00:00:47 1991
%       Add mention of \vdots.
%       Add sloppypar around one bad paragraph.
%       Add several references to recent TUGboat
%       papers on TeX editing support.
%       Add new section on French typography.
%
% Fri Sep 13 16:41:51 1991
%       Finished first cut at complete LaTeXinfo
%       version of this document, and in doing so,
%       found a few more typos in both, sigh...
%       Added the standard file header above.
%       Incorporate remark about additional a-list
%       entries added to
%       LaTeX-standard-environments.
%
% Mon Sep  9 13:54:05 1991
%       Remove single reference to obsolete
%       labelledequation environment.
%
% Sun Sep  1 12:50:47 1991
%       Add discussion of
%       LaTeX-extra-tied-abbreviations and
%       LaTeX-standard-tied-abbreviations.
%
% Wed Aug 28 08:48:54 1991
%       Fix three small formatting problems, and
%       add a few more index entries.
%
% Tue Aug 27 19:06:40 1991
%       Add LaTeX-set-indentation description.
%
%       Update documentation of LaTeX-bibitem,
%       LaTeX-cite, and LaTeX-item (they now
%       accept arguments).
%
% Mon Aug 26 09:51:04 1991
%       Add LaTeX-subscript and LaTeX-superscript
%       descriptions, and make several small
%       corrections and tunings.
%
% Sat Aug 24 17:28:00 1991
%       Augment discussion of autoload problem.
%
%       Add note that latex-mode == LaTeX-mode.
%
%       Add description of LaTeX-label-definition
%       and LaTeX-label-reference variables.
%
%       Add description of solution of multi-file
%       document label support with the function
%       update-LaTeX-labels and the variable
%       LaTeX-aux-file-label-tags.
%
%       Add discussion of global name space and
%       function/variable naming conventions.
%
%       Revise Figure 3 to reflect new functionality.
%
%       Update code size statistics in Sections 2
%       and 10.
%
%       Add percent to end of \typeout{} to remove
%       spurious extra space that otherwise sneaks in.
%
% Fri Aug 23 00:07:38 1991
%       Add description of
%       LaTeX-standard-environments; all variables
%       and user-visible functions in latex.el are
%       now documented.
%
%       Update option and style lists to match
%       current TEXINPUTS search path offerings.
%
%       Add some additional discussion of
%       LaTeX-xxx-options and LaTeX-xxx-styles.
%
%       Describe new LaTeX-quoted-insert and
%       change ``Dots and commas'' section title
%       to ``Dots, commas, and quotation marks''.
%
%       Update key bindings list in Figure 4
%       (all dependence on tex-mode.el has now
%       been removed).
%
%       Add discussion of association lists and why
%       we use lists-of-lists-of-strings instead of
%       lists-of-strings.
%
% Wed Aug 21 12:28:41 1991
%       Revise discussion of LaTeX-dot after
%       revision of code, and addition of new
%       LaTeX-standard-dotted-abbreviations and
%       LaTeX-extra-dotted-abbreviations variables.
%
%       Add short description of auto-save and undo.
%
%       Add reference to Rainer Schoepf's work on
%       comment environment.
%
%       Revise discussion of SLiTeX support,
%       following addition of support for note and
%       overlay environments.
%
%       Add description of
%       LaTeX-standard-unindented-environments and
%       LaTeX-extra-unindented-environments.
%
% Sat Aug 10 08:57:16 1991
%       Revise LaTeX-dollar in latex.el, and
%       rewrite math mode section.
%
% Wed Aug  7 16:09:03 1991 (feedback from TUGboat
%       editors and others)
%       Change VAX VMS to \VMS for kern and indexing
%       Add \ASCII macro
%       Change ``online as well'' to ``online as
%       well as''
%       Remove one space after e.g. in Figure 3
%       (fig-latex-index)
%       Change ``forwards'' to ``forward'', ditto
%       for ``backwards''
%       Change ``\verb*|\TeX\ book| will not'' to
%               ``\verb*|\TeX book| will not''.
%       Add italic correction after 66ff in
%               ``\cite[pp.~66ff\/]{Lamport:latex}''
%       Change ``immediately get a buffer'' to
%               ``immediately get the buffer''
%       Add \typeout about Fig 7
%               (fig-latex-letter) and change
%               reference to it.
%       Change ``Mass Ave'' to ``Massachusetts Ave''.
%       Change ``EEL. '' to ``EEL\@.''
%       Change visible space to \CURSOR using \Box
%               for cursor representation.
%       Change \newcommand{\CTL}[1]{\XX{\sf}{C-\hyphenpenalty10000 #1}}
%               to new \CTL and \CTLAUX below; the
%               hyphenpenalty still did not work
%               in all cases.  The new definition
%               puts the C-x into an \mbox,
%               preventing the break.  Ditto for
%               \META and \METAX.
%       Change the six discussions and examples of
%               command completion to note that
%               \KEY{RETurn} is needed to accept the
%               completion.
%       Clarify \CTL{c l}: that's the letter `l'
%       Add \MACRO and \MACROX to get LaTeX macros
%               into the index as well as the
%               text.  Users may want to find the
%               Emacs function for a particular
%               LaTeX command.
%       Add more index entries.
%       Change \theindex below to have an
%               \addcontentsline{toc}...
%
% Fri Aug  2 09:46:22 1991
%       change -\nobreak to -\hyphenpenalty10000
%       (I don't understand why \nobreak and
%       \nolinebreak both fail to prevent the break)
%       revise figure ref to fig-startup-code and
%       add \typeout reminder
%

\documentstyle[makeidx]{ltugboat}

%=================================================
%===============NOTE TO THE EDITOR================
% This article has a table of contents, a
% list of figures, and an index.  It also has
% extensive cross-referencing because it is also
% expected to function as a user manual for LaTeX
% editing mode.  It will be necessary to run
% LaTeX 3 times, with MakeIndex invoked between
% each step, to ensure consistency.
%
% Please check the final copy to ensure that the
% cross-reference to Figures 1 and 2 and to
% Figures 4 and 5 are correct.  Look for the
% \typeout{...} commands in the text below for
% details.
%
% ltugboat.sty (version 1.10, 13 Feb 1991) should
% be updated to:
%
% (a) incorporate a fix for bad positioning of
% subsection numbers in the table of contents, and
% excessive space between numbers and titles in
% the list of figures (see redefinition of
% \@pnumwidth below),
%
% (b) produce a visible separator (like my
% \HALFLINE) after the table of contents and the
% lists of figures and tables.
%
% (c) suppress removal of the page header on the
% index page (see \theindex) below, and set the
% index \raggedright
%
% (d) possibly reduce the tolerance in the
% definition of \sloppy and add some
% emergencystretch (see below); I have found this
% helpful in other two-column work, and TUGboat
% has a lot of that kind of typesetting.
%
% This document gets nearly 40 underfull boxes;
% attempts to fix them by adjusting \tolerance,
% \pretolerance, \hyphenpenalty, \exhyphenpenalty,
% and \emergencystretch were futile.  There are
% no overfull boxes.
%
%=================================================

%=================================================
% NB: In order to fit in a two-column TUGboat
% article, lines in small verbatim environments
% must not exceed 46 characters in length.
% Elsewhere, I have set the fill column to 50.
%
% Those macros which generate index entries, or
% might be arguments to ones which do, must have
% all control sequences prefixed with \protect
% to prevent expansion into the .idx file.
%
% Macros are (re)defined in alphabetical order,
% ignoring letter case.
%=================================================

% Supply some extra stretch to remove underfull boxes
% \ifx \emergencystretch\undefined
% \else
%    \emergencystretch=6pt
% \fi

\hbadness = 9999 % don't complain about most underfull boxes

\makeatletter
\def\@pnumwidth{2.55em}         %was 1.55em
\makeatother

\ifx\AMSTeX\undefined
    \newcommand{\AMSTeX}{\AmSTeX}
\fi

\newcommand{\ASCII}{ASCII}      %TUGboat editors prefer ascii, I want ASCII
                                %because it is an abbrev, not a word
\newcommand{\BRACED}[1]{{\protect\tt\protect\char123#1\protect\char125}}
                                %used in index refs to avoid getting
                                %spaces output after literal braces

\newcommand{\CONSTANT}[1]{\XX{\sf}{#1}}         % Emacs constant name

\newcommand{\CTLAUX}[2]{\mbox{C-#1} #2\unskip}  % auxiliary support for \CTL
\newcommand{\CTL}[1]{{\sf\CTLAUX#1{}}%
      \index{C-#1@{\protect\sf\protect\CTLAUX#1{}}}} % keyboard key name

\newcommand{\CTLCC}[1]{{\sf \mbox{C-c} \mbox{C-c} #1}
  \index{C-c C-c #1@{\protect\sf \protect\mbox{C-c} \protect\mbox{C-c} #1}}}
                                % C-c C-c #1 for proper indexing

\newcommand{\CURSOR}{\leavevmode\lower0.17ex\hbox{$\Box$}\index{cursor}}
                                %visible cursor for output examples
\makeatletter
    \newcount\ThisRefNum
    \newcommand{\FIGREF}[1]{%
      \expandafter\ifx\csname r@#1\endcsname\relax
         \ThisRefNum=-99999%
      \else
         \edef\@tempa{\@nameuse{r@#1}}%
         \ThisRefNum=\expandafter\@cdr\@tempa\@nil\null
      \fi
      Figure~\ref{#1}%
      \ifnum\ThisRefNum=\c@page\relax
      \else
        \ on page~\pageref{#1}%
      \fi
    }                       %figure ref, or figure+page if on another page
\makeatother

\newcommand{\FILE}[1]{\XX{\tt}{#1}}             % computer file name
\newcommand{\FIXVERB}{\parindent=0pt\parskip=0pt\topsep=0pt}
                                                % to fix spacing in mixex
                                                % verb and verbatim envs
% Try to keep Figures 4 and 5 together; 5 otherwise
% floats to end of document, but is really part of
% 4, which was too long to fit.
\setcounter{totalnumber}{4}
\renewcommand{\floatpagefraction}{0.25}

\newcommand{\FUNCTION}[1]{\XX{\sf}{#1}}         % Emacs function name
\newcommand{\KEY}[1]{\XX{\sf}{#1}}              % keyboard key name
\newcommand{\KEYNX}[1]{{\sf#1}}         % keyboard key name (no index entry)
\newcommand{\KEYWORD}[1]{{\bf #1}}              % computer program keyword
\newcommand{\HALFLINE}{%
            \medskip
            \hbox to \linewidth{%
               \hfil\vrule height 0.2pt depth 0.2pt width 0.5\linewidth\hfil
            }
            \medskip                %to separate toc from text;
                                    %this should be in ltugboat.sty
}

% French guillemets (definitions borrowed from german.sty)
\newcommand{\flqq}{\ifmmode \ll \else \leavevmode
        \raise 0.2ex \hbox{$\scriptscriptstyle \ll $}\fi }
\newcommand{\frqq}{\ifmmode \gg \else \leavevmode
        \raise 0.2ex \hbox{$\scriptscriptstyle \gg $}\fi }

\newcommand{\MACRO}[1]{{\tt\char92#1}}
\newcommand{\MACROX}[1]{\MACRO{#1}\index{#1@\protect\MACRO{#1}}}
\newcommand{\METAAUX}[2]{\mbox{M-#1} #2\unskip} % auxiliary support for \META
\newcommand{\META}[1]{{\sf\METAAUX#1{}}%
                      \index{M-#1@{\protect\sf\protect\METAAUX#1{}}}}
                                                % keyboard key name
\newcommand{\METAX}[1]{{\sf \mbox{M-x} #1}%
                       \index{M-x #1@{\protect\sf\protect\mbox{M-x} #1}}%
                       \index{#1@{\protect\sf #1}}}
                                                % Emacs M-x function command
\newcommand{\PAGEREF}[1]{page~\pageref{#1}}     % for easier page references
\newcommand{\PROG}[1]{\XX{\tt}{#1}}             % computer program name

\newcommand{\seealso}[2]{{\em see also\/} #1}

\ifx\SLiTeX\undefined
    \newcommand{\SLiTeX}{\SliTeX}
\fi

% LaTeX's default tolerance of 10000 in sloppy and sloppypar
% is unsatisfactory in two-column mode; \emergencystretch
% saves the day
\renewcommand{\sloppy}{\emergencystretch=10pt
                       \tolerance 9000 \hfuzz .5pt \vfuzz .5pt}

\newcommand{\SPACE}{{\protect\tt\protect\char32}} % literal space

\makeatletter
\renewcommand{\theindex}{
    \@restonecoltrue\if@twocolumn\@restonecolfalse\fi
    \columnseprule \z@
    \columnsep 35pt\twocolumn[\section*{Index}]
    \@mkboth{INDEX}{INDEX}
%   \thispagestyle{plain}    %leave pagestyle alone
    \parindent\z@
    \parskip\z@ plus .3pt\relax\let\item\@idxitem
    \addcontentsline{toc}{section}{\numberline {}Index}
    \raggedright                % index entries are sometimes long
}
                                        %this should be in ltugboat.sty
\makeatother

\newcommand{\Tib}{\XX{\sc}{Tib}}                % Jim Alexander's package
\newcommand{\TYPEIN}[1]{{\tt #1}}               % user type in
\newcommand{\VARIABLE}[1]{\XX{\sl}{#1}}         % Emacs variable name
\newcommand{\VMS}{\VAX{} VMS\index{VAX VMS@\protect\VAX{} VMS}}
\newcommand{\X}[1]{#1\index{#1}}                % text + index entry
\newcommand{\XCTL}[1]{\index{C-#1@{\protect\sf\protect\CTLAUX#1{}}}}
\newcommand{\XCTLCC}[1]{\index{C-c C-c #1@%
              {\protect\sf \protect\mbox{C-c} \protect\mbox{C-c} #1}}}
\newcommand{\XF}[1]{\index{#1@{\protect\sf #1}}}% silent function index entry
\newcommand{\XK}[1]{\index{#1@{\protect\sf #1}}}
\newcommand{\XM}[1]{\index{#1@\protect\MACRO{#1}}}
                                                % silent LaTeX macro entry
\newcommand{\XMETA}[1]{\index{M-#1@{\protect\sf\protect\METAAUX#1{}}}}
\newcommand{\XV}[1]{\index{#1@{\protect\sl #1}}}% silent variable index entry
\newcommand{\XX}[2]{{\protect#1#2}\index{#2@{\protect#1#2}}}
                                                % font + text + index entry

%=================================================

% figbox draws a box around its contents, which
% can even contain verbatim text!
\newbox\thefigbox
\newenvironment{figbox}{%
    \setbox\thefigbox\hbox\bgroup
    \advance\linewidth by -2\fboxsep %make outer box dimension == linewidth
    \advance\linewidth by -2\fboxrule
    \hss
    \begin{minipage}{\linewidth}%
}{%
    \end{minipage}%
    \hss
    \egroup
    \fbox{\box\thefigbox}
}

%=================================================

\title{
        \protect\LaTeX{} Editing Support
}

\author{
        Nelson H. F. Beebe
}

\address{
        Center for Scientific Computing\\
        Department of Mathematics\\
        University of Utah\\
        Salt Lake City, UT 84112\\
        USA\\
        Tel: +1 801 581 5254\\
        FAX: +1 801 581 4148
}

\netaddress[\network{Internet}]{beebe@math.utah.edu}

\makeindex

%=================================================

\begin{document}

\maketitle

\tableofcontents

\HALFLINE

\listoffigures

% Suppress this one for now, since the table of
% contents and list of figures exactly fill one
% TUGboat column.
% [03-Oct-1991] -- no longer true after French
% typography section added
\HALFLINE

\bibliographystyle{plain}

\section{Introduction}

The structured markup of \LaTeX{} can be easy to
read and understand, but tedious to type.  Its
syntax of environment groups bears a strong
resemblance to the \KEYWORD{begin}\slash
\KEYWORD{end} groups of the
Algol\index{Algol language}
family of computer programming languages, which
can be described by rigorous grammars that in turn
permit the automatic construction of lexical
analyzers and parsers, and \X{structured editor}s
to support programming in those languages
\cite[pp.~97--116, pp.~128--140, pp.~232-239]%
{Barstow:environ}.%
\index{Barstow, David~R.}%
\index{Shrobe, Howard~E.}%
\index{Sandewall, Erik}
This article describes a powerful facility
for the preparation of \LaTeX{} documents using
the Emacs text editor.

The convention here is that material displayed
in a {\tt typewriter font} is computer output, a
program name, or all or part of a file name.  A
{\sf sans serif font} is used for key names and
Emacs functions, and a {\sl slanted font} for
Emacs variable names.

Emacs is very likely the world's most powerful
text editor, because it is highly programmable and
customizable.  The popularity of the original
Emacs on the DEC \X{PDP-10} architecture in the
1970s led to several reimplementations on other
operating systems, particularly on \X{UNIX} and
\VMS{}.  The wide availability of the
excellent implementation from the \X{Free Software
Foundation}, known as \X{GNU Emacs},
has made Emacs the editor of choice for many
programmers on machines more powerful than
personal computers.  Smaller Emacs-like editors
have also been developed, including
  \begin{itemize}
    \item
          Jonathan Payne's\index{Payne, Jonathan}
          \PROG{jove} (Jonathan's
          Own Version of Emacs) for \X{UNIX},
          \VMS{}, \X{IBM PC} DOS,%
          \index{PC}%
          \index{PC DOS}
          and the \X{Apple Macintosh};%
          \index{Macintosh}

    \item
          \PROG{microemacs} and \PROG{freemacs} on
          \X{IBM PC} DOS;%
          \index{PC}%
          \index{PC DOS}

    \item
          the commercial editors \PROG{epsilon}
          from \X{Lugaru Software, Ltd{.}} (5843
          Forbes Avenue, Pittsburgh, PA 15217,
          USA), and \PROG{brief}
          from \X{Solution Systems} (541 Main St,
          Suite 410, South Weymouth, MA 02190,
          USA).

  \end{itemize}

Several years ago, I developed substantial editing
support in the \X{TOPS-20} Emacs text editor for
the \X{Fortran} and \X{SFTRAN3} languages, and
also for \LaTeX{}.  TOPS-20 Emacs was programmed
in a very terse language called \X{TECO}, in which
all 128 \ASCII{} characters are assigned editing
functions, and multi-character names provide
thousands more.

As we acquired \VMS{} and \X{UNIX} systems running
GNU Emacs, I reimplemented that editing support in
GNU Emacs Lisp,%
\index{Lisp!GNU Emacs}
which although much more verbose
than \X{TECO}, is much easier to read and write.

The purpose of this article is to describe the
capabilities of the \LaTeX{} editing support.
Before we get into that, however, some background
about Emacs must first be presented.  If you are
already familiar with Emacs, you might want to
skip ahead directly to the section {\bf \LaTeX{}
support} beginning on
\PAGEREF{latex-support}.

\section{Emacs history}

Emacs was developed by Richard M. Stallman%
\index{Stallman, Richard M.}
starting about 1974 on a \X{PDP-10} running
\X{MIT}'s \X{ITS} (\X{Incompatible Timesharing
System}) operating system.  The kernel of the
editor was written in PDP-10 assembly language,
which could be made to produce versions for DEC's
\X{TOPS-10} and \X{TOPS-20} systems and Stanford's
\X{SAIL} system as well, thanks to the
availability of conditional compilation
facilities.  SAIL was the home of the original
\TeX{} development.

Because \X{PDP-10} machines formed the backbone of
the original \X{Arpanet}, the precursor to today's
Internet linking millions of computers, and
because Emacs' author believed fervently in the
value of sharing of software, Emacs was soon in
wide use throughout the Arpanet.

Like \X{Topsy} in {\em Uncle Tom's Cabin\/}
\cite[p.~277]{Stowe:uncle-toms-cabin},%
\index{Stowe, Harriet Beecher}
PDP-10 Emacs just grew; the final version from the
mid 1980s had about 150 libraries and perhaps 2000
editing functions.  What made this possible was
the architectural division of the editor into two
parts:
%
  \begin{itemize}

    \item
          a modest kernel of low-level functions,
          like character insertion, deletion, and
          movement, string searching, and
          operating-system interface that have to
          be efficiently implemented for
          performance reasons, and

    \item
          a much larger collection of libraries
          written in a higher-level language,
          \X{TECO} (Text Editor and COrrector),
          that can be written, compiled, and
          debugged inside Emacs itself, thanks to
          the TECO interpreter and compiler
          included in the kernel.  Libraries can
          be loaded on demand, or automatically
          when certain specified conditions are
          met.

  \end{itemize}

Emacs' TECO was greatly extended beyond Dan
Murphy's\index{Murphy, Dan}
original TECO developed on early DEC \X{PDP}
machines at \X{MIT} in the 1960s.  TECO remains
available today on DEC \X{PDP-11} and \VMS{}
systems, though it has largely fallen into
disfavor because of its terseness, and because
DEC's versions provide only limited support for
screen-based editing.

The GNU Emacs reimplementation has a similar
division of architecture, but its kernel is
written in the \X{C language} for {\em
portability}, and high-level functions are written
in Lisp%
\index{Lisp!GNU Emacs}
for {\em readability}.  The Emacs Lisp
interpreter is provided by the C-language kernel,
and the compiler is written in Lisp.  The Lisp
dialect is peculiar to GNU Emacs, but is closely
related to \X{MIT}'s \X{MACLisp}.%
\index{Lisp!MACLisp}
In particular,
both use \X{dynamic scoping}, rather than the
\index{scoping}%
\X{lexical scoping}
of \X{Common Lisp};%
\index{Lisp!Common}
if you don't know why that is significant, read
Stallman's%
\index{Stallman, Richard M.}
article in \cite{Barstow:environ}.%
\index{Barstow, David~R.}%
\index{Shrobe, Howard~E.}%
\index{Sandewall, Erik}

Emacs supports simultaneous editing of multiple
files in multiple buffers, with the screen divided
horizontally and\slash or vertically to provide
windows into one or more buffers.  It also
supports an extensive on-line help system, with
self-documenting commands, and the full text of
many user manuals accessible inside the editor.

All of this power requires a lot of code to
support it, and about a megabyte of central memory
to run satisfactorily; that is why GNU Emacs has
not been ported to personal computer environments.
At version 18.57, GNU Emacs consists of%
\index{GNU Emacs!code size}
about 73600 lines of C code
\index{C language}
in 188 source files,
55300 lines of Lisp%
\index{Lisp!GNU Emacs}
in 145 libraries, 594 functions written in C, and
2718 functions written in
Lisp.%
\label{gnu-emacs-size}
The \LaTeX{} support code described here consists
of about 4200 lines of Lisp defining 91 functions
and 54 variables, together with an additional 900
lines and 30 functions of auxiliary support.%
\index{code size}

Some people argue that such a powerful editor
`wastes machine resources'; I disagree---computers
should work for people, not the reverse.

\section{Emacs editing model}

Some vendor-provided text editors, such as
\PROG{edt} in \VMS{} and \PROG{vi} in UNIX, have
two modes: command mode, and text insertion mode.
The meaning of a key depends on which mode you are
in, and some users find themselves frequently
making mistakes because they type in the wrong
mode.

Emacs does not make a distinction between these
two.  Instead, each character you type runs a
function.  The function attached to most printing
characters just inserts them in the buffer, so
entry of normal text works just like in other
editors.  However, certain keys invoke editing
functions that do other tasks.  For example,
pressing the \KEY{DELete} key results in a call to
a function that deletes the character on the
screen immediately before the \X{cursor}.

The execution of editing functions in response to
keystrokes requires \X{character-at-a-time input}.
Some older mainframe operating systems do not
support this, but all newer ones do.

Because most printing characters are needed for
themselves, and most \ASCII{} control characters
have no useful printable representation,
commonly-needed editing functions are assigned to
control characters, with mnemonic significance
where possible.  For example, the character
generated by holding down the \KEY{control} key
while pressing the \KEY{e} key, represented by the
compact notation\index{control character
notation} \CTL{e}, runs a function that moves the
\X{cursor} to the {\em end\/} of the current line,
and \CTL{d} runs a function that {\em deletes\/}
the character under the cursor.

There are only 33 control characters in \ASCII{},
and more editing functions are needed.  Some
terminal keyboards in the 1970s provided an
additional key, called a \KEY{meta} key, which
worked like the \KEY{control} key, except that it
added the 8th bit to the character value,
generating a character in the range 128 \ldots{}
255, thereby providing for another 128 keys to
bind functions to.  On keyboards that lack such a
key, the \ASCII{} \KEY{ESCape} key is used as the
first of a two-key sequence to represent the same
thing.  This is written \META{a}, meaning to hold
down the \KEY{meta} key while striking the
\KEY{a}, or to type the two characters \KEY{ESCape
a} in succession.

  \begin{sloppypar}
However, even $33 + 128$ functions are insufficient, % UNDERFULL fix for ``not enough,''
so one or more key sequences are used as prefixes
to named commands, or to get another 128
command-letter possibilities.  Thus, the command
\METAX{sort-lines} runs a function to sort lines
in the current region (a subset of the buffer),
and for editing \LaTeX{} text, \CTL{c f} generates
a \MACROX{footnote}\BRACED{}.
  \end{sloppypar}

All Emacs key bindings are customizable, and
importantly, that customization can be {\em
unique\/} to each edit buffer.  To reduce
confusion, the commonest functions, those attached
to most \KEY{control} and \KEY{meta} keys, are
rarely rebound, and even when their bindings are
changed, the functionality provided is usually
similar.  There is a good analogy here with
\TeX{}'s \X{catcode}s, which also permit
characters to take on new meanings.

Keyboards on some terminals, the \X{IBM PC},%
\index{PC}
and
workstations have additional keys with \X{cursor
direction arrow}s, and labels like \KEY{Help},
\KEY{Home}, and \KEY{Page Down}.  These keys
usually generate multi-character \X{escape
sequence}s, or special \X{scan code}s.  Emacs' key
binding model is general enough to deal with these
special codes, allowing functions to be bound to
them.  Novices often find such keys convenient,
but fast \X{touch typist}s prefer the conventional
key bindings because they need not move their
hands from the standard typing position.

A collection of key-function bindings suitable for
a particular task is known as an  {\em \X{editing
mode}\/}.  A mode can be selected by name, such as
in the command \METAX{LaTeX-mode}, or it can be
set automatically according to the extension of
the file name that has just been selected for
editing.  The connection between file extensions
and Emacs editing modes is of course
user-customizable.

Most Emacs functions can be given arguments when
they are invoked.  In the simplest case, a
\X{numeric argument} says to do the command $n$
times.  The function \FUNCTION{universal-argument}
is bound to \CTL{u}, so typing \CTL{u -31}
produces an argument of -31.  If no digits or
minus sign follow, an argument of 4 is provided,
and if the command is used more than once in
succession, the argument is multiplied by four
each time: \CTL{u} \CTL{u} \CTL{u} \KEY{x} will
insert 64 \KEY{x}'s into the buffer.  Multiple
\CTL{u} keystrokes are often used to speed up
\X{cursor movement}.

Some functions just use the presence or absence of
an argument to vary their behavior slightly, like
\LaTeX{}'s starred and unstarred commands.
Functions that expect string arguments prompt for
them.

Like \TeX{} and the \X{C language}, and {\em
unlike\/} \X{Common Lisp}%
\index{Lisp!Common!case sensitivity}
and most other programming languages, GNU Emacs
Lisp%
\index{Lisp!GNU Emacs!case sensitivity}
is {\em case sensitive}.  If you type
\METAX{latex-mode} instead of \METAX{LaTeX-mode},
then depending on the order of library loading,
you might get only the limited support for
\LaTeX{} provided in the standard GNU Emacs
\FUNCTION{tex-mode}.  Had the prefix%
\index{name prefix}%
\index{prefix in name}
{\sf latex-}
not already been usurped by \FUNCTION{tex-mode}, I
would have employed it myself, because it is
easier to type than {\sf LaTeX-}.  Perhaps that
can be changed in the future.  In any event, most
\FUNCTION{LaTeX-mode} functions have key bindings,
so only rarely do you have to type their names.

In any text editor, it is always possible to make
a serious editing mistake that damages your work.
Emacs offers several features that help you
recover.  It has an \FUNCTION{auto-save-mode} that
causes backup copies of the edit buffers to be
saved in the file system.  You can select how many
file generations to save, and how often
auto-saving occurs.  Emacs catches fatal errors,
like loss of a phone line or network connection,
and saves your work.  On request, it can show you
what you have recently typed, so you can perhaps
figure out what you did wrong.  It also provides
an extensive {\em \X{undo facility}} that lets you
revert to an earlier stage of editing; if you
accidentally undo too much, you can undo your undo
commands, retracing your steps to reach the point
you want.

\section{Emacs documentation}

\TeX{}info,\index{texinfo@\TeX{}info}
and its more recent relative,
\LaTeX{}info,\index{latexinfo@\LaTeX{}info}
are greatly-restricted \TeX{} and
\LaTeX{} subsets.  Files in these formats can be
typeset by \TeX{} or \LaTeX{}, or converted with
the \PROG{makeinfo} program, or the Emacs
\FUNCTION{latexinfo-format-buffer} or
\FUNCTION{texinfo-format-buffer}
functions, into a file in a special format that
allows easy navigation by the Emacs \PROG{info}
system.

\PROG{info} is a mature implementation of a {\em
\X{hypertext}\/} system, subject to the constraint
that text must be viewable using only the 95
printing \ASCII{} characters.

Simple commands allow `swinging through the
branches' of the \PROG{info} tree, selecting
topics from menus, searching forward and
backward, moving up, down, and sideways through
the branches, jumping temporarily into
cross-references or to arbitrary nodes by name,
and retracing one's node path which \PROG{info}
always remembers.  Since the \PROG{info} text is
always viewed in an Emacs buffer, which might be
visible in one of several windows on the screen,
documentation can be read (and edited) while you
are inside Emacs.  You can enter and leave
\PROG{info} at will.  Emacs always remembers where
you were, so reentry brings you back to the exact
spot in the documentation that you were reading
before.

\section{Learning an Emacs editing mode}

When faced with a new editing mode (i.e.\ set of
key-function bindings), an Emacs user wants to be
able to find out how to use it.  This can be done
in several ways:
%
  \begin{itemize}

    \item
          Sometimes, there is printed
          documentation of the kind you will see
          later in this article.  If that
          documentation is prepared in
          \LaTeX{}info\index{latexinfo@\LaTeX{}info}
          or
          \TeX{}info\index{texinfo@\TeX{}info}
          format, it can be accessible online as
          well in the Emacs \PROG{info} system.

    \item
          Most editing modes provide a brief
          summary of their usage in response to
          the command \METAX{describe-mode},
          conventionally bound to \CTL{h m}.
          \CTL{h} is the Emacs \KEY{Help} key; the
          keyboard also generates \CTL{h} when the
          \KEY{BackSpace} key is pressed.  The
          output of this command in
          \FUNCTION{LaTeX-mode} is shown in
\typeout{====> Check page cross-reference to Figs 1 and 2}%
%          \FIGREF{fig-latex-mode-1}
          Figure~\ref{fig-latex-mode-1}
          and
          \FIGREF{fig-latex-mode-2}.

    \item
          Documentation of individual commands or
          keys can be requested: \CTL{h d}
          (\FUNCTION{describe-function})
          \FUNCTION{LaTeX-index} and \CTL{h k}
          (\FUNCTION{describe-key})
          \CTL{c x} both display the text shown
          in \FIGREF{fig-latex-index}.%
          \index{function documentation}%
          \index{documentation of function}

    \item
          \CTL{h w} (\FUNCTION{where-is}) tells
          what the key binding of a named function
          is.

    \item
          The command \METAX{apropos} searches the
          list of loaded functions to find all
          those with a particular phrase in their
          names.

    \item
          The function
          \FUNCTION{describe-bindings} on \CTL{h
          b} will display in a separate buffer a
          list of all of the local
          (buffer-specific) and global (all
          buffers) key bindings.  The local
          bindings for \FUNCTION{LaTeX-mode}
          produced by that function are shown in
\typeout{====> Check page cross-reference to Figs 4 and 5}%
%         Figure~\ref{fig-bindings-1}
          \FIGREF{fig-bindings-1}
          and
          \FIGREF{fig-bindings-2}.

  \end{itemize}

  \begin{figure}[p]
  \begin{figbox}
    \begin{small}
\begin{verbatim}
LaTeX Mode: Major editing mode for LaTeX and
SLiTeX, with tex-mode underneath.

To create a new LaTeX document, use make-
LaTeX-document (on C-c d), or make-SLiTeX-
document (on C-c s).  With an argument, they
will provide some additional helpful comments.
The functions will prompt for document style
and options.  Type ? to see the standard ones;
you can enter them with name completion.  You
can also enter your own, since it is possible
to have private styles and options unknown to
make-LaTeX-document or make-SLiTeX-document.

The most frequent LaTeX construct is the
\begin{}...\end{} grouping; you can generate
it by LaTeX-begin-end-block (on C-c b).  With
an argument, a helpful comment may be printed.
Type ? to see the standard environments, or
enter your own.  If you type a \begin{...}
manually, you can later generate a matching
\end{...} with the function LaTeX-end (on C-c
n).

Other common constructs are the insertion of
labels, citations, cross-references, index
entries, verbatim strings, and additional
items in a list.  The functions
        C-c .   LaTeX-add-word-to-index
        C-c C-b LaTeX-bibitem
        C-c c   LaTeX-cite
        C-c k   LaTeX-counter
        C-c f   LaTeX-footnote
        C-c x   LaTeX-index
        C-c i   LaTeX-item
        C-c l   LaTeX-label
        C-c m   LaTeX-macro
        C-c p   LaTeX-pageref-with-completion
        C-c C-p LaTeX-protect
        C-c r   LaTeX-ref-with-completion
        C-c v   LaTeX-verb
        C-c d   make-LaTeX-document
        C-c s   make-SLiTeX-document
provide for these.

LaTeX-tab (on C-c TAB) will indent a line to
the current \begin{}...\end{} nesting level.

Most major LaTeX macros can be entered by
LaTeX-macro (on C-c m).  This will supply the
correct set of following braces, brackets, and
parentheses, and with an argument, will insert
a short comment about the expected command
arguments.

For SLiTeX, the function renumber-slides can
be used to put a numbered comment on each
\end{verbatim}
    \end{small}
  \end{figbox}
\caption{Online summary of \LaTeX{} mode.}
\label{fig-latex-mode-1}
\XF{LaTeX-add-word-to-index}
\XF{LaTeX-begin-end-block}
\XF{LaTeX-bibitem}
\XF{LaTeX-cite}
\XF{LaTeX-counter}
\XF{LaTeX-end}
\XF{LaTeX-footnote}
\XF{LaTeX-index}
\XF{LaTeX-item}
\XF{LaTeX-label}
\XF{LaTeX-macro}
\XF{LaTeX-pageref-with-completion}
\XF{LaTeX-protect}
\index{protecting arguments}
\XF{LaTeX-ref-with-completion}
\XF{LaTeX-tab}
\XF{LaTeX-verb}
\XF{make-LaTeX-document}
\XF{make-SLiTeX-document}
\XM{begin}
\XM{end}
  \end{figure}

  \begin{figure}[p]
   \begin{figbox}
    \begin{small}
\begin{verbatim}
slide environment for handy reference in the
\onlynotes{...} and \onlyslides{...} commands.

You can move over \begin{} ... \end{} groups
with LaTeX-to-begin (on C-c a) and
LaTeX-to-end (on C-c e).

Insertion of paired angle brackets, braces,
square brackets, and parentheses is provided
by
        C-c <  LaTeX-angles
        C-c {  LaTeX-braces
        C-c [  LaTeX-brackets
        C-c (  LaTeX-parentheses
With an argument, the last three insert
backslash prefixes for literal braces, math
mode, and displaymath mode.

Unbalanced character pairs are found by
        C-c >  LaTeX-check-angle-balance
        C-c }  LaTeX-check-brace-balance
        C-c ]  LaTeX-check-bracket-balance
        C-c $  LaTeX-check-dollar-balance
        C-c )  LaTeX-check-parenthesis-balance

You can test for undefined labels with
check-LaTeX-labels, display the labels and
their line numbers with show-LaTeX-labels, and
fetch labels from an .aux file with
update-LaTeX-labels.

Environment nesting errors can be caught by
check-LaTeX-nesting.

Use indent-LaTeX-begin-end-groups to get
environments nested for improved visibility.

Use LaTeX-comment (on C-c %) to comment out
the current paragraph (no arg) or region
(arg); undo with M-X undo (C-_).  LaTeX-
uncomment (on C-c u) is the inverse function.

One or more words can be set in any standard
LaTeX font using the commands
        C-c C-c b       LaTeX-font-bf
        C-c C-c e       LaTeX-font-em
        C-c C-c i       LaTeX-font-it
        C-c C-c r       LaTeX-font-rm
        C-c C-c u       LaTeX-font-sc
        C-c C-c f       LaTeX-font-sf
        C-c C-c s       LaTeX-font-sl
        C-c C-c t       LaTeX-font-tt

Please report bugs, comments, and enhancements
by e-mail to
        beebe@math.utah.edu (Internet)
LaTeX-gripe (on C-c g) makes this easier.
\end{verbatim}
    \end{small}
  \end{figbox}
\caption{More about \LaTeX{} mode.}
\label{fig-latex-mode-2}
\index{mail!electronic}\index{e-mail}
\XF{LaTeX-check-angle-balance}
\XF{LaTeX-check-brace-balance}
\XF{LaTeX-check-bracket-balance}
\XF{LaTeX-check-dollar-balance}
\XF{LaTeX-check-parenthesis-balance}
\XF{LaTeX-comment}
\XF{LaTeX-font-bf}
\XF{LaTeX-font-em}
\XF{LaTeX-font-it}
\XF{LaTeX-font-rm}
\XF{LaTeX-font-sc}
\XF{LaTeX-font-sf}
\XF{LaTeX-font-sl}
\XF{LaTeX-font-tt}
\XF{LaTeX-gripe}
\XF{LaTeX-angles}
\XF{LaTeX-braces}
\XF{LaTeX-brackets}
\XF{LaTeX-parentheses}
\XF{LaTeX-to-begin}
\XF{LaTeX-to-end}
\XF{LaTeX-uncomment}
\XF{check-LaTeX-labels}
\XF{check-LaTeX-nesting}
\XF{indent-LaTeX-begin-end-groups}
\XF{show-LaTeX-labels}
\XF{renumber-slides}
\XF{undo}
\XF{update-LaTeX-labels}
\XM{onlynotes}
\XM{onlyslides}
\XM{begin}
\XM{end}
\index{gripe}
\index{complaint}
\index{problem report}
\index{bug report}
\index{reporting bugs}
  \end{figure}

  \begin{figure}[tbh]
   \begin{figbox}
    \begin{small}
\begin{verbatim}
LaTeX-index:
Insert \index{ ... } at point (on C-c x).

If a prefix argument is given, the string is
prompted for, and inserted both as text and as
an index entry, e.g. gnats and
gnus\index{gnats and gnus}.  All horizontal
space preceding \index is removed to prevent
an intervening page break causing an
off-by-one page number error.

If LaTeX-index-start-with-newline is non-nil,
insert a percent to start a comment, then put
\index at the start of a following new line.
If LaTeX-index-end-with-newline is non-nil,
follow the entry with a new line.
\end{verbatim}
    \end{small}
   \end{figbox}
   \caption{Online help for
            \FUNCTION{LaTeX-index}.}
   \XM{index}
   \XV{LaTeX-index-end-with-newline}
   \XV{LaTeX-index-start-with-newline}
   \label{fig-latex-index}
  \end{figure}

  \begin{figure}[p]
    \begin{figbox}
      \begin{small}
\begin{verbatim}
Local Bindings:
key            binding
---            -------

_              LaTeX-subscript
^              LaTeX-superscript
.              LaTeX-dot
,              LaTeX-comma
$              LaTeX-dollar
ESC            Prefix Command
LFD            newline-and-indent
C-c            Prefix Command
"              LaTeX-quote

C-c ,          LaTeX-set-indentation
C-c C-c        Prefix Command
C-c =          LaTeX-equation
C-c }          LaTeX-check-brace-balance
C-c {          LaTeX-braces
C-c x          LaTeX-index
C-c v          LaTeX-verb
C-c u          LaTeX-uncomment
C-c s          make-SLiTeX-document
C-c r          LaTeX-ref-with-completion
C-c p          LaTeX-pageref-with-completion
C-c n          LaTeX-end
C-c m          LaTeX-macro
C-c l          LaTeX-label
C-c k          LaTeX-counter
C-c i          LaTeX-item
C-c g          LaTeX-gripe
C-c f          LaTeX-footnote
C-c e          LaTeX-to-end
C-c d          make-LaTeX-document
C-c c          LaTeX-cite
C-c b          LaTeX-begin-end-block
C-c a          LaTeX-to-begin
C-c 0          renumber-slides
C-c ]          LaTeX-check-bracket-balance
C-c [          LaTeX-brackets
C-c .          LaTeX-add-word-to-index
C-c )          LaTeX-check-parenthesis-balance
C-c (          LaTeX-parentheses
C-c %          LaTeX-comment
C-c $          LaTeX-check-dollar-balance
C-c >          LaTeX-check-angle-balance
C-c <          LaTeX-angles
C-c C-p        LaTeX-protect
C-c C-n        LaTeX-news
C-c TAB        LaTeX-tab
C-c C-b        LaTeX-bibitem

ESC )          forward-list
ESC (          backward-up-list
\end{verbatim}
      \end{small}
    \end{figbox}
    \caption{Local bindings in
             \protect\LaTeX{} mode.}
    \label{fig-bindings-1}
\XF{LaTeX-add-word-to-index}
\XF{LaTeX-begin-end-block}
\XF{LaTeX-bibitem}
\XF{LaTeX-check-angle-balance}
\XF{LaTeX-check-brace-balance}
\XF{LaTeX-check-bracket-balance}
\XF{LaTeX-check-dollar-balance}
\XF{LaTeX-check-parenthesis-balance}
\XF{LaTeX-counter}
\XF{LaTeX-cite}
\XF{LaTeX-comma}
\XF{LaTeX-comment}
\XF{LaTeX-dollar}
\XF{LaTeX-dot}
\XF{LaTeX-end}
\XF{LaTeX-equation}
\XF{LaTeX-footnote}
\XF{LaTeX-gripe}
\XF{LaTeX-index}
\XF{LaTeX-angles}
\XF{LaTeX-braces}
\XF{LaTeX-brackets}
\XF{LaTeX-parentheses}
\XF{LaTeX-quote}
\XF{LaTeX-item}
\XF{LaTeX-label}
\XF{LaTeX-macro}
\XF{LaTeX-news}
\XF{LaTeX-pageref-with-completion}
\XF{LaTeX-protect}
\index{protecting arguments}
\XF{LaTeX-ref-with-completion}
\XF{LaTeX-set-indentation}
\XF{LaTeX-tab}
\XF{LaTeX-to-begin}
\XF{LaTeX-to-end}
\XF{LaTeX-uncomment}
\XF{LaTeX-verb}
\index{prefix command}
\XF{backward-up-list}
\XF{forward-list}
\XF{make-LaTeX-document}
\XF{make-SLiTeX-document}
\XF{newline-and-indent}
\XF{renumber-slides}
\XF{up-list}
\index{_@{\protect\tt\protect\char95}}
\index{^@{\protect\tt\protect\char94}}
\XK{.}
\XK{,}
\XK{$\protect\$$}
\XK{ESCape}
\XK{LFD}
\XK{""}
\XCTL{c}
\XCTLCC{\unskip}
\XCTL{c =}
\XCTL{c $\protect\lbrace$}
\XCTL{c $\protect\rbrace$}
\XCTL{c x}
\XCTL{c v}
\XCTL{c u}
\XCTL{c s}
\XCTL{c r}
\XCTL{c p}
\XCTL{c n}
\XCTL{c m}
\XCTL{c l}
\XCTL{c i}
\XCTL{c g}
\XCTL{c f}
\XCTL{c e}
\XCTL{c d}
\XCTL{c c}
\XCTL{c b}
\XCTL{c a}
\XCTL{c 0}
\XCTL{c [}
\XCTL{c ]}
\XCTL{c .}
\XCTL{c (}
\XCTL{c )}
\XCTL{c $\protect\%$}
\XCTL{c $\protect\$$}
\XCTL{c {\protect\tt >}}
\XCTL{c {\protect\tt <}}
\XCTL{c C-n}
\XCTL{c Tab}
\XCTL{c C-b}
\XCTL{c C-r}
\XCTL{c C-p}
\XCTL{c C-q}
\XCTL{c C-l}
\XCTL{c C-k}
\XK{ESCape (}
\XK{ESCape )}
\XK{ESCape {\protect\{\unskip}}
\XK{ESCape {\protect\}\unskip}}
\XMETA{(}
\XMETA{)}
\XMETA{{\protect\{\unskip}}
\XMETA{{\protect\}\unskip}}
\index{gripe}
\index{complaint}
\index{problem report}
\index{bug report}
\index{reporting bugs}
  \end{figure}

  \begin{figure}[p]
    \begin{figbox}
      \begin{small}
\begin{verbatim}
C-c C-c t      LaTeX-font-tt
C-c C-c s      LaTeX-font-sl
C-c C-c f      LaTeX-font-sf
C-c C-c u      LaTeX-font-sc
C-c C-c r      LaTeX-font-rm
C-c C-c i      LaTeX-font-it
C-c C-c e      LaTeX-font-em
C-c C-c b      LaTeX-font-bf
C-c C-c }      LaTeX-check-brace-balance
C-c C-c ]      LaTeX-check-bracket-balance
C-c C-c )      LaTeX-check-parenthesis-balance
C-c C-c $      LaTeX-check-dollar-balance
C-c C-c =      LaTeX-displaymath
\end{verbatim}
      \end{small}
    \end{figbox}
    \caption{More local bindings.}
    \label{fig-bindings-2}
\XF{LaTeX-font-tt}
\XF{LaTeX-font-sl}
\XF{LaTeX-font-sf}
\XF{LaTeX-font-sc}
\XF{LaTeX-font-rm}
\XF{LaTeX-font-it}
\XF{LaTeX-font-em}
\XF{LaTeX-font-bf}
\XF{LaTeX-check-brace-balance}
\XF{LaTeX-check-bracket-balance}
\XF{LaTeX-check-parenthesis-balance}
\XF{LaTeX-check-dollar-balance}
\XF{LaTeX-displaymath}
\XCTLCC{t}
\XCTLCC{s}
\XCTLCC{f}
\XCTLCC{u}
\XCTLCC{r}
\XCTLCC{i}
\XCTLCC{e}
\XCTLCC{b}
\XCTLCC{$\protect\rbrace$}
% [ match
\XCTLCC{]}
% ( match
\XCTLCC{)}
\XCTLCC{$\protect\$$}
\XCTLCC{=}
  \end{figure}

\section{\protect\LaTeX{} support}
\label{latex-support}

Now that you understand how Emacs works, we can
move on to a discussion of the \LaTeX{} editing
support.  The material that you are now reading is
contained in the distribution as two files,
\FILE{ltxmode.ltx} for the \TUB{} article, and
\FILE{ltxinfo.ltx} for \LaTeX{}info.

\subsection{Preliminaries}

The first job is to arrange for
\FUNCTION{LaTeX-mode} to be selected automatically
when required.

Because the \FILE{latex.el} file of Lisp%
\index{Lisp!GNU Emacs}
code is not yet a standard part of the GNU Emacs
distribution, its association with particular file
extensions is unknown to Emacs.  To remedy that,
the Lisp code in
% Page break happens just above, so this ref
% is typeset on previous page, then moved onto
% this one, giving a ref to the current page
\FIGREF{fig-startup-code}
% Figure~\ref{fig-startup-code}
\typeout{====> Check page cross-reference to Figure 6}%
should be inserted into the
\FILE{.emacs} file%
\index{startup file}
in your login directory; that file is processed
each time Emacs starts up.  The \FUNCTION{load}
command there tells where \FILE{latex.el} is
found; it may need adjustment for your system.

  \begin{figure}[tbhp]
   \begin{figbox}
    \begin{small}
\begin{verbatim}
;=============================================
; Add mode for .ltx files if not there already
; for most people: (load-library "latex.el")
; for my private version:
; Force tex-mode.el to be loaded so latex.el
; can override it.
(load-library "tex-mode")
(load "~/emacs/latex" t t nil)
(if (not (assoc "\\.ltx$" auto-mode-alist))
    (setq auto-mode-alist
          (cons (cons "\\.ltx$" 'LaTeX-mode)
                auto-mode-alist)))
(if (not (assoc "\\.stx$" auto-mode-alist))
    (setq auto-mode-alist
          (cons (cons "\\.stx$" 'LaTeX-mode)
                auto-mode-alist)))
(if (not (assoc "\\.sty$" auto-mode-alist))
    (setq auto-mode-alist
          (cons (cons "\\.sty$" 'LaTeX-mode)
                auto-mode-alist)))

;=============================================
; Private letter support
(load "~/emacs/letter" t t nil)
\end{verbatim}
    \end{small}
  \end{figbox}
\caption{\FILE{.emacs} file additions.}
\label{fig-startup-code}
\XF{LaTeX-mode}
\XF{load}
\XV{auto-mode-alist}
  \end{figure}

The peculiar \FUNCTION{if} commands attach
\FUNCTION{LaTeX-mode} to the
\VARIABLE{auto-mode-alist} variable, which is a
list of pairs of file extensions and their mode
names; the attachment is omitted if the file
extensions are already in the list.

Once this startup code has been executed, Emacs
will automatically select \FUNCTION{LaTeX-mode}
when you visit files with extensions%
\index{file extensions}
\FILE{.ltx}
(\LaTeX{} document), \FILE{.stx} (\SliTeX{}
document), or \FILE{.sty} (\LaTeX{} style).
Others can be easily added according to taste.
File extension \FILE{.tex} is already attached to
GNU Emacs \FUNCTION{tex-mode} which comes with
the system, so different extensions are needed
for different editing modes.

If you don't have these associations of file
extensions with editing modes in effect, you can
always select the mode manually with the
command \METAX{LaTeX-mode}.

Experienced Emacs users may wonder why the
\FUNCTION{autoload} facility is not used instead
of the explicit \FUNCTION{load} command in the
startup file; the reason lies in a conflict with
the standard \FUNCTION{tex-mode}.  I expect that
conflict will be removed when \FILE{latex.el}
becomes part of the standard GNU Emacs
distribution.  A modification of
\FILE{tex-mode.el} that eliminates all
\LaTeX{}-specific code has been prepared locally,
and that new version removes the incompatibility
with \FILE{latex.el}, allowing \FUNCTION{autoload}
to be used.

In GNU Emacs Lisp, named functions, and variables
defined outside functions, are known globally.
There is no provision for file scoping or mode
scoping to limit name visibility.%
\index{visibility of names}%
\index{scope of names}
Consequently,
to avoid collision with the thousands of names
from other libraries, each library usually
includes a distinctive phrase in its global names.
Naturally enough, {\sf LaTeX} and {\sf SLiTeX} are
the phrases chosen in \FILE{latex.el}.  They are
almost always used as prefixes%
\index{name prefix}%
\index{prefix in name}
in variable names, and
usually also in function names, although a few
functions have embedded phrases for better
readability
(e.g.\ \FUNCTION{show-LaTeX-labels}).%
\index{conventions for naming}%
\index{naming conventions}

\subsection{Creating a new \protect\LaTeX{} file}

When you visit a new \LaTeX{} file, Emacs starts
up with an empty buffer.  The \X{mode line} at the
bottom of the screen will look something like

  \begin{small}
\begin{verbatim}
---Emacs: foo.ltx (LaTeX Abbrev Fill)----All---
\end{verbatim}
  \end{small}

\noindent
The first thing you want to do is get a standard
template of a \LaTeX{} file inserted; you do this
by typing \CTL{c d}
(\FUNCTION{make-LaTeX-document}).  This function
will first prompt you with

  \begin{small}
\begin{verbatim}
Document style:
\end{verbatim}
  \end{small}

\noindent
to which you can respond either with a complete
\X{style file} name, or with the first few
characters of a standard style, followed by a
\X{space} to request Emacs to complete the name,
and a \KEY{RETurn} to accept the completion.%
\index{completion}%
\index{command completion}
If you are unsure of what to supply, just type a
\X{query} (\X{?}); Emacs will respond with
something like

  \begin{small}
\begin{verbatim}
Possible completions are:
aaai                               amsart
amsbook                            amstex
aps                                article
book                               deproc
letter                             ltugproc
refman                             report
siam                               slides
tugboat                            ucthesis
uoftoronto                         usafmemo
uuthesis                           xxxslides
\end{verbatim}
  \end{small}

\noindent
Completion can also be requested on partial
names: the input \TYPEIN{a?}\ in the above
command will respond with

  \begin{small}
\begin{verbatim}
Possible completions are:
aaai                               amsart
amsbook                            amstex
aps                                article
\end{verbatim}
  \end{small}

\noindent
Suppose you type \TYPEIN{article} or
\TYPEIN{ar\protect\SPACE}, followed by a
\KEY{RETurn}.  Then Emacs will respond with

  \begin{small}
\begin{verbatim}
Document option (RET when done):
\end{verbatim}
  \end{small}

\noindent
to which you can then supply an option name
followed by a \KEY{RETurn}.  As before, a
\X{query} will show you what is available:%
\index{option}

  \begin{small}
\begin{verbatim}
Possible completions are:
11pt                               12pt
a4                                 a4wide
acm                                acronym
agugrl                             agujgr
alltt                              amsbsy
amscd                              amsfonts
amssymb                            amssymbols
amstext                            apalike
archmemo                           array
bezier                             biihead
boxedmini                          changebar
chapterbib                         cite
clsc                               clscmemo
concrete                           cropmark
ctagsplt                           cyrillic
dblspace                           doublespace
draft                              drafthead
drop                               dvidoc
eqsecnum                           espo
fleqn                              format
fullpage                           geophysics
german                             gnuindex
ifthen                             intlim
ist21                              leqno
listing                            longtab
ltugboat                           makeidx
math                               merge
mfr                                mitthesis
moretext                           natsci
nl                                 nonamelm
nopageno                           nosumlim
openbib                            pandora
preprint                           proc
psmavg                             psmbkm
psmncs                             psmpal
psmtim                             remark
resume                             revtex
righttag                           sc21
sc21-wg1                           sfwmac
showidx                            showlabels
slem                               spacecites
supertab                           suthesis
tablisting                         tapeseal
texindex                           texnames
tgrind                             theorem
thp                                threepart
titlepage                          trademark
troffman                           troffms
twocolumn                          twoside
underline                          uofutah
vdm                                verbatim
\end{verbatim}
  \end{small}

\noindent
You can keep on selecting options until you
finally just type a bare \KEY{RETurn}, at which
point \FUNCTION{make-LaTeX-document}
completes, and you have a buffer that looks like
this:

  \begin{small}
\FIXVERB{}
\begin{verbatim}
% -*-latex-*-
% Document name: /u/beebe/foo.ltx
% Creator: Nelson Beebe [beebe@math.utah.edu]
% Creation Date: Sun Jul 28 08:44:46 1991
\documentstyle[11pt,makeidx]{article}
\newcommand{\X}[1]{{#1}\index{{#1}}}
\end{verbatim}
\verb|\|\verb|begin{document}|\par
\CURSOR\par
\verb|\|\verb|end{document}|
\XM{documentstyle}
\XM{newcommand}
\XM{begin\protect\BRACED{document}}
\XM{end\protect\BRACED{document}}
  \end{small}

\noindent
The cursor, represented by \CURSOR{}, is left
positioned on the line following the
\MACROX{begin\protect\BRACED{document}}, ready
for text entry.

The initial comment with the tag
\verb|-*-latex-*-| is a special one.  It requests
an automatic mode selection when the file is
freshly visited in Emacs, overriding any mode that
might otherwise be selected based on the file name
extension.  \FUNCTION{latex-mode} is made
equivalent to \FUNCTION{LaTeX-mode} in
\FILE{latex.el} so that the comment tag can be
written in lower-case letters, as is conventional.

  \begin{sloppypar}
The \verb|% Creator:| comment information is
obtained from Emacs' operating system interface,
which in turn fetches the user's \X{personal name}
and \X{login name} from system authorization
files.  On networked systems, the \X{hostname} is
included as well, creating a valid electronic
mail%
\index{mail!electronic}\index{e-mail}
address.
  \end{sloppypar}

Had you given \FUNCTION{make-LaTeX-document} an
argument, it would have been somewhat more
verbose:

  \begin{small}
\FIXVERB{}
\begin{verbatim}
% -*-latex-*-
% Document name: /u/beebe/tex/tugboat/foo.ltx
% Creator: Nelson Beebe [beebe@math.utah.edu]
% Creation Date: Sun Jul 28 08:46:33 1991
%----------------------------------------------
% EVERYTHING TO THE RIGHT OF A  %  IS A REMARK
% TO YOU AND IS IGNORED BY LaTeX.
%
% WARNING!  DO NOT TYPE ANY OF THE FOLLOWING 10
% CHARACTERS AS NORMAL TEXT CHARACTERS:
%       &   $   #   %   _    {   }   ^   ~   \
%
% The following seven are printed by typing a
% backslash in front of them:
%       $  &  #  %  _  {  and  }.
%----------------------------------------------
\documentstyle[11pt,makeidx]{article}
\newcommand{\X}[1]{{#1}\index{{#1}}}
\begin{document}
\end{verbatim}
\CURSOR\par
\begin{verbatim}
\end{document}
\end{verbatim}
\XM{documentstyle}
\XM{newcommand}
\XM{begin\protect\BRACED{document}}
\XM{end\protect\BRACED{document}}
  \end{small}

\noindent
The extra commentary is a useful reminder for
beginning \LaTeX{} users.  Several other commands
in \FUNCTION{LaTeX-mode} use the presence of an
argument to supply additional helpful
commentary.

The \MACROX{X}%
\label{X-command}
command is one I have found helpful for preparing
indexes; typing \verb|\X{gnats and gnus}|%
\index{gnats and gnus}
will put that phrase in both the document and the
index.  Further discussion is given in the {\bf
Indexing} section beginning on \PAGEREF{indexing}.

The lists of standard styles and options%
\index{option}
are
embedded in the \FILE{latex.el} code.  They cannot
be determined automatically from the file system
for several reasons:
  \begin{itemize}
    \item
          Some options (e.g.\ \verb|11pt|) do not
          have a corresponding
          \X{style file}.
    \item
          Some
          \X{style file}s do not represent a
          valid option (e.g.\ \FILE{art10.sty}).
    \item
          Some
          \X{style file}s found in the normal
          \VARIABLE{TEXINPUTS} search path belong
          to other systems, such as \AmSTeX{}.
    \item
          It is impossible to distinguish from the
          \FILE{.sty} file extension whether the
          file represents a major document style,
          or merely an
          \X{option}
          that modifies a major style.
  \end{itemize}

It is regrettable that these difficulties exist,
because they confuse users, as well as programmers
of code like \FUNCTION{LaTeX-mode}.  It is often
difficult to tell from its contents whether a
particular file is a major style, or just a
document
\X{option}.  It would have been wiser in the
initial \LaTeX{} design to have chosen distinctive
file extensions, and for each style and option to
be associated with a unique file.

The present collection of twenty available styles
and over one hundred options is daunting for a
novice, particularly since many options can only
be used with certain styles.  Eventually I may
find a satisfactory way to deal with this,
and offer a better presentation of choices in the
completion%
\index{completion}%
\index{command completion}
lists.

The style and
\X{option} lists can be easily extended;
see {\bf Customizing lists} on
\PAGEREF{customizing-lists} for details.

\subsection{\protect\LaTeX{} macros}

Every one of the 589 \LaTeX{} \X{macros} in the
index to the {\em \LaTeX{} User's Guide and
Reference Manual\/}
\cite{Lamport:latex}%
\index{Lamport, Leslie}
is known to the
function \FUNCTION{LaTeX-macro} (on \CTL{c m}),
and as before, Emacs command completion%
\index{completion}%
\index{command completion}
is
available with the \X{query} (?) and \X{space}
(\SPACE) characters.  Thus, you can type
  \begin{itemize}
    \item
          \CTL{c m longr\protect\SPACE}
          \KEY{RETurn} to get
          \MACROX{longrightarrow};

    \item
          \CTL{c m em} \KEY{RETurn} to get

 \begin{small}
 \noindent
 \verb|{\em |\CURSOR{}
\begin{verbatim}
\/}
\end{verbatim}
 \end{small}

          \noindent
          with the \X{cursor} positioned ready for
          you to enter some text;

    \item

           \CTL{u} \CTL{c m
          newcom\protect\SPACE} \KEY{RETurn} to
          get

            \begin{small}
          \noindent
\verb|\newcommand{|\CURSOR{}
\begin{verbatim}
}[]{} % {\cmd}[n]{def} define new command
      % with n arguments
\end{verbatim}
            \end{small}

    \item

          \CTL{c m e?} to find the names of macros
          that begin with \KEY{e}:

            \begin{small}
\begin{verbatim}
Possible completions are:
ell                            em
emptyset                       encl
end                            epsilon
equiv                          eta
evensidemargin                 exists
exp                            extracolsep
\end{verbatim}
            \end{small}

 \end{itemize}

When the \X{cursor} is left after an open brace in
a generated command, the closing brace is by
default placed at the start of the next line so
that you have a clean line to type on.  This
reduces visually-distracting screen updates, but
means that you will need to delete the end-of-line
character when you finish typing the argument.  If
you don't like this behavior, you can set the
Emacs variable
\VARIABLE{LaTeX-newline-after-opening-delimiter}
to a \CONSTANT{nil} value, usually in your
\FILE{.emacs}\index{startup file} startup file:

  \begin{small}
\begin{verbatim}
(setq LaTeX-mode-hook
 '(lambda ()
    (setq LaTeX-newline-after-opening-delimiter
          nil)
    )
 )
\end{verbatim}
\XV{LaTeX-mode-hook}
\XF{lambda}%
\index{hook}
  \end{small}

\noindent
The variable
\VARIABLE{LaTeX-newline-after-closing-delimiter}
is used similarly for brace pairs inserted on
their own, or after certain macros.

A {\em \X{mode hook}\/}%
\label{mode-hook}%
\index{hook}
is Lisp%
\index{Lisp!GNU Emacs}
code to be executed whenever the corresponding
mode function is executed.  The hook is called
just before the mode function returns, so it can
override anything that the function did.  The
peculiar \verb|lambda ()|%
\XF{lambda}
is the Lisp way of declaring a nameless function.
The single quote prefixing it means that
\VARIABLE{LaTeX-mode-hook} will be assigned the
function itself, and not the value returned by the
function.

In GNU Emacs,%
\index{Lisp!GNU Emacs!executing}
you can execute Lisp code in a file through
\METAX{load-file} and \METAX{load-library}
commands.  Inline code must be executed in a
buffer which is in \FUNCTION{emacs-lisp-mode}.
The \X{minibuffer} always has that mode, and can
be temporarily accessed with the
\FUNCTION{eval-expression} function bound to
\KEY{ESCape ESCape}.

If you just want to set an Emacs variable, you can
also use the command \METAX{set-variable}; it
supports completion%
\index{completion}%
\index{command completion}
on the variable name, and
prompts for the value.

The availability of all of the \LaTeX{} macros
with \FUNCTION{LaTeX-macro} reduces the likelihood
of spelling mistakes, and the command completion%
\index{completion}%
\index{command completion}
usually means that only a few leading characters
need to be typed.  The complete macro name is
entered in the buffer:
\MACROX{abovedisplayshortskip} is much more
readable than a cryptic \verb|\adss| that \LaTeX{}
users without such editing support might be
inclined to define as a private macro%
\index{macros!private}
to save typing effort.

If you have frequently-used private macros,%
\index{macros!private}
there is a convenient way to make them known to
\FUNCTION{LaTeX-mode}.  See the section {\bf
Customizing lists} on
\PAGEREF{customizing-lists} for details.

\subsection{\protect\LaTeX{} environments}

\begin{sloppypar}
An important concept in \LaTeX{} is the notion of
{\em \X{environment}s}, which are marked by
surrounding \MACROX{begin}\verb|{...}|
and
\MACROX{end}\verb|{...}| commands.  The
braced tag must be repeated, and if the tag name
is long, spelling errors are more likely.  The
function \FUNCTION{LaTeX-begin-end-block} on
\CTL{c b} generates the command pair, indented
according to the current
\X{nesting level}, and leaves
the \X{cursor} on the line between them.  The
indentation is controlled by the value of the
Emacs variable
\VARIABLE{LaTeX-begin-end-indentation}\/; the
default is two spaces.

If the variable
\VARIABLE{LaTeX-space-after-begin-end} is
non-\CONSTANT{nil}, a space will be inserted
between the keyword and the following opening
brace.  The default value is \CONSTANT{nil}.  This
formatting style is discouraged, because it cannot
be applied uniformly; it must be suppressed for
the \verb|verbatim| environment.  The code in
\FILE{latex.el} knows about this vagary, and
always omits the space for that environment.

The keystrokes
\CTL{c b quote} \KEY{RETurn}
\CTL{c b ite\protect\SPACE} \KEY{RETurn}
\CTL{c b verb\protect\SPACE} \KEY{RETurn}
produce
\end{sloppypar}

  \begin{small}
\FIXVERB{}
\begin{verbatim}
  \begin{quote}
    \begin{itemize}
      \item
\end{verbatim}
\verb|\begin{verbatim}|\par
\CURSOR\par
\verb|\end{verbatim}|\par
\begin{verbatim}
      \item
      \item
      \item
    \end{itemize}
  \end{quote}
\end{verbatim}
\XM{begin\protect\BRACED{quote}}
\XM{end\protect\BRACED{quote}}
\XM{begin\protect\BRACED{itemize}}
\XM{end\protect\BRACED{itemize}}
\XM{begin\protect\BRACED{verbatim}}
\XM{end\protect\BRACED{verbatim}}
\XM{item}
  \end{small}

  \begin{sloppypar}
\noindent
with the \X{cursor} inside the \verb|verbatim|
environment.  Notice that the normal indentation
is automatically suppressed for that environment;
the command knows that leading spaces in front of
\MACROX{end\protect\BRACED{verbatim}} would
otherwise generate an unwanted blank line in the
typeset output.
  \end{sloppypar}

If you have private environments,%
\index{environment!private}
you can still use \CTL{c b}; you just have to type
the complete environment name.  If you use some
private ones frequently in different documents,
it is possible to extend the list of
environments known to \FUNCTION{LaTeX-mode}.
See the section {\bf Customizing lists} on
\PAGEREF{customizing-lists} for details.

In those environments that have \MACROX{item}
commands, four are generated by default; that
number can be changed by modifying the value of
the Emacs variable \VARIABLE{LaTeX-item-count}.
Their indentation is defined by the variable
\VARIABLE{LaTeX-item-indentation}\/; the default
is two spaces.  Additional indentation of text
under a \MACROX{item} command is set by the
variable \VARIABLE{LaTeX-item-info-indent}\/; the
default is six spaces.

You can generate additional \MACROX{item} commands
as needed with the function \FUNCTION{LaTeX-item}
on \CTL{c i}.  With an argument, it supplies the
alternate form \MACROX{item[]} instead.

If you forgot about the \CTL{c b} command, and
manually typed a
\MACROX{begin\protect\BRACED{conjecture}}, you
can get the matching
\MACROX{end\protect\BRACED{conjecture}}
generated automatically by typing \CTL{c n}
(\FUNCTION{LaTeX-end}).  That is also sometimes
helpful when you have forgotten%
\index{environment!forgotten}
what environment you are in: you can generate the
\MACROX{end}\verb|{...}|, and then kill it.

You can type \CTL{c a} (\FUNCTION{LaTeX-to-begin})
to move backward to the enclosing \MACROX{begin};
with an argument, you can move backward over a
specified number of
\MACROX{begin}\verb|{...}|s.  If the
argument is negative, you move forward over
\MACROX{end}\verb|{...}|s instead.
Usually, you would use \CTL{c e}
(\FUNCTION{LaTeX-to-end}) instead to move forward
over \MACROX{end}\verb|{...}|s; that
command handles numeric arguments too, and
reverses direction for negative arguments.

These two movement commands are analogous to
the standard Emacs commands for moving backward
and forward in sentences, normally bound to
\META{a} and \META{e}.  They also require that
the \MACROX{begin} and \MACROX{end} macros be
preceded on their lines only by optional
whitespace, and immediately followed by open
braces.  This helps to enforce the discipline
of keeping the
\MACROX{begin}\verb|{...}| \ldots{}
\MACROX{end}\verb|{...}|
grouping properly nested and
readable, and also avoids having to deal
with more complex input parsing.

\subsection{Common commands}

\index{macros!common}

Some \LaTeX{} macros are used so often that it
is desirable to have them bound directly to keys,
instead of having to type their first few
characters with \FUNCTION{LaTeX-macro} as
described earlier.  You can find a list of these
convenience functions in the fourth
paragraph of \FIGREF{fig-latex-mode-1}.

For example, typing \CTL{c l} (that's the letter
`l') generates

  \begin{small}
\noindent
\verb*|~\label{|\CURSOR{}
\begin{verbatim}
}
\end{verbatim}
\XM{label}
  \end{small}

\noindent
at the \X{cursor} position, leaving the cursor
after the open brace.

\subsection{Math mode}

\index{math mode}

\TeX{}'s math mode uses paired \X{dollar sign}s to
delimit the math text.  Single dollar signs mark
\X{inline math}, and doubled ones mark \X{display
math}.  If you forget to type a closing dollar
sign, or type the wrong number of dollar signs,
\TeX{} will complain bitterly.

The start and finish of these math regions are
indistinguishable, making it hard for simple
programs (and sometimes, readers) to distinguish
the `inside' from the `outside'.

  \begin{sloppypar}
Consequently, \LaTeX{} additionally supports two
bracketing forms:
\MACROX{(} \ldots{} \MACROX{)} for
\verb|$ ... $|,%
\index{$ ... $@\protect\verb"|$ ... $"|}
and
\MACROX{[} \ldots{} \MACROX{]} for
\verb|$$ ... $$|,%
\index{$$ ... $$@\protect\verb"|$$ ... $$"|}
as well as more readable forms

  \begin{small}
\begin{verbatim}
  \begin{math}
  ...
  \end{math}

  \begin{displaymath}
  ...
  \end{displaymath}
\end{verbatim}
  \end{small}

\noindent
for the single and double \X{dollar sign} pairs,
respectively.  All of these have unique opening
and closing sequences.
  \end{sloppypar}

  \begin{sloppypar}
\FUNCTION{LaTeX-mode} supports all of these forms.
The variants selected are determined by the
variables \VARIABLE{LaTeX-math-option} and
\VARIABLE{LaTeX-displaymath-option}.  Values of 0,
1, and 2 select the dollar,%
\index{dollar sign}
\X{backslash}ed delimiter,
and \MACROX{begin}\verb|{...}| \ldots{}
\MACROX{end}\verb|{...}| environment forms
respectively; all other values are equivalent to
0.  The default values select the single dollar
and \verb|displaymath| forms.%
\index{display math}
  \end{sloppypar}

Normally, when you type a \X{dollar sign}, you get
an \X{inline math} environment.  If the dollar
sign happens to be at the beginning of a line, it
expands instead into a display%
\index{display math}
environment.  On
the other hand, if the preceding character was a
\X{backslash}, you just get a plain dollar sign.

Spacing around the inserted text is controlled by
two more variables. If
\VARIABLE{LaTeX-newline-after-opening-delimiter}
is non-\CONSTANT{nil} (the default), the opening
delimiter is followed by a newline, with the
\X{cursor} positioned immediately after the
delimiter for the inline%
\index{inline math}
case, and on a new line for the
display%
\index{display math}
form.  If
\VARIABLE{LaTeX-newline-after-closing-delimiter}
is non-\CONSTANT{nil} (the default), the closing
delimiter is followed by a newline.

This pleasantness is our first example of having
an alternate function bound to a normal printing
character.  Instead of running the usual
\FUNCTION{self-insert-command} attached to
printing characters, \verb|$| is bound
to \FUNCTION{LaTeX-dollar} which has been
programmed to deal with the three different
meanings of the \X{dollar sign}.  Few editors
outside the Emacs family could do this; the
critical feature is that {\em any character\/} can
run {\em any function}.

What if you really just wanted a single plain
\X{dollar sign}, with no preceding \X{backslash}?
Well, that is easy.  In Emacs, any character can
be {\em quoted}, which causes it to be inserted
directly into the buffer; the
\FUNCTION{quoted-insert} function is normally
bound to \CTL{q}, but that too can be changed.
Thus, \CTL{q $\protect\$$}
% use math mode there to fix spacing problem in output
will get you a
\X{literal} \X{dollar sign}, if that is
what you really want.

The function \FUNCTION{LaTeX-equation} on
\CTL{c =} generates

  \begin{small}
\FIXVERB{}
\begin{verbatim}
  \begin{equation}
\end{verbatim}
\CURSOR\par
\begin{verbatim}
  \end{equation}
\end{verbatim}
\XM{begin\protect\BRACED{equation}}
\XM{end\protect\BRACED{equation}}
  \end{small}

\noindent
with the \X{cursor} between them.
\FUNCTION{LaTeX-displaymath}%
\index{display math}
on \CTLCC{=} inserts

  \begin{small}
\FIXVERB{}
\begin{verbatim}
  \begin{displaymath}
\end{verbatim}
\CURSOR\par
\begin{verbatim}
  \end{displaymath}
\end{verbatim}
\XM{begin\protect\BRACED{displaymath}}
\XM{end\protect\BRACED{displaymath}}
  \end{small}

  \begin{sloppypar}
All math mode environments
(\verb|array|,
\verb|eqnarray*|,
\verb|eqnarray|,
\verb|math|, and
\verb|theorem|)
can be also generated by
\FUNCTION{LaTeX-begin-end-block} on \CTL{c b}, and
additional ones can be easily added; see {\bf
Customizing lists} on \PAGEREF{customizing-lists}.
  \end{sloppypar}

\FUNCTION{LaTeX-subscript} on \KEYNX{\tt\char95}%
\index{_@{\protect\tt\protect\char95}}
and \FUNCTION{LaTeX-superscript} on
\KEYNX{\char94}%
\index{^@{\protect\tt\protect\char94}}
generate braced \X{subscript} and \X{superscript}
sequences, leaving the \X{cursor} between the
braces \cite{vonBechtolsheim:TQ7-195}.%
\index{von Bechtolsheim, Stephan}

\subsection{Dots, commas, and quotation marks}

The \X{dot} or \X{period} (\X{full stop}, to some
of you) is an overloaded character.  Normally, it
just means end of sentence.%
\index{end of sentence}
\index{sentence end}
Sometimes, it ends an
\X{abbreviation} in the middle of a sentence.  It
can also be a decimal point, as in 3.14159.  Still
other times, it appears in ellipses,%
\index{ellipsis}
as in $\cdots$ (\MACROX{cdots}), $\smash{\ddots}$
(\MACROX{ddots}), \ldots{} (\MACROX{ldots}),
and $\smash{\vdots}$ (\MACROX{vdots}).

In typography, these uses are distinguished by
small changes in spacing after the dots.  That is
why \TeX{} provides control sequences for the
ellipses, and the \LaTeX{} book
\cite[p.~14]{Lamport:latex}%
\index{Lamport, Leslie}
recommends that you type a \verb*|\ | sequence
after a \X{period} that does not end a sentence.%
\index{end of sentence}
\index{sentence end}

\TeX{} assumes that a \X{period} following an
upper-case letter does not end a sentence%
\index{end of sentence}
\index{sentence end}
(it might be someone's initial)
\cite[pp.~74, 311]{Knuth:texbook},%
\index{Knuth, Donald. E.}
and follows it with a smaller amount of space.
The {\em \LaTeX{} User's Guide and Reference
Manual} recommends insertion of
\MACRO{@}\index{"@@\protect\MACRO{"@}}
before a sentence-ending%
\index{end of sentence}
\index{sentence end}
dot that follows an
upper-case letter in order to get additional
space after the dot.

\FUNCTION{LaTeX-mode} handles these intricacies by
binding dot to the function \FUNCTION{LaTeX-dot}.
That function examines what is immediately before
the dot in the buffer, and takes one of several
actions:

  \begin{itemize}
    \item
          If the dot ends an \X{ellipsis}, the
          three dots are replaced by
          \MACROX{ldots}\BRACED{}.
    \item
          If the dot is preceded by an \X{italic
          correction} at group end,
          \MACROX{/}\verb|}|, the italic
          correction is removed.
    \item
          If the dot ends an \X{abbreviation},
          like {\em e.g.} or {\em i.e.}, it
          inserts a \verb*|\ | command or a
          \X{comma}, depending on whether the
          variable
          \VARIABLE{LaTeX-comma-after-dotted-abbreviation}
          is \CONSTANT{nil} or non-\CONSTANT{nil}.
          Traditionally, such abbreviations are
          followed by a \X{comma}, but modern
          tendency is to omit the comma
          \cite[p.~84]{Shertzer:grammar},%
          \index{Shertzer, Margaret}
          although Knuth disagrees
          \cite[p.~74]{Knuth:texbook}.%
          \index{Knuth, Donald. E.}

    \item
          If the previous characters are
          \X{abbreviation}s like {\em Fig.},
          {\em cf.}, {\em vs.}, and
          {\em resp.}~\cite[p.~74]{Knuth:texbook}%
          \index{Knuth, Donald. E.}
          \cite[p.~18]{Lamport:latex}%
          \index{Lamport, Leslie}
          that should be tied to the following
          word with a single unbreakable space,
          the function inserts a \X{tilde}
          to mark the \X{tie}.
          \index{~@{\tt \char`\~}}

    \item
          If the dot follows two or more
          upper-case letters, the dot is prefixed
          by
          \MACRO{@}\index{"@@\protect\MACRO{"@}}.

  \end{itemize}

To prevent confusion with words at end of
sentence,%
\index{end of sentence}
\index{sentence end}
\X{abbreviation}s are not recognized if they
are immediately preceded by a letter in the
editing buffer.

  \begin{sloppypar}
The \X{abbreviation}s known to
\FUNCTION{LaTeX-dot} are defined by the variable
\VARIABLE{LaTeX-standard-dotted-abbreviations}.
More can be added by a suitable definition of the
variable
\VARIABLE{LaTeX-extra-dotted-abbreviations}, such
as this example:
  \end{sloppypar}

    \begin{small}
\begin{verbatim}
(setq LaTeX-extra-dotted-abbreviations
      '(
        ("ad. lib.")
        ("cwt.")
        ("q.e.d.")
        )
      )
\end{verbatim}
    \end{small}

\noindent
See {\bf Customizing lists} on
\PAGEREF{customizing-lists} for more details.

The \X{abbreviation}s for which \X{tie}s are
supplied are similarly defined by the variables
\VARIABLE{LaTeX-standard-tied-abbreviations} and
\VARIABLE{LaTeX-extra-tied-abbreviations}.

\FUNCTION{LaTeX-dot} cannot tell whether a dot
following an upper-case letter is a
sentence-ending%
\index{end of sentence}
\index{sentence end}
one or not, so it only inserts
\MACRO{@}\index{"@@\protect\MACRO{"@}}
before a dot if there are {\em two or more}
preceding upper-case letters.  It is up to the
user to remember to insert
\MACRO{@}\index{"@@\protect\MACRO{"@}}
in the exceptional case of a single final
upper-case letter.

What about a dot after a macro that expands to a
word ending in an upper-case letter, like \TeX{}
itself?  No
\MACRO{@}\index{"@@\protect\MACRO{"@}}
is necessary there, because \TeX{} treats that dot
as a normal end of sentence.%
\index{end of sentence}
\index{sentence end}

    \begin{sloppypar}
These actions cover most of the common cases, but
of course, for \X{abbreviation}s, cannot be
omniscient.  Dictionaries that I consulted listed
over a thousand abbreviations%
\index{abbreviations!number of in English}
in use in English.  Fewer than a dozen of the
commonest ones are included in
\VARIABLE{LaTeX-standard-dotted-abbreviations},
but customization of
\VARIABLE{LaTeX-extra-dotted-abbreviations}
provides a way to add new ones.
    \end{sloppypar}

Emacs' \FUNCTION{quoted-insert} function saves the
day when you want to suppress all of this
wizardry; just type \CTL{q\protect\nolinebreak\ .}
to get a
\X{literal} dot inserted.

\FUNCTION{LaTeX-comma} bound to \X{comma} removes
any immediately preceding \X{italic correction},
and then inserts a \X{comma}.

Italic corrections%
\index{italic correction}
are somewhat of a nuisance, since you are supposed
to have them after italicized text, {\em except\/}
a \X{period} or a \X{comma}, which are so low that
it doesn't matter if the character to their
immediate left leans over them.  Those two
exceptions make it hard to write a \TeX{} macro to
determine whether the correction is needed or not.
I'd rather let Emacs remember for me, so I
programmed it to do so.

Good typography uses different opening and closing
quotation marks;
\index{quotation!mark}
in \TeX{}, you get ``quoted
text'' by typing \TYPEIN{``quoted text''}.%
\label{quote}
Because many people are accustomed to using the
double quotation mark character, \verb|"|, found
on computer keyboards and typewriters, the
function \FUNCTION{LaTeX-quote} is bound to
that character.  It generates the correct paired
opening
\X{grave accent}s,%
\index{opening apostrophe}
\verb|``|, or
\X{closing apostrophe}s,%
\index{apostrophe}
\verb|''|, as appropriate: the input
\TYPEIN{"quoted text"} expands to \TYPEIN{``quoted
text''} in the edit buffer. With an argument,
the function inserts a bare double quotation mark;
you can get the same effect from
\FUNCTION{quoted-insert} by typing
\CTL{q\protect\nolinebreak\ "}.
\index{C-q\nolinebreak \ ""@{\sf C-q\nolinebreak \ ""}}

\subsection{Font changes}

\index{font change}

The \FUNCTION{LaTeX-macro} function on \CTL{c m}
lets you easily generate font changes to any of
\LaTeX{}'s eight standard styles, including
supplying the \X{italic correction} in the three
leaning styles (\MACROX{em}, \MACROX{it}, and
\MACROX{sl}).

But what if you are revising a document, and
decide to add a font change?  Well, you could use
\CTL{c m} to do it, but then you'd have to move
the closing brace, and any preceding \X{italic
correction}.

\FUNCTION{LaTeX-mode} provides a better solution:
customized functions {\em wrap\/} a \X{font
change} around the current word, or if a numeric
argument is given, around that many words starting
from the current one.  These functions are listed
near the bottom of \FIGREF{fig-latex-mode-2}.
They are almost the only functions that require a
second prefix character; \CTLCC{e}
(\FUNCTION{LaTeX-font-em}) is easy to type, and
retains mnemonic significance.  These functions
handle the \X{italic correction} properly; leaning
fonts get it unless the character following the
last word is a \X{period} or a \X{comma}.

\subsection{Comments}

\TeX{} provides an inline \X{comment} mechanism
with the percent sign.  It discards text from that
character to the end of the line, plus {\em all
leading space on the next line up to, but not
including, its end-of-line character}.

Sometimes, however, you want to temporarily
suppress typesetting of a part of a document
without actually removing it from the file.  One
way is to insert leading percents on each line of
the region to be suppressed, but that is tedious
to do manually.  A second way is to use \LaTeX{}'s
\FILE{ifthen} style
\X{option} which added loops and
conditionals, but appeared after the {\em \LaTeX{}
User's Guide and Reference Manual\/} was written,
and so is not widely known.  A third way is to
define a \LaTeX{} macro like

  \begin{small}
\begin{verbatim}
\newcommand{\comment}[1]{}
\end{verbatim}%
\XM{newcommand}%
  \end{small}

\noindent
However, that won't work if the argument contains
paragraph breaks.  You could drop down to
low-level \TeX{} and write

  \begin{small}
\begin{verbatim}
\long\def\comment#1{}
\end{verbatim}
\XM{long}
\XM{def}
\XM{comment}
  \end{small}

\noindent
but \LaTeX{} users are not supposed to do that,
except in
\X{style file}s.  Also, both of these macros
risk overflowing \TeX{}'s input buffer,%
\index{overflow of buffer}%
\index{buffer overflow}
since the complete argument might be rather long,
even if it is subsequently discarded.

I often wish that \LaTeX{} had provided a standard
\verb|comment| environment to do this; it could be
implemented much like \verb|verbatim|, except that
it must support properly nested \verb|comment|
environments.  Rainer Sch\"opf
has implemented a version of a \verb|comment|
environment in a new \verb|verbatim|
implementation for \LaTeX{}
\cite{Schoepf:TB11-2-284-296},%
\index{Schoepf, Rainer@Sch{\"o}pf, Rainer}
although nested comments are not yet supported.

The solution provided by \FUNCTION{LaTeX-mode} is
the function \FUNCTION{LaTeX-comment} on \CTL{c
$\protect\%$}
% use math mode there to fix spacing problem in output
which implements the first choice
above.  By default, it comments out the current
paragraph, or with an argument, the current
region.  The comment prefix inserted at the
beginning of each line is defined by the variable
\VARIABLE{LaTeX-comment-prefix}\/; its default
value is \verb*|%%: |.  A unique prefix is
desirable to distinguish such lines from ordinary
comments.  You should avoid using any
regular-expression%
\index{regular expression}
matching characters in it.

You can remove the comments inserted by
\FUNCTION{LaTeX-comment} by using the function
\FUNCTION{LaTeX-uncomment} on \CTL{c u}.  It
should normally be used with an argument to act on
a region, instead of a paragraph.  The reason for
this is that paragraphs are recognized according
to the \X{regular expression} in the Emacs
variable \VARIABLE{paragraph-separate}\/; the
default setting is such that a line containing
only a comment ends a paragraph.  Consequently,
\FUNCTION{LaTeX-uncomment} will do nothing because
its `paragraph' is always empty.  Invoking it with
an argument to process a marked region solves the
problem.

\subsection{Mismatched delimiters}

\index{mismatch!of delimiter}
\index{delimiter mismatch}

\TeX{} gets very unhappy when it finds mismatched
braces, and in complex documents, it can sometimes
be difficult to find them.  The job is not made
easier on low-resolution screen displays where
braces and parentheses are virtually
indistinguishable.  Finding such mismatches is a
job for a computer, not a human, and
\FUNCTION{LaTeX-mode} offers you help.

Braces are not the only things you might want
assistance with.  Checking for mismatched
parentheses, square brackets, and angle brackets
is also supported.  These normally insert
themselves when you type them, but
\FUNCTION{LaTeX-mode} has commands
that insert
pairs: typing
%=================================================
% NB: We cannot use \{ and \} here and in the next
% paragraph because MakeIndex cannot handle them,
% even with quoting, until I fix the problem.  We
% therefore revert to \lbrace and \rbrace instead.
%=================================================
\CTL{c $\protect\lbrace$}
gets you a pair of open and close braces, and
similarly for
\CTL{c [}, % ] match
\CTL{c (}, % ) match
and
\CTL{c {\protect\tt <}}. % > match
These are the default bindings of the functions
\FUNCTION{LaTeX-braces},
\FUNCTION{LaTeX-brackets},
\FUNCTION{LaTeX-parentheses}, and
\FUNCTION{LaTeX-angles}.

If you get in the habit of using these instead of
typing the delimiter pair yourself, you will
rarely have mismatch problems.  Emacs itself has
native delimiter matching support: as you type a
close delimiter, the \X{cursor flash}es briefly to
the matching open delimiter.

But what if you didn't follow my advice, typed a
lot of braces yourself, and then when \TeX{}
complained about unbalanced braces, you couldn't
find the errors?  Well, the function
\FUNCTION{LaTeX-check-brace-balance}
bound to
\CTL{c $\protect\rbrace$}
will scan the buffer from the current point to the
end, checking for unbalanced braces, and brace
pairs separated by unusually long strings, but
ignoring \X{backslash}ed braces.  It complains if
it finds a paragraph break between braces, unless
you give it an argument.
If mismatches are detected, you are so informed,
and the positions of the mismatches are remembered
on Emacs' stack of marks,%
\index{mark stack}
so you can easily get to them.

Similar functions
\FUNCTION{LaTeX-check-angle-balance},
\FUNCTION{LaTeX-check-bracket-balance},
and
\FUNCTION{LaTeX-check-parenthesis-balance}
are provided on
% < match
\CTL{c {\protect\tt >}},
% [ match
\CTL{c ]},
and
% ( match
\CTL{c )},
for checking those delimiter balances.  Note the
key binding symmetry: \CTL{c open-delimiter}
inserts the pair, and \CTL{c close-delimiter}
checks the balance.

The characters \verb|<| and \verb|>| are likely to
be used in \X{math mode}, and not require
balancing.  However, you might also have used them
for other purposes.  In such a case, you can just
add matching delimiters inside comments in your
math mode uses, and then \CTL{c {\protect\tt >}}
will work satisfactorily.

There is also
\FUNCTION{LaTeX-check-dollar-balance}%
\index{dollar sign}
on \CTL{c $\protect\$$}.
% use math mode there to fix spacing problem in output
It looks for dollar pairs separated by long
strings, ignoring \X{backslash}ed dollars.  It
also complains about paragraph breaks between
dollar pairs, unless it is given an argument.
There is no way for a computer program that is
much less complex than \TeX{} to tell the inside
of math mode from the outside, so you can confuse
this function by starting it inside math mode.

  \begin{sloppypar}
The Emacs variables
\VARIABLE{LaTeX-angle-interval},
\VARIABLE{LaTeX-brace-interval},
\VARIABLE{LaTeX-bracket-interval},
\VARIABLE{LaTeX-dollar-interval}, and
\VARIABLE{LaTeX-parenthesis-interval}
set the limiting between-delimiter string length
before a warning is raised; their default values
are each set to 500 characters.
  \end{sloppypar}

\subsection{Mismatched environments}

\index{mismatch!of environment}
\index{environment!mismatch}

  \begin{sloppypar}
If you have a complex document where
\MACROX{begin}\verb|{...}| \ldots{}
\MACROX{end}\verb|{...}|
groups have been typed manually, you can also
end up with mismatched environments that are
hard to find.
  \end{sloppypar}

The command \METAX{check-LaTeX-nesting}%
\index{nesting check}
scans the buffer to ensure the correctness of
\MACROX{begin}\verb|{...}| \ldots{}
\MACROX{end}\verb|{...}|
nesting.  If, for example, your buffer contains a
\X{nesting error} like this

  \begin{small}
\begin{verbatim}
  \begin{verse}
...
    \begin{quote}
...
  \end{verse}
...
    \end{quote}
\end{verbatim}
\XM{begin\protect\BRACED{verse}}
\XM{end\protect\BRACED{verse}}
\XM{begin\protect\BRACED{quote}}
\XM{end\protect\BRACED{quote}}
  \end{small}

\noindent
the command will terminate with the \X{cursor} in
front of the \MACROX{end\protect\BRACED{verse}}
with the error message

     \begin{quote}
\tt
This \verb|\end{verse}| is matched by preceding
\verb|\begin{quote}| at mark.
     \end{quote}

\noindent
The Emacs function
\FUNCTION{exchange-point-and-mark} on \CTL{x}
\CTL{x} will move the \X{cursor} to the
mismatching \MACROX{begin\protect\BRACED{quote}}.
After fixing the error, you can rerun the
\X{nesting check} by typing \CTL{x ESCape}
(\FUNCTION{repeat-complex-command}) until it
finally reports

     \begin{quote}
\tt
[done] -- all \verb|\begin{}-\end{}|s balance.
     \end{quote}

\begin{sloppypar}
The command
\METAX{indent-LaTeX-begin-end-groups} indents
\MACROX{begin}\verb|{...}| \ldots{}
\MACROX{end}\verb|{...}|
groups according to their
\X{nesting level}, which
helps to make the input file more readable.
\end{sloppypar}

You don't need these commands very often, so
they do not have default key bindings.

\subsection{Word abbreviations}
\label{word-abbreviations}

Emacs provides a convenient \X{word abbreviation}
facility%
\index{abbreviation}
that permits the automatic expansion of a
string of letters when the following \X{space} or
\X{punctuation} is typed.  \FUNCTION{LaTeX-mode}
provides this by default with a set of
abbreviations in a table that can be customized
for personal use.

You can find the complete set of abbreviations%
\index{abbreviations!displaying all defined}
by examining the value of the variable
\VARIABLE{LaTeX-mode-abbrev-table}, or by invoking
the function \FUNCTION{list-abbrevs}.  You can
make changes most easily with
\METAX{edit-abbrevs}.

The commonest abbreviations recognized in
\FUNCTION{LaTeX-mode} are for macro names
that are awkward to type: the input
\verb*|latex | expands to \verb*|\LaTeX{} |,
\index{latex to latex@latex to \verb|\LaTeX{}|}
\verb*|tex | to \verb*|\TeX{} |, and so on.
\index{tex to tex@tex to \verb|\TeX{}|}

Note particularly that the expansion here is to
\MACRO{TeX}\BRACED{}, and {\em not\/}
\verb*|\TeX\ |!%
\index{tex vs. tex@\protect\MACRO{TeX}\BRACED{}
vs.\ \protect\MACRO{TeX}\protect\verb*=\ =}
There are good reasons for this:
%
  \begin{itemize}
    \item
          If you terminate macro names with
          \verb*|\ | instead of with \verb|{}|,
          you have to remember to do that only
          where a space would really be
          permitted; in particular, you don't
          want the \verb*|\ | before
          punctuation. You can use \verb|{}|
          consistently in both cases.
    \item
          If the \verb*|\ | appears at
          the end of a line, and trailing
          spaces\index{space!trailing}
          are subsequently stripped, you
          now have a new macro equivalent to
          \verb|\^^M|, which might have a
          different meaning.  Although both
          \FILE{plain.tex} and
          \FILE{lplain.tex} make the two macros
          equivalent, that might not always be
          the case.

          You should never count on end-of-line
          blanks being preserved; some e-mail%
          \index{mail!electronic}\index{e-mail}
          systems, and some editors, may delete
          them.  Text filling and justification
          as commonly used in Emacs can also
          remove them.
    \item
      \begin{sloppypar}
          In composite words, like
          \verb|\TeX{}book|, the braces keep
          the parts together for text fill
          operations, word counting, spell
          checking and so forth, while the form
          \verb*|\TeX book| will not.
      \end{sloppypar}
  \end{itemize}

The form \verb|{\TeX}| has the almost same
advantages over \verb*|\TeX\ | as \verb|\TeX{}|
does, but has one drawback: if you need to
\MACROX{protect} it, then you must do so inside
the braces.  Use of a final empty brace pair
therefore seems the best choice.

By Emacs convention,
\X{word abbreviation}%
\index{abbreviation}
mode is
never turned on automatically; you must explicitly
toggle it on a case-by-case basis by executing the
command \METAX{abbrev-mode}.  If you always want
it selected in \FUNCTION{LaTeX-mode}, add it to
your \FILE{.emacs}\index{startup file} file in a
\X{mode hook}:%
\index{hook}

  \begin{small}
\begin{verbatim}
(setq LaTeX-mode-hook
      '(lambda ()
         (abbrev-mode 1)
         )
      )
\end{verbatim}
\XV{LaTeX-mode-hook}%
\index{hook}
\XF{lambda}
  \end{small}

\noindent
If you have other things to set in that
\X{mode hook},%
\index{hook}
they should go on the lines immediately before or
after the \verb|(abbrev-mode 1)| line, since there
can be only one mode hook for each editing mode.

\subsection{Bibliographies}

\index{bibliography}

Literature citations are conveniently provided for
on \CTL{c c} (\FUNCTION{LaTeX-cite}), which
generates a \MACROX{cite}\BRACED{} command
with the \X{cursor} after the open brace.  With
an argument, it produces \MACROX{cite[]}\BRACED{}
instead, with the cursor between the square
brackets.

There is another function,
\FUNCTION{LaTeX-bibitem}, on \CTL{c} \CTL{b},
which generates a
\MACROX{bibitem\protect\BRACED{}} for you;
with an argument, it produces
\MACROX{bibitem[]\protect\BRACED{}}.
Normally, you should be using a program like
\BibTeX{}
\cite[Appendix~B]{Lamport:latex}%
\index{Lamport, Leslie}%
\index{bibtex@\BibTeX{}}
or \Tib{}
\cite{Alexander:TB7-3-138,Alexander:TB8-2-102}%
\index{Alexander, James}
for preparation of bibliographies from a data base
and the citations recorded in the \LaTeX{}
\FILE{.aux} file.   If you find yourself using
this command, you are doing the job the hard and
inflexible way.

\FUNCTION{LaTeX-mode} automatically invokes the
function \FUNCTION{update-LaTeX-bibtags} to
extract the list of bibliography files from the
\MACROX{bibdata} command in the \FILE{.aux} file,
or the \MACROX{bibliography} command in the
\LaTeX{} file.  Each such file is then located in
the \VARIABLE{BIBINPUTS} search path, and scanned
to extract citation tags which are stored as an
association list in the variable
\VARIABLE{LaTeX-bibtags}.  Each list entry
contains a citation tag and the name of the file
in which the tag was found.

If the \VARIABLE{BIBINPUTS} environment variable
is not set, then the Emacs variable
\VARIABLE{LaTeX-BIBINPUTS} is used instead to get
a suitable search path.

You can view the citation tag list by invoking the
function \FUNCTION{show-LaTeX-bibtags}.

You can request completion on a citation tag
inside a \MACROX{cite} command by using the
function \FUNCTION{LaTeX-bibtag-with-completion}
normally bound to \CTL{c C}.

If you are visiting a subfile in a multi-file
document, or have just modified the list of
bibliography files in the \MACROX{bibliography}
command, you should manually run
\FUNCTION{update-LaTeX-bibtags} to update the
variable \VARIABLE{LaTeX-bibtags}.

\subsection{Indexing}

\label{indexing}
\index{indexing}

Index preparation is a tedious job that cannot be
entirely automated
\cite{Aurbach:TQ3-1,%
      Bentley:EPODD-1-1-3,%
      Chen:UCB-TR-87-347,%
      Chen:SPE-19-9-897,%
      Lamport:makeindex}.%
\index{Aurbach, R.~L.}%
\index{Bentley, J.~L.}%
\index{Kernighan, B.~W.}%
\index{Lamport, Leslie}%
\index{Chen, Pehong}%
\index{Harrison, Michael~A}
Nevertheless, technical documents can
benefit significantly from a good index, and
support tools like \PROG{makeindex} or
\PROG{texindex} can handle much of the drudge
work of sorting and formatting the index entries.

\FUNCTION{LaTeX-mode} provides two functions
to support generation of index entries in the
\LaTeX{} file.

\FUNCTION{LaTeX-add-word-to-index} on \CTL{c .}
wraps an index entry around the word at the
\X{cursor} position, either using a private
indexing macro%
\index{macros!private}
like \MACROX{X} described earlier on
\PAGEREF{X-command}, or by duplicating the word
inside a standard \LaTeX{} \MACROX{index}\BRACED{}
command.  The choice between the two is determined
by the Emacs variable
\VARIABLE{LaTeX-index-macro}\/; a
non-\CONSTANT{nil} value supplies the indexing
macro name.  With a numeric argument, multiple
words can be selected for indexing.

\FUNCTION{LaTeX-index} on \CTL{c x} generates

  \begin{small}
\noindent
\verb|\index{|\CURSOR{}
\begin{verbatim}
}
\end{verbatim}
  \end{small}

\noindent
so you can type an explicit index entry that will
not appear at that point in the text.

For use in the
\X{X Window System} on workstations and
personal computers acting as X clients,
\FILE{latex.el} provides additional functions,
\FUNCTION{x-LaTeX-index-start} and
\FUNCTION{x-LaTeX-index-end} that are bound to
\X{mouse} actions; they cannot usefully be invoked
from the keyboard.

To index a phrase in the document like
{\em gnats and gnus},%
\index{gnats and gnus}
simply hold down the shift key and
click the right
\X{mouse}
button at the start of the first word, and then
holding the button down, sweep the mouse across
the entire phrase, lifting the button anywhere in
the last word.  Voil\`a: the buffer now contains
\verb|\X{gnats and gnus}|!

I find it useful to sit down with a typeset copy
of a document, and use a colored \X{highlighter
pen} to mark phrases to be indexed.  With the
marked-up copy, it is then straightforward to use
the
\X{mouse} to add the marked phrases to the index.
For documents like this one, with lots of
technical terms to be indexed, it pays to think
about matters before you start writing.  Define
suitable macros that will typeset those terms in a
particular font, and also automatically create an
index entry for them.  For example, I typeset and
index an Emacs function using a private
\verb|\FUNCTION{}| macro.%
\index{macros!private}

The Emacs variable
\VARIABLE{LaTeX-index-start-with-newline} can be
set to a non-\CONSTANT{nil} value if you prefer to
have the inserted index entry start a new line.
The variable
\VARIABLE{LaTeX-index-end-with-newline} can be
set to a non-\CONSTANT{nil} value to have a
newline generated after the inserted index entry.
The default for both is \CONSTANT{nil}, so that no
additional lines are generated.

\subsection{Cross-references}
\index{cross-references}

  \begin{sloppypar}
\LaTeX{}'s \MACROX{label}, \MACROX{pageref}, and
\MACROX{ref} commands provide a convenient way to
generate \X{cross-references} to equations,
figures, pages, sections, and tables.  In
\FUNCTION{LaTeX-mode}, they are readily available
on the keys \CTL{c l} (that's the letter `l'),
\CTL{c p}, and \CTL{c r}.
  \end{sloppypar}

Since definitions with \MACROX{label} tend to be
separated from their references, you may often
find yourself unable to remember the exact name of
the label you want.  If you type the label name
incorrectly, you won't discover the error until
you have run \LaTeX{} twice.  To avoid this delay,
two functions provide additional support:

  \begin{itemize}
    \item
           \FUNCTION{show-LaTeX-labels} finds all
           labels%
           \index{labels!in use}
           in the buffer and displays them
           with their line numbers; I ran that
           function while I was writing this
           article, and got the output

  \begin{small}
\begin{verbatim}
LaTeX labels in buffer ltxmode.ltx:
"X-command" [line 1220]
"customizing-lists" [line 2358]
"fig-bindings-1" [line 856]
"fig-bindings-2" [line 928]
"fig-latex-index" [line 789]
"fig-latex-mode-1" [line 659]
"fig-latex-mode-2" [line 744]
"fig-letter" [line 2561]
"fig-startup-code" [line 1006]
"gnu-emacs-size" [line 376]
"indexing" [line 2048]
"latex-support" [line 946]
"mode-hook" [line 1310]
"word-abbreviations" [line 1931]
\end{verbatim}
  \end{small}

\noindent
showing the labels in alphabetical order.
With an argument, the labels are shown
instead in line number order.

    \item
           \FUNCTION{check-LaTeX-labels}%
           \index{labels!checking validity of}
           scans the entire buffer, looking for
           labels that are referenced, but
           undefined.  At each such label found, a
           \X{recursive edit} is entered to allow
           you to supply the missing
           label;%
           \index{labels!missing}
           when you exit the recursive edit, the
           search for undefined labels continues
           from where it left off.
  \end{itemize}

These functions locate label references by
searching for the string defined by the variable
\VARIABLE{LaTeX-label-reference}\/; it contains a
\X{regular expression} that normally matches both
\MACROX{pageref} and \MACROX{ref}.  If you have
defined private macros%
\index{macros!private}
that also receive labels
as arguments, you may wish to extend it.  For
example, this document has \MACROX{FIGREF} and
\MACROX{PAGEREF} macros that simplify
cross-referencing.

Similarly, these functions locate label
definitions by searching for the string defined by
the variable \VARIABLE{LaTeX-label-definition},
another regular expression that normally matches
\MACROX{label}.  You may wish to customize it if
private macros%
\index{macros!private}
also generate labels.

Multi-file documents
\index{labels!in multi-file documents}
pose a challenge: labels
defined in one file may be referenced in another
file, and it would be helpful to be able to show a
list of all currently-defined labels when one is
needed for a cross-reference.

It is not feasible for the code in \FILE{latex.el}
to attempt to figure out what files are used for a
particular document, nor is it acceptable to ask
the user to provide those file names.  Yet we
somehow need to scan those files to find all of
the labels.

The solution is that \LaTeX{} can do part of this
job for us: \LaTeX{} processing of the master file
produces in the corresponding \FILE{.aux} file all
defined labels embedded in \MACROX{newlabel}
commands.  The function
\FUNCTION{update-LaTeX-labels}
\index{labels!in multi-file documents}
does the remainder of the job: it prompts for the
name of the master \FILE{.aux} file, and then
scans it to extract a list of labels from the
\MACROX{newlabel} commands.  This list is then
{\em appended\/} to the current contents of the
variable \VARIABLE{LaTeX-aux-file-label-tags}.
Augmentation, rather than replacement, permits
selective construction of list subsets by
multiple invocations of
\FUNCTION{update-LaTeX-labels} on different
files.   \FUNCTION{check-LaTeX-labels}%
\index{labels!checking validity of}
includes the values from
\VARIABLE{LaTeX-aux-file-label-tags}
in its list of defined labels.

For convenience, whenever \FUNCTION{LaTeX-mode} is
run (normally when a file is first visited), it
will search the buffer for the first \TeX{} macro
which is preceded only by optional whitespace on
its line.  If that macro is
\MACROX{documentstyle}, then the file must be the
master file for the document, so
\VARIABLE{LaTeX-aux-file-label-tags} is set to
\CONSTANT{nil}, and \FUNCTION{update-LaTeX-labels}
is automatically called on the corresponding
\FILE{.aux} file.  This means that manual
invocation of \FUNCTION{update-LaTeX-labels} is
needed only when you visit a sub-file
without first visiting the master file.

In recent versions of \FILE{latex.el},
the functions
\FUNCTION{LaTeX-pageref} and \FUNCTION{LaTeX-ref}
have been augmented by
\FUNCTION{LaTeX-pageref-with-completion} and
\FUNCTION{LaTeX-ref-with-completion}.  The new
functions are bound to \CTL{c p} and \CTL{c r},
replacing the bindings to the older functions.
The new ones use an internal function to
dynamically scan the buffer for
\MACROX{label}\BRACED{} definitions, add the
contents of \VARIABLE{LaTeX-aux-file-label-tags}
to the labels collected, and construct a list that
can be used for command completion.%
\index{completion}%
\index{command completion}
They then prompt for a label,
and if you type a \X{query}, they will display the
current list of labels.%
\index{labels!in use}
You can use completion%
\index{completion}%
\index{command completion}
to select any one of them,
or you can enter an arbitrary label that is not in
the completion list.

Here is what the completion%
\index{completion}%
\index{command completion}
list looks like for
this document:

  \begin{small}
\begin{verbatim}
Possible completions are:
X-command                    customizing-lists
fig-bindings-1               fig-bindings-2
fig-latex-index              fig-latex-mode-1
fig-latex-mode-2             fig-letter
fig-startup-code             gnu-emacs-size
indexing                     latex-support
mode-hook                    word-abbreviations
\end{verbatim}
  \end{small}

Because the dynamic label scan that happens each
time these functions are executed may be slow in
large documents, the old functions remain
available for rebinding to keys.

The Emacs variable
\VARIABLE{LaTeX-label-start-with-newline} can be
set to a non-\CONSTANT{nil} value if you prefer to
have the inserted label entry start a new line.
The variable
\VARIABLE{LaTeX-label-end-with-newline} can be set
to a non-\CONSTANT{nil} value to have a newline
generated after the inserted label entry.  The
default for both is \CONSTANT{nil}, so that no
additional lines are generated.

\subsection{French typography}
\index{French typography}
\index{typography!French}

% [03-Oct-1991] -- new subsection describing
% code added after Bernard Gaulle's presentation
% of French typography rules at GUT91 in Paris,
% France on 26-Sep-1991

English typographical conventions for spacing
around punctuation are at odds with good French
typography.%
\index{typography!English}%
\index{French typography}%
\index{typography!French}
\TeX{}'s \MACROX{frenchspacing}
macro~\cite[p.~74]{Knuth:texbook}%
\index{Knuth, Donald. E.}
\cite[p.~154]{Lamport:latex}%
\index{Lamport, Leslie}
does not entirely satisfy French conventions: it
only makes spaces after punctuation the same as
interword spaces.

In French typography,%
\index{French typography}%
\index{typography!French}
the punctuation characters
\verb|: ; ? !| are {\em preceded\/} by an
unbreakable interword space (in \TeX{} language, a
{\em \X{tie}\/}).  Em-dashes%
\index{em-dash (---)}
(---) are always surrounded
by spaces; in \X{English typography},%
\index{typography!English}
such spacing is a matter of personal style.
Quotations
\index{quotation!in French}
are made
with \X{guillemet}s as \flqq~\ldots{}~\frqq,
instead of as ``\ldots{}''; the open guillemet is
followed by a space, and the close one is preceded
by a space.

The \X{GUTenberg} organization has developed a
standard \TeX{} and \LaTeX{}
\X{style file},
\FILE{french.sty}, to provide suitable definitions
of the guillemets as the control sequences
\verb|"<|%
\index{""<@{\tt ""<}}
(or \MACROX{flqq})
and \verb|">|%
\index{"">@{\tt "">}}
(or \MACROX{frqq}), as well as more
convenient accent primitives.

It is tedious to remember to type the \TeX{}
\X{tie} command everywhere that special French
punctuation spacing is required, so the minor mode
function \FUNCTION{French-LaTeX-mode} is provided
in \FILE{latex.el}.  Each time it is invoked, it
toggles between French and non-French conventions.
It can be used in either \TeX{} or \LaTeX{} files.

  \begin{sloppypar}
When French mode is selected, the Emacs \X{mode
line} contains the string \verb|French|, and new
functions
\FUNCTION{LaTeX-French-colon},
\FUNCTION{LaTeX-French-exclamation},
\FUNCTION{LaTeX-French-langle},
\FUNCTION{LaTeX-French-minus},
\FUNCTION{LaTeX-French-query},
\FUNCTION{LaTeX-French-rangle}, and
\FUNCTION{LaTeX-French-semicolon}
are bound to the appropriate keys.  The quotation
mark is rebound to \FUNCTION{self-insert-command}
so that the special handling normally provided by
\FUNCTION{LaTeX-quote} (see
{\bf Dots, commas, and quotation marks}
on \PAGEREF{quote}) is suppressed.
  \end{sloppypar}

The French
\X{angle bracket}
functions insert an angle bracket, expand
\verb|<<| to \verb|"<|,%
\index{""<@{\tt ""<}}%
\index{<<@{\tt <<}}%
\index{<<@\flqq}
and
\verb|>>| to \verb|">|,%
\index{"">@{\tt "">}}%
\index{>>@{\tt >>}}%
\index{>>@\frqq}
and then supply the necessary ties.  Isolated
angle brackets are inserted without further
modification.  Guillemets can thus be inserted
either by typing their named control sequences, or
by \verb|"<| or \verb|<<|, and \verb|">| or
\verb|>>|.

\FUNCTION{LaTeX-French-minus} inserts a
minus sign, and if it is the end of an em-dash,%
\index{em-dash (---)}
supplies surrounding spaces ({\em not\/} ties).

While it would be possible to have \TeX{} provide
for the French spacing requirements by suitable
macro definitions of active characters, such
redefinitions risk interfering with other macros.
It seems best to provide for the spacing
requirements in the input file itself, letting
Emacs remember the necessary rules.

French mode can be customized by defining a
suitable value of the
\VARIABLE{French-LaTeX-mode-hook}%
\index{hook}
variable; see {\bf \LaTeX{} macros} on
\PAGEREF{mode-hook}.

\subsection{Miscellaneous functions}

\FUNCTION{LaTeX-counter} on \CTL{c k} generates a
\X{counter name} with completion,%
\index{completion}%
\index{command completion}
using the names
stored in the variable
\VARIABLE{LaTeX-standard-counters}.

  \begin{sloppypar}
\FUNCTION{LaTeX-footnote} on \CTL{c f} generates a
\MACROX{footnote}\BRACED{}.  Not only does this
save typing, but it also prevents my fingers from
producing \MACRO{bootnote}\BRACED{}, which looks
reasonable enough, but makes \TeX{} unhappy.
Non-\CONSTANT{nil} values of the variables
\VARIABLE{LaTeX-footnote-end-with-newline} and
\VARIABLE{LaTeX-footnote-start-with-newline}
request that newlines be generated before and
after the footnote; the default values are
\CONSTANT{nil}.
  \end{sloppypar}

\FUNCTION{LaTeX-news}%
\index{news}
on \CTL{c} \CTL{n} views the
\FILE{latex.el} file to show the
\X{revision history}
recorded in it.

  \begin{sloppypar}

\FUNCTION{LaTeX-tab} on \CTL{c Tab} indents to the
current
\MACROX{begin}\verb|{...}| \ldots{}
\MACROX{end}\verb|{...}|
\X{nesting level}.
  \end{sloppypar}

\FUNCTION{LaTeX-protect}%
\index{protecting arguments}
on \CTL{c} \CTL{p}
inserts a \MACROX{protect} macro at the current
point.  It is needed whenever
\X{fragile command}s
(e.g.\ any \LaTeX{} command that has a star form
\cite[p.~27]{Lamport:latex})%
\index{Lamport, Leslie}
are present in a moving argument
\cite[p.~151]{Lamport:latex}.%
\index{Lamport, Leslie}
In particular, all macros in
\MACROX{index}\BRACED{} entries should be
preceded by \MACROX{protect}.  Otherwise, you can
get long macro expansions that cause
buffer-overflow%
\index{overflow of buffer}%
\index{buffer overflow}
problems for indexing programs,
and make the index file hard to read.  Also, macro
expansions can introduce special characters which
cause problems for indexing programs like
\PROG{makeindex}.

\FUNCTION{LaTeX-set-indentation} on \CTL{c ,} sets
the current indentation column to the value of its
argument, or to the \X{cursor column} if there is
no argument.  It is only rarely necessary to use
this function, because the indentation is reset by
several other functions.

\FUNCTION{LaTeX-verb} on \CTL{c v} generates a
\verb=\verb|...|=\XM{verb}
command with the \X{cursor} after
the first
\X{vertical bar}.  With an argument, it
creates the \verb=\verb*|...|=\XM{verb*}
form, which makes
spaces visible.\index{space!visible}
The delimiter character can be changed from a
\X{vertical bar} by reassigning the Emacs variable
\VARIABLE{LaTeX-verb-delimiter}.  For example, to
set it to a
\X{plus sign} instead of a
\X{vertical bar}:

  \begin{small}
\begin{verbatim}
(setq LaTeX-verb-delimiter ?\+)
\end{verbatim}
  \end{small}

\noindent
The funny \verb|?\| prefix is one of Lisp's%
\index{Lisp!GNU Emacs}%
\index{Lisp!character quote}
character quotes.  As shown on
\PAGEREF{mode-hook},%
\index{hook}
this assignment should
normally be placed inside a
\X{mode hook}.  It can also be executed
dynamically inside the Emacs \X{minibuffer}.
Alternatively, you can use \METAX{set-variable};
it will prompt for the variable name and value.

There are several other functions in
\FILE{latex.el} that I shall not document here;
they are intended for internal use only, and are
subject to change without warning.  They all begin
with the reserved prefix%
\index{name prefix}%
\index{prefix in name}
\FUNCTION{internal-}.%
\index{conventions for naming}%
\index{naming conventions}

\subsection{Miscellaneous variables}

\index{variables}

There are a number of variables that we have not
yet described.  You should not have to modify any
of them, but you occasionally might want to know
what they are.

\VARIABLE{LaTeX-current-indentation} tracks the
current environment indentation as the number of
spaces from the left margin.  It is updated
dynamically by many functions.

\VARIABLE{LaTeX-mode-map} holds the map%
\index{map of keys}%
\index{key map}
that associates keys with functions.

\VARIABLE{LaTeX-mode-version} is a string
containing the
\X{version number} and date of the last
revision%
\index{revision date}%
\index{date of revision}
to the code.  You should cite its value
when reporting bugs; \FUNCTION{LaTeX-gripe}%
\index{gripe}%
\index{complaint}%
\index{problem report}%
\index{bug report}%
\index{reporting bugs}
puts it in the e-mail%
\index{mail!electronic}\index{e-mail}
subject line.

\VARIABLE{LaTeX-standard-environments} contains
the list of environment names used by
\FUNCTION{LaTeX-begin-end-block}.

\VARIABLE{LaTeX-standard-fonts} holds a list of
font names and sizes.

  \begin{sloppypar}
\VARIABLE{LaTeX-standard-italic-fonts} is a list
of the \LaTeX{} control sequences for fonts that
require italic corrections.
  \end{sloppypar}

\VARIABLE{LaTeX-standard-list-environments} is a
list of \LaTeX{} environments which can have
\MACROX{item} entries.

\VARIABLE{LaTeX-standard-options} is a list of
\X{option}s that can go in the square
brackets of the \MACROX{documentstyle} command.
It is used
by \FUNCTION{make-LaTeX-document} and
\FUNCTION{make-SLiTeX-document}.

\VARIABLE{LaTeX-standard-styles} is a list of
styles that can go in the braces
of the \MACROX{documentstyle} command.  It is used
by \FUNCTION{make-LaTeX-document}.

\VARIABLE{LaTeX-standard-unindented-environments}
is a list of environments that must not be
indented.

Variables beginning with the reserved prefix%
\index{name prefix}%
\index{prefix in name}
\VARIABLE{internal-}%
\index{conventions for naming}%
\index{naming conventions}
are for internal use only; they
are subject to change without warning, and will
not be documented here.

\subsection{Customizing lists}

\label{customizing-lists}
\index{customization}

It is undesirable for users to have to duplicate
the long initializations of standard fonts,
macros, environments, and so on, when all they
want to do is add a few more items to the lists.

  \begin{sloppypar}
Therefore, for each variable
\VARIABLE{LaTeX-standard-xxx}, there is a
corresponding variable \VARIABLE{LaTeX-extra-xxx}
that is intended for user customization.  The
extra values are appended to the standard ones to
make new lists that are used for command
completion.%
\index{completion}%
\index{command completion}
Here are the names of these
customization variables:
\VARIABLE{LaTeX-extra-counters},
\VARIABLE{LaTeX-extra-dotted-abbreviations},%
\index{abbreviation}
\VARIABLE{LaTeX-extra-environments},
\VARIABLE{LaTeX-extra-fonts},
\VARIABLE{LaTeX-extra-italic-fonts},
\VARIABLE{LaTeX-extra-list-environments},
\VARIABLE{LaTeX-extra-macros},
\VARIABLE{LaTeX-extra-options},
\VARIABLE{LaTeX-extra-styles},
\VARIABLE{LaTeX-extra-tied-abbreviations},
and
\VARIABLE{LaTeX-extra-unindented-environments}.
  \end{sloppypar}

Suppose for example that you want to add new
environments named \verb|conjecture|,
\verb|postulate|, and \verb|wildguess| to the
standard list used by
\FUNCTION{LaTeX-begin-end-block}.  In the
\VARIABLE{LaTeX-mode-hook}%
\index{mode hook}%
\index{hook}
in your \FILE{.emacs}
file, add this assignment:

  \begin{small}
\begin{verbatim}
(setq LaTeX-extra-environments
      '(
        ("conjecture")
        ("postulate")
        ("wildguess")
        )
      )
\end{verbatim}
  \end{small}

\noindent
When you subsequently type \CTL{c b}, these three
new names will appear in the environment name
completion list.  Such lists are automatically
alphabetized during the completion process, so the
names can be given in any order in the assignment.

There is no provision for deleting names from the
standard lists; after all, they are {\em
standard\/}!  Also, remember that the new
additions are made known only to Emacs; you still
have to teach \LaTeX{} how to typeset them.

You may have wondered in the example above why I
wrote \TYPEIN{("conjecture")} instead of just
\TYPEIN{"conjecture"} in the assignment of
\VARIABLE{LaTeX-extra-environments}.  The extra
parentheses make a list out of each element in the
variable.  In \FILE{latex.el}, all variables that
hold multiple strings store them as {\em lists of
lists\/} of strings, rather than as simpler lists
of strings.  This choice was intentional, because
it facilitates adding additional related strings
in the form of Lisp {\em \X{association list}s}.

 \begin{sloppypar}
The variables
\VARIABLE{LaTeX-extra-environments},
\VARIABLE{LaTeX-extra-macros},
\VARIABLE{LaTeX-standard-environments},
and
\VARIABLE{LaTeX-standard-macros}
already use association lists to hold trailing
braces and brackets, descriptive comments, and
positioning functions.
 \end{sloppypar}

\section{\protect\SliTeX{} support}

\SliTeX{}%
\index{slitex@\SliTeX{}}
works much like \LaTeX{}, so little
additional support is required.  All of the
commands in the preceding sections can be used,
and the editing mode is still called
\FUNCTION{LaTeX-mode}.

  \begin{sloppypar}
When you select a new \SliTeX{} file to edit, you
can create an initial template with
\FUNCTION{make-SLiTeX-document} on \CTL{c s}.
It prompts only for document style
\X{option}s, since
the major style is fixed at \verb|slides|, and
produces something like this:
  \end{sloppypar}

  \begin{small}
\begin{verbatim}
% -*-latex-*-
% Document name: /u/beebe/tex/tugboat/foo.stx
% Creator: Nelson Beebe [beebe@math.utah.edu]
% Creation Date: Mon Jul 29 08:15:15 1991
\documentstyle[]{slides}
\begin{document}
  \onlyslides{1-9999}
  \onlynotes{1-9999}
% \colors{} % {red,green,blue,etc.} colors
% \colorslides{} % input file
\end{verbatim}
\verb|  \blackandwhite{|\CURSOR\verb|} % input file|
\begin{verbatim}
\end{document}
\end{verbatim}
\XM{documentstyle}
\XM{newcommand}
\XM{begin\protect\BRACED{document}}
\XM{end\protect\BRACED{document}}
\XM{onlynotes}
\XM{onlyslides}
\XM{colors}
\XM{colorslides}
  \end{small}

\noindent
The \X{cursor} is left positioned in the brace
pair of the \MACROX{blackandwhite}\BRACED{} macro,
where you can type the name of another file that
you can create in \FUNCTION{LaTeX-mode}, using
\verb|slide|%
\index{slide environment@\protect\verb"|slide"| environment}
environments generated by
\CTL{c b sli\protect\SPACE} \KEY{RETurn}.

It is convenient to number each slide with a
comment, so that you have the numbers available if
you need them for the \MACROX{onlynotes} and
\MACROX{onlyslides} commands.  The function
\FUNCTION{renumber-slides} on \CTL{c 0} modifies
relevant \XM{begin} commands in the buffer to read
something like this:

  \begin{small}
\begin{verbatim}
  \begin{slide}{} % slide number 1
...
  \begin{slide}{} % slide number 2
...
  \begin{overlay}{red} % overlay number 2-a
...
  \begin{overlay}{green} % overlay number 2-b
...
  \begin{note} % note number 2-1
...
  \begin{slide}{} % slide number 3
...
  \begin{note} % note number 3-1
...
  \begin{note} % note number 3-2
\end{verbatim}
\XM{begin\protect\BRACED{slide}\protect\BRACED{}}
  \end{small}

\noindent
Any existing comments on the \XM{begin} commands
are discarded.  Notice the special handling
accorded the \SliTeX{}
\verb|note|%
\index{note environment@\protect\verb"|note"| environment}
and
\verb|overlay|%
\index{overlay environment@\protect\verb"|overlay"| environment}
environments; they receive a major number equal to
that of the closest preceding slide, followed by a
hyphen and a minor number or letter
\cite[pp.~136--137]{Lamport:latex}.%
\index{Lamport, Leslie}

The Emacs variable \VARIABLE{SLiTeX-begin-slide}
defines the \X{regular expression} used to find
the start of the \verb|note|, \verb|overlay|, and
\verb|slide| environments.

\section{Letter support}

\index{letter}

\LaTeX{} \cite[pp.~66ff\/]{Lamport:latex}%
\index{Lamport, Leslie}
provides a \verb|letter| document style,
but there is a fair amount of constant
`\X{boilerplate}' that has to be typed each time
you use it.  This suggests that the best approach
is to have private
\X{template file}s that already have a
letter outline in them, and then arrange to start
each letter with a copy of the template already
inserted into the buffer.  Emacs' programmability
makes this straightforward.

The startup file code in
\FIGREF{fig-startup-code} loads a small
Lisp%
\index{Lisp!GNU Emacs}
file, \FILE{letter.el}.  It defines a
\FUNCTION{letter-mode} function, and
associates it with files with extension%
\index{file extensions}
\FILE{.ltr}.  If I then visit a new file
\FILE{rb-jones.ltr}, I immediately get the
buffer shown in
\typeout{====> Check page cross-reference to Figure 7}%
Figure~\ref{fig-letter},
%\FIGREF{fig-letter},
with the \X{cursor} positioned in the empty brace
pair in
\MACROX{begin\protect\BRACED{letter}\protect\BRACED{}},
ready for entry of the address.  The \X{query} in
\MACROX{opening}\BRACED{Dear ?} is a reminder to
enter something there, and then the body of the
letter can be typed in following the
\MACROX{opening} line.

  \begin{figure}[tbh]
    \begin{figbox}
  \begin{small}
\FIXVERB{}
\begin{verbatim}
% -*-LaTeX-*-
% Document name: /u/beebe/rb-jones.ltr
% Creator: Nelson Beebe [beebe@math.utah.edu]
% Creation Date: Mon Jul 29 20:06:18 1991

%---------------------------------------------
% EVERYTHING TO THE RIGHT OF A  %  IS A REMARK
% TO YOU AND IS IGNORED BY LaTeX.
%
% WARNING!  DO NOT TYPE ANY OF THE FOLLOWING
% 10 CHARACTERS AS NORMAL TEXT CHARACTERS:
%       &   $   #   %   _    {   }   ^   ~   \
%
% The following seven are printed by typing a
% backslash in front of them:
%       $  &  #  %  _  {  and  }.
%---------------------------------------------

\documentstyle[nhfb-letter]{letter}
\begin{document}
\end{verbatim}
\verb|\begin{letter}{|\CURSOR\verb|}|
\begin{verbatim}

\opening{Dear ?}

\closing{Sincerely,}
\ps{{$\cal NHFB$}/\LaTeX}
\end{letter}
\end{document}
\end{verbatim}
\XM{documentstyle}
\XM{newcommand}
\XM{begin\protect\BRACED{document}}
\XM{end\protect\BRACED{document}}
\XM{begin\protect\BRACED{letter}\protect\BRACED{}}
\XM{end\protect\BRACED{letter}}
\XM{opening}
\XM{closing}
\XM{ps}
\XM{cal}
  \end{small}
    \end{figbox}
    \caption{Letter template.}
    \label{fig-letter}
  \end{figure}

My personal style
\X{option} \verb|nhfb-letter|
provides for a University and Department
\X{letterhead} on the first page, and defines a
few private macros%
\index{macros!private}
that I often need in my correspondence.

Once the letter file has been saved, I suspend
Emacs, or switch to another workstation
window, and then process the letter by typing

  \begin{small}
\begin{verbatim}
make LET=rb-jones
\end{verbatim}
  \end{small}

\noindent
The UNIX \PROG{make} utility is a wonderful
tool; here it directs the execution of commands
to expand tabs to blanks, changes the file
protection to remove access to all but its
owner, runs \LaTeX{}, and then runs a
\X{PostScript} DVI driver, sending the output to a
nearby printer.  Then it sends the output
PostScript through a shell filter that modifies
the \verb|showpage| command to print the string
{\em File Copy\/} in \X{outline letters}
diagonally across each page, and queues that to
the printer as well.  On those occasions where I
require multiple copies of the original letter, I
just type something like

  \begin{small}
\begin{verbatim}
make LET=rb-jones C=3
\end{verbatim}
  \end{small}

\noindent
This gives me one file copy, and three
originals for signing and mailing.

With this support, preparation of typeset
letters is just as easy as typewritten ones,
and the result looks much better.  And I can
use mathematics and a variety of fonts too!

\section{Bug reporting}

\FUNCTION{LaTeX-gripe}%
\index{gripe}%
\index{complaint}%
\index{problem report}%
\index{bug report}%
\index{reporting bugs}
on \CTL{c g} makes it easy
to complain about \FUNCTION{LaTeX-mode}; it puts
you in an e-mail%
\index{mail!electronic}\index{e-mail}
buffer with a mail header something like this:

  \begin{small}
\begin{verbatim}
To: beebe@math.utah.edu
Subject: LaTeX-mode gripe report {beta test
         0.23 [08-May-1991]}
\end{verbatim}
  \end{small}

\noindent
The standardized subject field makes it easy
for the author to identify such messages in his
voluminous e-mail correspondence, and
also automatically identifies the
\X{code version}.%
\index{version of code}%
\index{revision date}%
\index{date of revision}

If you don't have an electronic mail%
\index{mail!electronic}\index{e-mail}
connection yet, you probably soon will.  For now,
just send me your comments in postal mail.
Machine-readable submissions can be sent on
\X{IBM PC}%
\index{PC}
or
\X{Apple Macintosh}%
\index{Macintosh}
\X{floppy disk}s.

\section{Conclusion}

\FUNCTION{LaTeX-mode} editing support in GNU Emacs
provides a very powerful, and pleasant, way to
prepare \LaTeX{} and \SliTeX{} input.

The original \X{TOPS-20} version written in
\X{TECO} was begun in October 1984, and used
extensively at Utah until our \X{DEC-20}/60
retired on October 31, 1990.  It consists of about
1000 lines of code defining 24 functions.%
\index{code size}

The power of Lisp%
\index{Lisp!GNU Emacs}
over TECO made it possible to
be much more ambitious in the functionality of
the GNU Emacs version, and I consequently
suspended further development of the TECO code
in January 1988 when I began the Lisp coding.
The current Lisp version is nearly 4 times the
size of the TECO one, both in lines of code,
and in editing functions.  Despite the increase
in size, it is {\em much\/} easier to maintain.

The GNU Emacs implementation was released for
beta testing in March, 1988.  About 70 sites
have participated in the \X{beta test} of
\FILE{latex.el}.  I thank these many people for
their contributions of comments, and sometimes,
even code.

Is it bug free?  No computer program for a
realistic problem ever is; there are simply too
many details for humans ever to get completely
right. The \FILE{latex.el}
\X{revision history} shows
mostly additions of new functionality, and code
changes for better performance.  The virtue of the
Emacs editing environment is that new functions
can be written, debugged, and tested in the editor
itself, providing immediate feedback and
confidence in the correctness of operation.

Much of the code is in small functions that are
independent of the others, following the Lisp%
\index{Lisp!programming tradition}
programming tradition.  After removal of comments
and empty lines, and ignoring the initializations
of large tables, the average is about 22 lines of
code and documentation per function.%
\index{function documentation}%
\index{documentation of function}
This is
close to the 20-line average for all of GNU Emacs,
computed from the statistics given earlier on
\PAGEREF{gnu-emacs-size}.  Documentation
contributions are included here because Emacs
functions, and some variables, carry their
own documentation with them, even after
compilation.  That documentation is readily
available for viewing in the editor.

I believe that this code could serve as a model
for other Emacs-like editors that have an
extension language in which new functions can be
written.  I had planned to write an \X{EEL}
version for the \PROG{epsilon} editor on PC DOS,%
\index{IBM PC}%
\index{PC DOS}%
\index{PC}
but alas, have not found the time to do so.  This
is not a small job, but it should be
straightforward for someone familiar with both
Lisp%
\index{Lisp!GNU Emacs}
and \X{EEL}\@.  The
\FILE{latex.el} file is over 4200 lines long,
with about 155KB of text; Emacs compiles it into
about 100KB of byte codes.  The latter figure
should give some idea of the memory requirements
for implementations in other editors.  I hope some
reader will prepare such a translation and make it
freely available, as \FILE{latex.el} is.  A large
portion of the \TeX{} community uses personal
computers that are inadequate for GNU Emacs, but
have smaller Emacs-like editors available, and
such editing support would be a great boon for
them.

If you plan to undertake such a translation
effort, check with the author of \FILE{latex.el}
first to find out if anyone else is already
working on one.

Some other work in the \TeX{} community for
editing support has been reported in the \TUG{}
\TeX{}niques%
\index{texniques@\TeX{}niques}
series
\cite{McPherson:TQ1-1,Muller:TQ7-235,%
vonBechtolsheim:TQ7-195}%
\index{McPherson, Kent}%
\index{Muller, Paul~M.}%
\index{von Bechtolsheim, Stephan}
and in \TUB{}%
\index{tugboat@\TUB{}}
\cite{%
Clark:TB10-1-14-15,%
Eijkhout:TB11-4-605,%
Hoenig:TB7-1-51,%
Hoover:TB10-4-549-559,%
Hornbach:TB7-2-99,%
Kleine:TB7-2-111,%
Williams:TB11-3-421-424%
}.%
\index{Clark, Adrian}%
\index{Eijkhout, Victor}%
\index{Hall, Linda}%
\index{Hoenig, Alan}%
\index{Hoover, Anita}%
\index{Hornbach, Kathy}%
\index{Kleine, Karl}%
\index{Pfeffer, M.}%
\index{Williams, Linda}
I believe that \FILE{latex.el} is much more
powerful, however.

Those who use \X{UNIX} workstations or \VMS{}
systems where GNU Emacs is already available
should eventually find \FILE{latex.el} in the
\FILE{emacs/lisp} directory, and until then, can
obtain it directly from the author, provided they
have Internet electronic mail%
\index{mail!electronic}\index{e-mail}
or \PROG{ftp} access.

If you have a UNIX or \VMS{} system, but do not
yet have GNU Emacs,%
\index{GNU Emacs!getting}
you can get Emacs from any site that already has
it, or better, you can get the latest version
directly from the \X{Free Software Foundation}.
The latter is accessible either via Internet
anonymous \PROG{ftp} to the machine {\tt
prep.\penalty0ai.\penalty0mit.\penalty0edu}, or
through postal mail to
  \begin{verse}
Free Software Foundation, Inc.\\
675 Massachusetts Ave\\
Cambridge, MA 02139\\
USA
  \end{verse}
The postal mail
\index{mail!postal}
approach carries some shipping and documentation
charges, but the software itself is free.

\bibliography{ltxmode}

\makesignature

%% Put all ``see xxx'' index entries at end so
%% they have maximal page numbers.  MakeIndex
%% sorts them by their page numbers, and we want
%% them to come at the end of the page number
%% lists for each entry.

\index{<<@{\tt <<}|seealso {guillemet}}
\index{>>@{\tt >>}|seealso {guillemet}}
\index{<<@\flqq|seealso {\protect\MACRO{flqq}}}
\index{>>@\frqq|seealso {\protect\MACRO{frqq}}}
% NB: Need space after MACRO!
\index{flqq@\MACRO {flqq}|seealso {guillemet}}
\index{frqq@\MACRO {frqq}|seealso {guillemet}}
\index{Emacs|seealso {GNU Emacs}}
\index{tie|seealso {tilde}}
\index{tilde|seealso {tie}}

\printindex

\end{document}
%%% This is for GNU Emacs file-specific customization:
%%% Local Variables:
%%% fill-column: 50
%%% End:
