
\chapter{Document styles}

\section{Main architecture}

To a document, it is possible to associate one or several document styles,
which are either standard or user defined. The main document style of
a document is selected in the \submenu{Document}{style} menu.
Extra styles can be added using \submenu{Document}{use package}.

From the editor point of view, each style corresponds to a ¤.ts¤ file.
The files corresponding to each style are processed in as if they were
usual documents, but at the end, the editor only keeps
the final environment as the initial environment for the main document.
More precisely, the style files are processed in order as well as
there own styles, in a recursive manner.

\section{Standard document styles}

Currently, the following standard document styles have been implemented:
\begin{itemize}
  \item Book;
  \item Article;
  \item Letter;
  \item Seminar (for transparencies).
\end{itemize}

Each of these styles export a certain number of standard functions and
environments listed below. All future standard document styles are expected
to support at least the above commands and environments and
we suggest users to write style files which do so too.
\begin{itemize}
  \item Sectioning commands.
  \item Itemize and enumerate environments.
  \item Equation like environments.
  \item Theorem like environments.
  \item Programming environments.
\end{itemize}

We notice that the theorem like environments are not standard in {\LaTeX},
which is a standard source of non compatibility.
New ``theorems'' can be added with the ¤newtheorem¤ command.
It is also possible to add new ``remarks'' with the ¤newremark¤ command;
``remarks'' are different from ``theorems'' in the sense that their
body is usually not typeset in an emphasized font.

Of course, programming environments are not supported by {\LaTeX} either.
Such environments are currently under development.

\section{User style files}

\subsection{Look at an example}

Before writing your own style file, it may be useful to take
a look at some standard style files. For instance, you may load
¤book.ts¤ using \submenu{File}{load} (no path is necessary here,
since the style directory is included in the default file path).

After loading ¤book.ts¤, you will see many function and
environment declarations (these declarations are visible,
since style files are written in ``preamble mode''
(see \submenu{Options}{mode})). Some more declarations are
contained in the files ¤basic.ts¤, ¤list.ts¤, ¤theorem.ts¤ and
¤program.ts¤ on which ¤book.ts¤ is based.
These files respectively contain basic, itemize-like,
theorem-like and programming environments.

\subsection{Some important paths}

Before writing your own style file,
it is useful to know the following important \TeXmacs\ paths:
\begin{itemize}
  \item ¤$TEXMACS_PATH¤ is the main path for \TeXmacs. %$
  \item ¤$TEXMACS_HOME_PATH¤ is the main user path for \TeXmacs\ files %$
        (documents, styles or programs). By default,
        this path is set to ¤~/.TeXmacs¤.
  \item ¤$TEXMACS_STYLE_PATH¤ contains the path for including style files. %$
        By default, this path contains ¤.¤, ¤$TEXMACS_PATH/styles¤ and %$
        ¤$TEXMACS_HOME_PATH/styles¤. %$
  \item ¤$TEXMACS_FILE_PATH¤ contains the path for searching text files. %$
        By default, this path contains ¤$TEXMACS_STYLE_PATH¤, %$
        ¤$TEXMACS_PATH/texts¤ and ¤$TEXMACS_HOME_PATH/texts¤.
\end{itemize}

\subsection{Writing your own style file}

The main key-combinations that you should know to write style files
are the following:
\begin{description}
  \item[\key{esc}-\key{$=$}]
    creates a new assignment.
    The first argument is a new command name and
    the second argument an expression.
  \item[\key{esc}-\key{w}]
    permits to locally change one or
    more environment variables. With statements are of the form
    $\langle x_1 | a_1 | \cdots | x_n | a_n | b \rangle$,
    where the $x_i$ are the names of the variables,
    the $a_i$ their local values, and $b$ the text on
    which the local environment applies.
  \item[\key{esc}-\key{m}]
    creates a macro.
    Arguments to the macro can be inserted using the \key{tab}-key.
  \item[\key{esc}-\key{f}]
    creates a function.
    Arguments to the macro can be inserted using the \key{tab}-key.
  \item[\key{esc}-\key{i}-\key{$\#$}]
    get the value of a macro argument.
  \item[\key{esc}-\key{i}-\key{v}]
    get the value of an environment variable.
  \item[\key{esc}-\key{i}-\key{e}]
    expands the macro with zero or more arguments.
  \item[\key{esc}-\key{i}-\key{a}]
    applies a function to zero or more arguments.
\end{description}
More precisely, when evaluating a macro expansion
$\{a|x_1|\cdots|x_n\}$ created by \key{esc}-\key{i}-\key{e},
the following action is undertaken:
\begin{itemize}
  \item If $a$ is not a string nor a macro, then $a$ is evaluated once.
        This results either in a macro name or a macro expression $f$.
  \item If we obtain a macro name, then we replace $f$
        by the value of the environment variable $f$.
        If, after this, $f$ is still not a macro expression,
        then we return $f$.
  \item Let $y_1, \ldots, y_n$ be the arguments of $f$ and $b$ it's body
        (superfluous arguments are discarded;
        missing arguments take the empty string as their default value).
        Then we substitute $x_i$ for each $y_i$ in $b$ and
        return the evaluated result.
\end{itemize}
Functions are similar to macros, except that the arguments of
function appliciations are evaluated and they can not be edited
in a direct way (you first need to deactivate the function application,
edit the arguments, and reactivate). Also, $y_1, \ldots, y_n$
are now rather considered as local environment variables,
which are given $x_1, \ldots, x_n$ as their values.
These local variables are not remembered when a function
returns a function which involves these variables.

\subsection{Computational markup}

The following commands can be used for performing dynamic computations:
\begin{description}
  \item[\key{esc-e}-\key{|}]
    sequential or of two conditions.
  \item[\key{esc-e}-\key{\^{}}]
    exclusive or of two conditions.
  \item[\key{esc-e}-\key{\&}]
    sequential and of two conditions.
  \item[\key{esc-e}-\key{!}]
    negation of a conditions.
  \item[\key{esc-e}-\key{+}]
    add two numbers or lengths.
  \item[\key{esc-e}-\key{-}]
    subtract two numbers or lengths.
  \item[\key{esc-e}-\key{$\star$}]
    multiply two numbers.
  \item[\key{esc-e}-\key{/}]
    divide two numbers.
  \item[\key{esc-e}-\key{;}]
    concatenate two strings.
  \item[\key{esc-e}-\key{$\#$}]
    display a number in Arabic, roman, Roman,
    alpha or Alpha (used for instance in enumerations).
  \item[\key{esc-e}-\key{$>$}]
    translate a word from a source language into a destination language
    (see the dictionaries in ¤$TEXMACS_PATH/data/dic¤). %$
  \item[\key{esc-e}-\key{=}]
    test equality.
  \item[\key{esc-e}-\key{esc-=}]
    test inequality.
  \item[\key{esc-e}-\key{?}]
    insert an if statement with an optional else part.
\end{description}

