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

%=================================================
%=========> 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
%
% 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[ltugboat,makeidx]{article}

%=================================================
%===============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
%
% (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.
%=================================================

%=================================================
% 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

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

\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}{$\Box$}    %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{\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
}
\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

% LaTeX's default tolerance of 10000 in sloppy and sloppypar
% is unsatisfactory in two-column mode; \emergencystretch
% saves the day
\renewcommand{\sloppy}{
    \tolerance=9000
    \tolerance=4000 %get 17 instead of 26 underfulls
    \tolerance=2000 %get 7 instead of 26 underfulls; many stick into right margin
    \tolerance=1000 %get 0 instead of 26 underfulls; many stick into right margin
    \tolerance=9999 %get 22 instead of 26 underfulls
    \tolerance=10000 %get 26 underfulls
    \tolerance=1000 %get 0 instead of 26 underfulls; many stick into right margin
    \tolerance=9000 % get 26 underfulls
    \emergencystretch=0pt
%    \exhyphenpenalty=-1000
%    \pretolerance=100
%    \pretolerance=10000
%    \hyphenpenalty=0
%    \exhyphenpenalty=-100
    \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}
    \parindent\z@
    \parskip\z@ plus .3pt\relax\let\item\@idxitem
    \addcontentsline{toc}{section}{\numberline {}Index}
}                                       %leave pagestyle alone
                                        %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}{%
%   \hfuzz=10pt                         %no complaints, please
    \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\\
        South Physics Building\\
        University of Utah\\
        Salt Lake City, UT 84112\\
        USA\\
        Tel: (801) 581-5254\\
        FAX: (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.
% \HALFLINE

\bibliographystyle{plain}

\section{Introduction}

  \begin{sloppypar}
However, even $33 + 128$ functions are 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}

  \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}

\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 nesting level, and leaves
the 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.

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{sloppypar}
\noindent
with the 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}

  \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 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, backslashed 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.
  \end{sloppypar}

  \begin{sloppypar}
All math mode environments
(\verb|array|,
\verb|eqnarray*|,
\verb|eqnarray|,
\verb|labelledequation|,
\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}

  \begin{sloppypar}
The abbreviations 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{sloppypar}
These actions cover most of the common cases, but
of course, for abbreviations, cannot be
omniscient.  Dictionaries that I consulted listed
over a thousand abbreviations 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}

  \begin{sloppypar}
You can remove the comments inserted by
\FUNCTION{LaTeX-comment} with 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.
  \end{sloppypar}

  \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}

  \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 fix.
  \end{sloppypar}

  \begin{sloppypar}
\noindent
the command will terminate with the cursor in
front of the \MACROX{end\protect\BRACED{verse}}
with the error message {\em This
\verb|\end{verse}| is matched by preceding
\verb|\begin{quote}| at mark.} The Emacs function
\FUNCTION{exchange-point-and-mark} on \CTL{x}
\CTL{x} will move the cursor to the mismatching
\MACROX{begin\protect\BRACED{quote}}.  After
fixing each such error, you can rerun the nesting
check by typing \CTL{x ESCape} (\FUNCTION{Redo})
until it finally reports {\em [done] -- all
\verb|\begin{}-\end{}|s balance}.
\end{sloppypar}

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

\begin{itemize}
  \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}

  \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}

  \begin{sloppypar}
In recent versions of \FILE{latex.el},
\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 another new function,
\FUNCTION{LaTeX-make-label-list}, to dynamically
scan the buffer for \MACROX{label}\BRACED{}
definitions, and construct a list that can be used
for 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 to select any one of them,
or you can enter an arbitrary label that is not in
the completion list.
  \end{sloppypar}

  \begin{sloppypar}

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

  \begin{sloppypar}
\VARIABLE{LaTeX-option-list} holds the options
collected by \FUNCTION{make-LaTeX-document} and
\FUNCTION{make-SLiTeX-document}.
  \end{sloppypar}

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

  \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.  Here are the names of these
customization variables:
\VARIABLE{LaTeX-extra-dotted-abbreviations},
\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},
and
\VARIABLE{LaTeX-extra-unindented-environments},
  \end{sloppypar}

  \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 options, since
the major style is fixed at \verb|slides|, and
produces something like this:
  \end{sloppypar}

\end{document}
