[OS X TeX] Customizing Emacs.

[Martin Steer]

It's been a while since this query was posted, but I hope some of this
(the product of trial and error) will still be of use.

Andrea Riciputi <ariciputi at pito.com> writes:

> I'm speaking of having keyboard shorcuts bounded to some frequently
> used LaTeX commands, such as \emph{}, \mbox{}, \frac{}{}, ^{}, _{} and
> other, like Alpha did in past times. (Actually I know Alpha is still
> there, but for several reason I prefer to stay with emacs now).

The auctex macros \mbox{} and \frac{}{} should be accessible in any
latex document. The others you mention aren't available by default.

> Furthermore I'd be very very happy to make AucTeX AMSLaTeX aware, it
> should sound strange but I've not ever been able to get it working.
> :-(

The relevant style file is amsmath.el, which is installed with auctex
in the directory .../auctex/style. The latter is the default directory
for manually added style (macro) information. If you use C-c C-m to
add \usepackage{amsmath} to your document's header, amsmath.el should
be loaded and the macros it defines should be available. If you type
in \usepackage{amsmath} by hand, you will have to reset the style
hooks for your document by running C-c C-n (see below), before you can
use the macros. Test whether they've been loaded with "C-c C-m
hdotsfor" or something similar (have a look at amsmath.el).

For me this works out of the box, with just the following lines in my
.emacs, and no other auctex customization:

(require 'tex-site)
(setq TeX-auto-save t)
(setq TeX-parse-self t)

The styles available can be seen by typing "C-h v TeX-active-styles
RET" from inside your document. The list is local to the document, and
differs according to the packages you have in your header. In a new
foo.tex with nothing in the header I get:

TeX-active-styles's value is ("foo" "LATEX")

which are the styles belonging to foo.tex and those belonging to
auctex in latex mode. The latter include, for example, the macro for
inserting \usepackage. Though "active", no styles have yet been
defined for foo.tex

>
> And yes, I've read the f***ing manual but it's so terse that was of no
> help (at least for me). I've also asked for help on AucTeX list, but
> it seems that my questions were too basic for those guys. :-(
>

Their answers can be terse too, but I don't think they mean any harm
by it, do they?

> Just a little example. If I try to type '\em' and then hit M-tab or
> C-c 
> C-m I can't get the expected (and desired) completion '\emph{}'
>

M-tab is macro completion, C-c C-m is macro insertion (a different
thing).

Anyway, in the default setup, \emph{} isn't an ordinary macro, but
instead has its own binding as a font command (see the auctex
reference card below). You could however add \emph{} to the list of
ordinary macros by putting the following in a style file called
latex.el.

;; latex.el

(TeX-add-style-hook "latex2e"
  (function
    (lambda ()
      (TeX-add-symbols '("emph" t)))))


**The path**

Before you can use your new style, auctex has to find it and apply it
to your document. It finds manually-added style info by following:

some path to --> some style file which has --> some style hook

which in the case of the packaged amsmath styles is:

.../auctex/style/ --> amsmath.el --> "amsmath"

The path is set by the variable TeX-style-path. If you check it's
current value (C-h v TeX-style-path RET), you will see that auctex
looks in a directory called style/ in the same directory as your
document (you will see other directories as well). This is the most
immediate directory for you to use for your own styles. You can add
other directories by customizing TeX-style-path in the usual way. For
my styles I have:

/Users/martin/emacs/style/

Style directories which you add to the path don't have to be called
"style", but must be written with a following slash in the
customization entry (e.g. mystyledir/). Directories called auto/ are
used for styles added automatically by auctex (if you put your own
styles there they could be overwritten).


**Style files and style hooks**

These work together. Say you want to add another amsmath style, with
some more macros. You can do this in a new style file called
amsmath.el, with "amsmath" as the style hook.

.../mystyledir/amsmath.el --> "amsmath"

If you do it this way, auctex will find both your new amsmath styles
as well as those in the original amsmath.el. It will also find them
for any document which uses amsmath.sty.

You might instead use the name of your document for the style file:

.../mystyledir/mydocument.el --> "amsmath"

but if you do it that way, only your new amsmath styles will be
available once auctex is reset (see below), e.g. you won't have the
hdotsfor macro, and your styles will only be available in
mydocument.tex.

You could also use:

.../mystyledir/mydocument.el --> "mydocument"

Again you lose the old amsmath styles once auctex is reset, and now
your styles are available even when you're not using amsmath.sty.

The safe way to go is therefore the first of these three.

File-names/style-hooks you can use include your document's name, latex
class names e.g. "article", and latex package names. Auctex knows what
names to search for to find your styles because it parses your
document.

A special case is where you want a style (e.g. the \emph{} macro) to
be available in all documents. Here it is possible to use:

.../mystyledir/latex.el --> "latex2e"

As far as I can tell, this works without doing any harm. There may
however be a better way. This setup requires C-u C-c C-n to load your
new style (see below).

You can of course put more than one hook in a style file.


**Loading the styles**

You can force the loading of a style with C-c C-n or C-u C-c C-n. The
first of these saves the buffer and reapplies the style hooks. The
second also reloads the style hooks. I use each of these whenever I
feel like it, and so should you. If you use C-c C-m or C-c C-e to add
a package or class to your document (e.g. by inserting "\usepackage
packagename"), the style hooks are applied automatically.

If you make changes to a style you're already using, you will in
general need C-u C-c C-n to clear the old style and see the changes.

> Another example. When I want to type in an equation with, let say, the
> integral symbol it should be nice to have a dialog that asks for lower
> and upper bounds of integration and return the right LaTeX input.
>
> Anyone here has ever managed things like these?
>

I'm not a mathematician, but I'll assume you want to insert something
like this (from Lamport):

\int_{0}^{1} f

which you can do with the following style hook:

;; article.el

(TeX-add-style-hook "article"
  (function
    (lambda ()
      (TeX-add-symbols
        '("int"
	 (TeX-arg-literal "_") "Lower bound"
	 (TeX-arg-literal "^") "Upper bound")))))


A different way would be to wrap it up first in a latex macro:

\newcommand{\integral}[3]{\ensuremath{\int_{#1}^{#2} #3}}

which you could put in your tex path in a file called integral.sty.
You then define a style hook and put it in a file called integral.el.

;; integral.el

(TeX-add-style-hook "integral"
  (function
    (lambda ()
      (TeX-add-symbols
        '("integral" "Lower bound" "Upper bound" "Function")))))

The new style will be loaded if you have \usepackage{integral} in your
header (which you must do to use the latex macro). The other examples
above have arbitrary style hooks; make up your own mind as to what is
appropriate there.

If you call "C-h v TeX-symbol-list RET" from inside your document, you
should see a large number of patterns for constructing further macros.



**C-c C-m vs M-tab***

You should do your testing with C-c C-m (equivalently, C-c RET), which
is interactive (it will ask you for arguments), not with M-tab, which
merely completes, i.e. "\integ M-tab" gives me:

\integral{}

with point outside the brackets. For macros with (multiple) arguments
this isn't useful. If you're on a mac you probably don't have M-tab
anyway, as the os takes it over for task switching. If you really do
want TeX-complete-symbol (the function bound to M-tab) use ESC-tab
instead, or rebind to another key.

When you get sick of hitting C-c C-m, put:

(setq TeX-electric-escape t)

in your .emacs, or use "M-x customize-variable RET TeX-electric-escape
RET". This should be set before you load auctex, so it may require you
to restart emacs. Then go to your document and hit return. This is
magic.

The auctex manual doesn't adequately separate the stuff above from
auctex's ability to customize itself, to some extent, by automatically
scanning *.sty files. That's a relevant issue, but a somewhat
different one.

Finally, I guess that you're aware that auctex has a maths minor mode,
with built in shortcuts which you could extend. It's noted on the
reference card below, which I've included in case you don't have it.
Run it through tex.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% -*- plain-tex -*- 
% Reference Card for AUCTeX version 11.53
%**start of header
\newcount\columnsperpage

% This file has only been checked with 3 columns per page.  But it
% should print fine either via DVI or PDFTeX.

\columnsperpage=3

% Papersize stuff.  Use default paper size for PDF, but switch
% orientation.  Use papersize special for dvips.

\ifcase\ifx\pdfoutput\undefined 1 \fi
  \ifnum\pdfoutput=0 1 \fi 2
\or
%    \special{papersize 8.5in,11in}%
     \special{papersize 297mm,210mm}%
\or
      \dimen0\pdfpagewidth
      \pdfpagewidth\pdfpageheight
      \pdfpageheight\dimen0
\fi


% This file is intended to be processed by plain TeX (TeX82).
% compile-command: "tex tex-ref" or "pdftex tex-ref"
%
% Original author of Auc-TeX Reference Card:
%                                  
%       Terrence Brannon, PO Box 5027, Bethlehem, PA 18015 , USA
%  internet: tb06 at pl118f.cc.lehigh.edu  (215) 758-1720 (215) 758-2104
%
% Kresten Krab Thorup updated the reference card to 6.
% Per Abrahamsen updated the reference card to 7, 8, and 9.
% Ralf Angeli updated it to 11.50.
% And David Kastrup messed around with it, too, merging the math reference.
%
% Thanks to Stephen Gildea
% Paul Rubin, Bob Chassell, Len Tower, and Richard Mlynarik
% for creating the GNU Emacs Reference Card from which this was mutated

\def\versionnumber{11.53}
\def\year{2004}
\def\version{August \year\ v\versionnumber}

\def\shortcopyrightnotice{\vskip 1ex plus 2 fill
  \centerline{\small \copyright\ \year\ Free Software Foundation, Inc.
  Permissions on back.  v\versionnumber}}

\def\copyrightnotice{%
\vskip 1ex plus 2 fill\begingroup\small
\centerline{Copyright \copyright\ 1987, 1993, 2004 Free Software Foundation, Inc.}
\centerline{Copyright \copyright\ 1992 Kresten Krab Thorup}
\centerline{for AUC\TeX\ version \versionnumber}

Permission is granted to make and distribute copies of
this card provided the copyright notice and this permission notice
are preserved on all copies.


\endgroup}

% make \bye not \outer so that the \def\bye in the \else clause below
% can be scanned without complaint.
\def\bye{\par\vfill\supereject\end}

\newdimen\intercolumnskip
\newbox\columna
\newbox\columnb

\edef\ncolumns{\the\columnsperpage}

\message{[\ncolumns\space 
  column\if 1\ncolumns\else s\fi\space per page]}

\def\scaledmag#1{ scaled \magstep #1}

% This multi-way format was designed by Stephen Gildea
% October 1986.
\if 1\ncolumns
  \hsize 4in
  \vsize 10in
  \voffset -.7in
  \font\titlefont=\fontname\tenbf \scaledmag3
  \font\headingfont=\fontname\tenbf \scaledmag2
  \font\smallfont=\fontname\sevenrm
  \font\smallsy=\fontname\sevensy

  \footline{\hss\folio}
  \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}}
\else
  \hsize 3.2in
  \vsize 7.6in
  \hoffset -.75in
  \voffset -.8in
  \font\titlefont=cmbx10 \scaledmag2
  \font\headingfont=cmbx10 \scaledmag1
  \font\smallfont=cmr6
  \font\smallsy=cmsy6
  \font\eightrm=cmr8
  \font\eightbf=cmbx8
  \font\eightit=cmti8
  \font\eighttt=cmtt8
  \font\eightsl=cmsl8
  \font\eightsc=cmcsc8
  \font\eightsy=cmsy8
  \textfont0=\eightrm
  \textfont2=\eightsy
  \def\rm{\fam0 \eightrm}
  \def\bf{\eightbf}
  \def\it{\eightit}
  \def\tt{\eighttt}
  \def\sl{\eightsl}
  \def\sc{\eightsc}
  \normalbaselineskip=.8\normalbaselineskip
  \ht\strutbox.8\ht\strutbox
  \dp\strutbox.8\dp\strutbox
  \normallineskip=.8\normallineskip
  \normallineskiplimit=.8\normallineskiplimit
  \normalbaselines\rm           %make definitions take effect

  \if 2\ncolumns
    \let\maxcolumn=b
    \footline{\hss\rm\folio\hss}
    \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}}
  \else \if 3\ncolumns
    \let\maxcolumn=c
    \nopagenumbers
  \else
    \errhelp{You must set \columnsperpage equal to 1, 2, or 3.}
    \errmessage{Illegal number of columns per page}
  \fi\fi

  \intercolumnskip=.46in
  \def\abc{a}
  \output={%
      % This next line is useful when designing the layout.
      %\immediate\write16{Column \folio\abc\space starts with \firstmark}
      \if \maxcolumn\abc \multicolumnformat \global\def\abc{a}
      \else\if a\abc
        \global\setbox\columna\columnbox \global\def\abc{b}
        %% in case we never use \columnb (two-column mode)
        \global\setbox\columnb\hbox to -\intercolumnskip{}
      \else
        \global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi}
  \def\multicolumnformat{\shipout\vbox{\makeheadline
      \hbox{\box\columna\hskip\intercolumnskip
        \box\columnb\hskip\intercolumnskip\columnbox}
      \makefootline}\advancepageno}
  \def\columnbox{\leftline{\pagebody}}

  \def\bye{\par\vfill\supereject
    \if a\abc \else\null\vfill\eject\fi
    \if a\abc \else\null\vfill\eject\fi
    \end}  
\fi

% we won't be using math mode much, so redefine some of the characters
% we might want to talk about
\catcode`\^=12
\catcode`\_=12

\chardef\\=`\\
\chardef\{=`\{
\chardef\}=`\}

\hyphenation{mini-buf-fer}

\parindent 0pt
\parskip 1ex plus .5ex minus .5ex

\def\small{\smallfont\textfont2=\smallsy\baselineskip=.8\baselineskip}

\outer\def\newcolumn{\vfill\eject}

\outer\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex}

\outer\def\section#1{\par\vskip 0pt plus 0.2\vsize \penalty-3000
         \vskip 0pt plus -0.2\vsize
  \vskip 3ex plus 2ex minus 2ex {\headingfont #1}\mark{#1}%
  \vskip 2ex plus 1ex minus 1.5ex}

\newdimen\keyindent

\def\beginindentedkeys{\keyindent=1em}
\def\endindentedkeys{\keyindent=0em}
\endindentedkeys

\def\paralign{\vskip\parskip\halign}

\def\<#1>{$\langle${\rm #1}$\rangle$}

\def\kbd#1{{\tt#1}\null}        %\null so not an abbrev even if period follows

\def\beginexample{\par\leavevmode\begingroup
  \obeylines\obeyspaces\parskip0pt\tt}
{\obeyspaces\global\let =\ }
\def\endexample{\endgroup}

\def\key#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.68\hsize\rightskip=1em
  \hskip\keyindent\relax#1}\kbd{#2}\hfil}}

\newbox\metaxbox
\setbox\metaxbox\hbox{\kbd{M-x }}
\newdimen\metaxwidth
\metaxwidth=\wd\metaxbox

\def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize
  {\hskip\keyindent\relax#1\hfil}%
  \hskip -\metaxwidth minus 1fil
  \kbd{#2}\hfil}}

\def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\kbd{#2}\quad
  &\kbd{#3}\quad\cr}

\def\LaTeX{%
    L\kern-.36em\raise.3ex\hbox{\sc{a}}\kern-.15em\TeX}

%**end of header

\title{AUC\TeX\ Reference Card}

\centerline{(for version \versionnumber)}

\section{Conventions Used}

\key{Carriage Return or \kbd{C-m}}{RET}
\key{Tabular or \kbd{C-i}}{TAB}
\key{Linefeed or \kbd{C-j}}{LFD}

\section{Shell Interaction}

\key{Run a command on the master file}{C-c C-c}
\key{Run a command on the buffer}{C-c C-b}
\key{Run a command on the region}{C-c C-r}
\key{Fix the region}{C-c C-t C-r}
\key{Kill job}{C-c C-k}
\key{Recenter output buffer}{C-c C-l}
\key{Next error in \TeX/\LaTeX\ session}{C-c `}
\key{Toggle debug of wonderful boxes}{C-c C-w} % wonderful?
\key{View output file}{C-c C-v}

Commands you can run on the master file (with \kbd{C-c C-c}) or the
region (with \kbd{C-c C-r}) include the following (starred versions
are not available in all modes):

\def\star{\llap{\rm*}}
\key{\TeX}{\star TeX}
\key{\LaTeX}{\star LaTeX}
\key{Con\TeX{}t (once)}{\star ConTeXt}
\key{Con\TeX{}t Full}{\star ConTeXt Full}
\key{Makeinfo}{\star Makeinfo}
\key{Makeinfo with HTML output}{\star Makeinfo HTML}
\key{Appropriate previewer}{View}
\key{Print the output}{Print}
\key{Bib\TeX}{BibTeX}
\key{MakeIndex}{Index}
\key{LaCheck}{Check}
\key{Make (PostScript) File}{File}
\key{Ispell}{Spell}

\section{\TeX ing options}
\TeX\ runs can come in various types, which may be toggled and are
indicated in the mode line.

\key{$\Omega$ mode}{C-c C-t C-o}
\key{PDF/DVI mode}{C-c C-t C-p}
\key{Stop on errors (Interactive mode)}{C-c C-t C-i}
\key{Use Source Specials for viewer control}{C-c C-t C-s}

\section{Miscellaneous}

\key{Read AUC\TeX\ manual}{C-c TAB}
\key{Math Mode}{C-c \string~}
\key{Reset Buffer}{C-c C-n}
\key{Reset AUC\TeX}{C-u C-c C-n}

\section{Multifile Handling}

\key{Save Document}{C-c C-d}
\key{Switch to master file or active buffer}{C-c ^}
\key{Query for a master file}{C-c \_}

\section{Command Insertion}

\key{Insert Section}{C-c C-s}
\key{Insert \LaTeX\ environment}{C-c C-e}
\key{Insert item}{C-c LFD}
\key{Insert item (alias)}{M-RET}
\key{Close \LaTeX\ environment}{C-c ]}
\key{Insert \TeX\ macro \kbd{\\\{\}} }{C-c C-m}
\key{Insert double brace}{C-c \{}
\key{Complete \TeX\ macro}{M-TAB}
\key{Smart ``quote''}{"}
\key{Smart ``dollar''}{\$}
  
\section{Font Selection}

\key{Insert {\bf bold\/} text}{C-c C-f C-b}
\key{Insert {\it italics\/} text}{C-c C-f C-i}
\key{Insert {\rm roman} text}{C-c C-f C-r}
\key{Insert {\it emphasized\/} text}{C-c C-f C-e}
\key{Insert {\tt typewriter\/} text}{C-c C-f C-t}
\key{Insert {\sl slanted\/} text}{C-c C-f C-s}
\key{Insert {\sc Small Caps\/} text}{C-c C-f C-c}
\key{Delete font}{C-c C-f C-d}
\key{Replace font}{C-u C-c C-f \<key>}

\section{Source Formatting}

\key{Indent current line}{TAB}
\key{Indent next line}{LFD}

\key{Format a paragraph}{M-q}
\key{Format a region}{C-c C-q C-r}
\key{Format a section}{C-c C-q C-s}
\key{Format an environment}{C-c C-q C-e}

\key{Mark an environment}{C-c .}
\key{Mark a section}{C-c *}

\key{Comment or uncomment region}{C-c ;}
\key{Comment or uncomment paragraph}{C-c \%}

\section{Source Display}

\key{Toggle folding mode}{C-c C-o C-f}
\key{Hide all items in buffer}{C-c C-o C-b}
\key{Hide current macro}{C-c C-o C-m}
\key{Hide current environment}{C-c C-o C-e}
\key{Show all items in buffer permanently}{C-c C-o C-x}
\key{Show current item permanently}{C-c C-o C-c}

\copyrightnotice
\penalty-9000
\title{Math Mode}

\section{Variables}

All math mode commands are under the prefix key specified by
LaTeX-math-abbrev-prefix, default is "`".

You can define your own math mode commands by setting the variable
LaTeX-math-list before loading LaTeX-math-mode.

\section{Greek Letters}

\def\disp#1{\hbox to 6ex{$#1$\hfill}}
\def\twocol#1\par{{%
  \def\key##1##2{##1&##2\cr}%
  \setbox0\vbox{\halign to 0.45\hsize{\tabskip0ptplus1fil\relax
    ##\hfil&\kbd{##}\hfil\cr\vrule width0ptheight\ht\strutbox#1}}%
  \line{%
  \splittopskip=\ht\strutbox
  \dimen0\ht0
  \advance\dimen0\baselineskip
  \setbox2\vsplit0to0.5\dimen0
  \vtop{\unvbox2}\hfill\raise \ht\strutbox \vtop {\unvbox0}}}}
\def\keycs#1#2#{\keycsii#1{#2}}
\def\keycsii#1#2#3{\key{\disp{#1#2} ({\tt\string#1})}{#3}}

\twocol
\keycs\alpha{a}
\keycs\beta{b}
\keycs\gamma{g}
\keycs\delta{d}
\keycs\epsilon{e}
\keycs\zeta{z}
\keycs\eta{h}
\keycs\theta{j}
\keycs\kappa{k}
\keycs\lambda{l}
\keycs\mu{m}
\keycs\nu{n}
\keycs\xi{x}
\keycs\pi{p}
\keycs\rho{r}
\keycs\sigma{s}
\keycs\tau{t}
\keycs\upsilon{u}
\keycs\phi{f}
\keycs\chi{q}
\keycs\psi{y}
\keycs\omega{w}
\keycs\Delta{D}
\keycs\Gamma{G}
\keycs\Theta{Q}
\keycs\Lambda{L}
\keycs\Pi{P}
\keycs\Sigma{S}
\keycs\Upsilon{U}
\keycs\Phi{F}
\keycs\Psi{Y}
\keycs\Omega{W}

\section{Symbols}

\twocol
\keycs\rightarrow{C-f}
\keycs\leftarrow{C-b}
\keycs\uparrow{C-p}
\keycs\downarrow{C-n}
\keycs\leq{<}
\keycs\geq{>}
\keycs\tilde x{\string~}
\keycs\nabla{N}
\keycs\infty{I}
\keycs\forall{A}
\keycs\exists{E}
\keycs\not \ {/}
\keycs\in{i}
\keycs\times{*}
\keycs\cdot{.}
\keycs\subset{\{}
\keycs\supset{\}}
\keycs\subseteq{[}
\keycs\supseteq{]}
\keycs\emptyset{0}
\keycs\setminus{\\}
\keycs\cup{+}
\keycs\cap{-}
\keycs\langle{(}
\keycs\rangle{)}
\keycs\exp{C-e}
\keycs\sin{C-s}
\keycs\cos{C-c}
\keycs\sup{C-^}
\keycs\inf{C-_}
\keycs\det{C-d}
\keycs\lim{C-l}
\keycs\tan{C-t}
\keycs\hat x{^}
\keycs\vee{|}
\keycs\wedge{\&}

\section{Miscellaneous}

\key{cal letters}{c \<letter>}

\bye

%%% Local Variables: 
%%% mode: plain-TeX
%%% TeX-master: t
%%% End: 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

--------------------- Info ---------------------
Mac-TeX Website: http://www.esm.psu.edu/mac-tex/
           & FAQ: http://latex.yauh.de/faq/
TeX FAQ: http://www.tex.ac.uk/faq
List Post: <mailto:MacOSX-TeX at email.esm.psu.edu>