\documentclass[a4paper,12pt]{article}
\usepackage{url}
\usepackage{isolatin1}
\usepackage[colorlinks,urlcolor=blue]{hyperref}

% -----

\newcommand{\version}{1.3.0}

% -----

\begin{document}

\title{\texttt{latex.sl}: an enhanced \LaTeX{} mode for Jed}

\author{Version \version\\
Guido ``goccia'' Gonzato, Ph. D.\\
\url{guido.gonzato@univr.it}}

\date{Universit\`a di Verona (Italy)\\
\today}

\maketitle

\begin{abstract}
The Jed editor provides support for several programming languages and text
formats, among which \LaTeX. However, the author feels that the default
\LaTeX{} mode is too simple, and that it could be improved in many ways.

This document describes an enhanced \LaTeX{} mode. It aims at making the
process of writing \LaTeX{} documents an easy and pleasant task. Vaguely
inspired by Emacs' AUC \TeX, \texttt{latex.sl} provides the user with
menus, templates, many utilities, and integrated conversion and previewing
of \LaTeX{} documents.
\end{abstract}

\tableofcontents
% \listoftables
% \listoffigures

% -----

\section{Introduction}

Many \TeX{}nicians use \texttt{emacs}: a great\footnote{or rather, big?}
program, but I don't like it very much. \texttt{emacs} has very good
\LaTeX{} support (AUC \TeX), but it's also unacceptably bloated and slow.

I use a fast and compact \texttt{emacs} clone called Jed,
\url{http://www.jedsoft.org}. It can be customised and extended using
S-Lang, an easy-to-learn language similar to C. Jed provides support for a
variety of programming modes, with syntax highlighting and other
facilities. \LaTeX{} support in Jed is provided by \texttt{latex.sl} and
other S-Lang files included in the distribution.

I feel that the default implementation of \texttt{latex.sl} leaves much
to be desired. When I write code or documentation, I follow the so-called
``Goccia's Rules'':

\begin{enumerate}
  \item the program should be as helpful as possible, but
  \item it must not stand in the way; therefore,
  \item it should be fully customisable, and 
  \item it should be usable by geeks and newbies alike.
\end{enumerate}

In my opinion, \texttt{latex.sl} breaks Goccia's Rules 1, 3, and 4. It
should attempt to be more useful.

J\o ergen Larsen, \texttt{jl@dirac.ruc.dk}, wrote a much better
implementation available from \url{http://dirac.ruc.dk/~jl/jed/}. I
initially added an extensive menu system to his mode, but as its
development proceeded I lost sync with it.

I eventually decided to roll my own \LaTeX{} mode. It was developed on
Linux, but it also works and other Unix systems and---woops---Windows. It
was tested on a RedHat 7.3 GNU/Linux machine with teTeX, and under Windows
98 with MiKTeX.

The latest version of \texttt{latex.sl} is \version, it works with Jed
0.99.15 upwards, and is available from
\url{http://profs.sci.univr.it/~gonzato/jed}.

% -----

\section{Installation}

I assume that you have a working installation of Jed. First of all, make a
backup copy \texttt{JED\_ROOT/\-lib/\-latex.sl}. In the unlikely event you
don't like the new \LaTeX{} mode, you'll restore the original file.

Copy \texttt{latex.sl} and \texttt{latex.hlp} to \texttt{JED\_ROOT/lib},
then add these lines to your \texttt{.jedrc}:

\begin{verbatim}
add_mode_for_extension ("latex", "tex");
enable_dfa_syntax_for_mode ("LaTeX");
\end{verbatim}

For a system-wide installation, edit the lines above in the file
\texttt{JED\_ROOT/\-lib/\-jed.rc}.

You'll also want to create the DFA \footnote{the regular expression-based
highlighting scheme.} cache table. As root, add \texttt{latex.sl} to the
list in the file \texttt{preparse.sl}, then run the command:

\begin{verbatim}
jed -batch -n -l preparse
\end{verbatim}

Caveat: by default, \LaTeX{} mode is incompatible with folding mode
because of clashing \texttt{Ctrl-Cf} key binding. Unless you're prepared
to change the key bindings in \texttt{folding.sl}, you can solve the
problem setting this variable in your \texttt{.jedrc}:

\begin{verbatim}
variable LaTeX_Font_Key = "n";
\end{verbatim}

which will make all font operations start with \texttt{Ctrl-Cn} instead of
\texttt{Ctrl-Cf}.

From now on, I shall assume that you run Jed in Emacs emulation mode. All
key bindings will start in \texttt{Ctrl-C}; users who prefer IDE mode will
use \texttt{Ctrl-Z} instead. I also remind you that all operations can be
interrupted with \texttt{Ctrl-G}.

% -----

\subsection{Customisation}
\label{sec:custom}

You customise \texttt{latex.sl} changing the value of its variables.
Insert lines like the following in your \texttt{.jedrc}. The values shown
are the default:

\begin{verbatim}
variable LaTeX_Default_Output = 
               "dvi"; % or: "ps", "dvipdf", "pdf"
variable LaTeX_Indent = 2;
variable LaTeX_Article_Default_Options = "a4paper,12pt";
variable LaTeX_Book_Default_Options = "twoside,11pt";
variable LaTeX_Letter_Default_Options = "a4paper,12pt";
variable LaTeX_Report_Default_Options = "twoside,12pt";
variable LaTeX_Slides_Default_Options = "a4paper,landscape";
variable LaTeX_Prosper_Default_Options = 
               "pdf,slideColor,colorBG,azure";
variable LaTeX_Default_Language = "italian,english" % for Babel
#ifdef WIN32
variable LaTeX_View_Dvi_Command = "yap";
variable LaTeX_View_Ps_Command = "gsview32";
variable LaTeX_View_Pdf_Command = "gsview32";
variable LaTeX_Print_Command = "gsview32";
#else
variable LaTeX_View_Dvi_Command = "xdvi";
variable LaTeX_View_Ps_Command = "gv -watch";
variable LaTeX_View_Pdf_Command = "acroread";
variable LaTeX_Print_Command = "lpr";
#endif
\end{verbatim}

Windows users will have to make sure that all helper programs are in the
PATH.

You can further customise \LaTeX{} mode adding a
\texttt{latex\_mode\_hook} function in \texttt{.jedrc}. For example, I
want accented letters to self insert as the right \TeX{} sequence:

\begin{verbatim}
define latex_mode_hook ()
{
  set_abbrev_mode (1);
  if ( () = abbrev_table_p ("LaTeX") )
    use_abbrev_table ("LaTeX");
#ifdef WIN32
  % prevent clash with movement keys
  undefinekey ("��", "LaTeX-Mode");
  definekey (" \\`a", "��", "LaTeX-Mode");
#else
  local_setkey (" \\`a",     "�");
#endif
  local_setkey (" \\'e",     "�");
  local_setkey (" \\`e",     "�");
  local_setkey (" \\`\\i{}", "�");
  local_setkey (" \\`o",     "�");
  local_setkey (" \\`u",     "�");
}
\end{verbatim}

% -----

\section{Editing \LaTeX{} Documents}

\subsection{Getting Started}

Start a new document, say \texttt{newfile.tex}. The \texttt{.tex}
extension will automatically activate \LaTeX{} mode, which can also be
started on any buffer typing \texttt{Alt-X latex\_mode}. See also the
\textsf{Buffers/\-Select Mode} menu.

The \textsf{Mode} menu contains many entries and sub-menus, and it also
indicates the key bindings when available. You'll want to browse through
the menus, especially if you're not a \LaTeX{} expert. 

Now select \textsf{Mode/\-Templates/\-Article} to create an article
template. Fill it with some text: add a couple of sections, some
environments, change the fonts, and so on. Let \texttt{latex.sl} help you:
use the menus, but try and memorise the key bindings. Note the syntax
highlighting of keywords and other \LaTeX{} elements.

When you're finished, convert your document using \textsf{Mode/\-Compose}.
\texttt{latex} will be run on your document, and if no errors occur the
file \texttt{newfile.dvi} will be created. If errors do occur, please read
Section~\ref{sec:composing}.

Now select \textsf{Mode/\-View} to preview your document. Voil\`a, all
done, without ever using the command line!

% -----

\subsection{Main Features of \LaTeX{} Mode}

As of version \version, \texttt{latex.sl} has the following features:

\begin{itemize}
  \item thoroughly menu-driven 
  \item syntax highlighting
  \item full integration with external programs
  \item templates
  \item document outline
  \item integrated debugging
  \item symbol completion
  \item many commands to write \LaTeX{} sources in less time.
\end{itemize}

Available key bindings are shown in the \textsf{Mode} menu entries, and
were defined in a hopefully intuitive and consistent manner. Some examples
are \texttt{Ctrl-Css} for
\textsf{Mode/\-Sections/\-\textbackslash{}section}, \texttt{Ctrl-Cec} for
the \texttt{center} environment, and so on. 

Thanks to this arrangement, this guide does not contain tables of key
bindings. It's much simpler to read the menus.

There is another important feature you'll want to use. Most commands are
\emph{region or word aware}. For example, if a region is defined and you
select \textsf{Mode/\-Environments/\-center}, that region will be included
in a \texttt{center} environment. If the cursor is positioned on a word
and you select \textsf{Mode/\-Font/\-\textbackslash{}emph}, the word will
be included in a \texttt{\textbackslash{}emph} command.

% -----

\subsection{Useful Keys}

In addition to all key bindings listed in the \textsf{Mode} menus, the
following keys are also useful:

\begin{itemize}
  \item \texttt{Ctrl-C} followed by one of the special characters
  \texttt{\& \$ \# \% \_ \textasciicircum{} \textasciitilde{}
  \textbackslash{}} will insert \texttt{\textbackslash{}\&
  \textbackslash{}\$ \textbackslash{}\# \textbackslash{}\%
  \textbackslash{}\_} \texttt{\textbackslash{}text\-ascii\-circum{}
  \textbackslash{}text\-ascii\-tilde{}
  \textbackslash{}text\-back\-slash{}}
  \item \texttt{Ctrl-C} followed by \texttt{\{} will insert a couple of
  curly braces \texttt{\{\}}. This command is region or word aware.
  \item the single and double quote characters will self insert as smart
  quotes. That is, type \texttt{"word"} to obtain \texttt{``word''}
  \item three dots in a row will insert \texttt{{\textbackslash{}ldots}}.
\end{itemize}

% -----

\subsection{Symbol Completion}

This feature was borrowed by the old \texttt{latex.sl}. If you start
typing a \LaTeX{} keyword and type \texttt{Alt-TAB}, the keyword will self
complete. Type \texttt{Alt-TAB} again to cycle through possible
completions. For example, if you type \texttt{\textbackslash{}bib} you'll
cycle through \texttt{\textbackslash{}bib\-item[]\{\}},
\texttt{\textbackslash{}biblio\-grapy\{\}}, and
\texttt{\textbackslash{}biblio\-grapy\-style\{\}}.

Under X11, the window manager may reserve \texttt{Alt-TAB} for itself. MS
Windows uses this key binding to switch between tasks. In that case, use
\texttt{ESC-TAB}.

% -----

\subsection{Indentation}

\texttt{latex.sl} uses a sort of `preventive indentation' scheme.
Normally, a new line starts at the same column as the line above, but
lines within environments are indented. For example, start a
\texttt{center} environment with \texttt{Ctrl-Cec}: the text will be
indented by the amount specified by the variable \texttt{LaTeX\_Indent}.
The default is 2 columns, and can be changed as seen in
Section~\ref{sec:custom}.

If you wish to change the amount of indentation on the fly, select
\textsf{System/\-S-Lang Command} and type at the prompt:

\begin{verbatim}
S-Lang> LaTeX_Indent = 4;
\end{verbatim}

% -----

\subsection{Environments}

Environments can be entered via the \textsf{Mode/\-Environments} menu.
This method will provide the right indentation for both environment and
the text it surrounds.

Another way to start a new environment is typing \texttt{Ctrl-C[}. You'll
be prompted for the environment name, and the
\texttt{\textbackslash{}begin{}} line will be inserted. When you're done,
close the environment with \texttt{Ctrl-C]}.

% -----

\subsubsection{Itemize}

In \texttt{itemize} or \texttt{enumerate} environments you can use
\texttt{Ctrl-C\textless{}return\textgreater} to start a new
\texttt{\textbackslash{}item} line.

% -----

\subsubsection{Tables}

\texttt{latex.sl} makes it easier to write tables. When you start a
\texttt{table} or \texttt{tabular} environment, you'll be prompted for the
number of columns, then a table template will be inserted.

The \textsf{Mode/\-Environments/\-table row} menu will insert a line
containing the right number of \texttt{\&} delimiters, and terminated by
\texttt{\textbackslash{}\textbackslash{}}. Just fill in the blanks.

% -----

\subsection{Templates}

Templates for standard \LaTeX{} document classes: \texttt{article},
\texttt{book}, \texttt{letter}, \texttt{report}, \texttt{slides}, are
provided. In addition, templates for notices and for Prosper
presentations (\url{http://prosper.sourceforge.net}) have been added for
your convenience. The latter lets you write a presentation in minutes!

The most commonly used packages are also listed in the 
\textsf{Mode/\-Templates/\-Packages} sub-menu.

% -----

\subsection{Using a Master File}

When you work on complex documents, you can set a buffer as the `master
file'. That means that although you may be working on several \LaTeX{}
files at the same time, all operations of conversion, previewing etc. will
be performed on the master file. This is useful, for example, when you
have a main file that includes several parts.

If you disable the master file, all operations will be performed on the
current buffer.

% -----

\subsection{Document Outline}

Use this feature to navigate through complex documents. The
\texttt{*Outline*} buffer shows the document structure, listing all
\texttt{\textbackslash{}parts}, \texttt{\textbackslash{}sections}, etc.
and the line where they appear.

Press \texttt{\textless{}enter\textgreater} or double click on a section
to move to the relative line in the \LaTeX{} buffer, or `q' to quit.

% \begin{center}
%   \begin{figure}[htbp]
%     \includegraphics[width=\linewidth]{latex2.png}
%     \caption{An example of document outline.}
%     \label{fig:outline}
%   \end{figure}
% \end{center}

% -----

\subsection{Composing and Debugging}
\label{sec:composing}

\LaTeX{} documents are converted using four output profiles: dvi, ps, pdf,
and dvipdf. The final output is, respectively: a \texttt{.dvi} file, a
\texttt{.ps} file created with \texttt{dvips}, a \texttt{.pdf} file
created with \texttt{dvipdf}, and a \texttt{.pdf} file created with
\texttt{pdflatex}. The default output profile is dvi.

Select \textsf{Mode/\-Compose} to convert the buffer using the current
output profile. A `beep' will notify you of warnings, e.g.

\begin{verbatim}
Font Warning.
\end{verbatim}

If errors are detected, an error message appears:

\begin{verbatim}
Error(s) found! Press 'L' to switch to the log.
\end{verbatim}

Type `l' to inspect the \LaTeX{} log, or any other key to continue.

If you choose to examine the log, a new window pops up and the line that
explains the problem is highlighted. Now type `g' (go) to move to the line
in the \LaTeX{} source that caused the error, or \texttt{Ctrl-C'} to move
to the next error, or `q' to quit the log.

If the conversion succeeded, the following \textsf{Mode/\-View} command
will start the appropriate viewer.

% -----

\subsection{Maths}

It's virtually impossible to list all mathematical symbols
supported by \LaTeX{} in a menu. That said, most symbols are available
under \textsf{Mode/\-Math}.

Greek letters are obtained typing \texttt{Ctrl-Cm} and a letter; the 
equivalent Greek letter, if available, will be inserted. For instance,
\texttt{Ctrl-Cma} inserts \texttt{\textbackslash{}alpha}, and
\texttt{Ctrl-CmG} inserts \texttt{\textbackslash{}Gamma}. 

All available symbols are provided by the file \texttt{ltx-math.sl},
included in the Jed distribution. In addition, \texttt{Ctrl-C} followed by
an arrow key produces ono of these: \texttt{\textbackslash{}leftarrow
\textbackslash{}rightarrow \textbackslash{}uparrow
\textbackslash{}downarrow}.

% -----

\subsection{Notes on BiB\TeX}

\LaTeX{} mode doesn't provide any support for writing BiB\TeX{} files. Jed
has an excellent BiB\TeX{} mode already. Edit a file with the
\texttt{.bib} extension to turn BiB\TeX{} mode on.

% -----

\section{Known Problems}

The current implementation of syntax highlighting could be improved. The
most apparent problem is that text enclosed in curly braces isn't always
highlighted correctly. This is a limitation of the DFA code in Jed.

The documentation (this guide) is probably a bit too concise.

% -----

\section{The End}

\texttt{latex.sl} was written and is copyrighted \textcopyright{} by Guido
Gonzato, \url{guido.gonzato@univr.it}.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MER\-CHAN\-TA\-BI\-LI\-TY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

I use \texttt{latex.sl} every day, and I think it's very complete.
However, I'll be glad to receive suggestions and requests from you. If you
find a bug or would like to see a new feature added, please feel free to
contact me.

Enjoy! \texttt{=8-)}

% -----

\end{document}
