
\chapter{The TeXmacs data format}

\section{Introduction}

{\TeXmacs} represents all texts by trees (for a fixed text,
the corresponding tree is called the \tmdef{edit tree}).
The inner nodes of such a tree are labeled by standard \tmdef{operators}
of type ¤tree_label¤ (see ¤Basic/Data/tree.gen.h¤).
The labels of the leaves of the tree are strings, which are either invisible
(such as lengths or macro definitions), or visible (the real text).

The meaning of the text and the way it is typeset essentially depends
on the current environment. The environment mainly consists of
a relative hash table of type ¤rel_hashmap<string,tree>¤,
i.e. a mapping from the environment variables to their tree values.
The current language and the current font are examples of system
environment variables; new variables can be defined by the user.

In what follows, we will describe the meanings of the different
stardard {\TeXmacs} operators. We will use {\scheme} notation.
The current {\TeXmacs} data format is unstable and
several changes will take place in the near future.
In the last section we will describe these changes.

\section{Leaves}

The encoding of normal text is described in the chapter about fonts.
Certain invisible data can also occur as leaves of {\TeXmacs} trees.
Common examples are lengths of boxes and spaces, auxiliairy data, etc.

\section{Main formatting operators}

\begin{description}
  \item[¤(document p1 ... pn)¤]$\text{}$\\
    The general form of the edit tree,
    which is a document consisting of the paragraphs ¤p1, ..., pn¤.
  \item[¤(concat t1 ... tn)¤]$\text{}$\\
    Horizontal concatenation of the trees ¤t1, ..., tn¤.
    Often, but not always, the paragraphs of the main edit tree
    are concatenations.
  \item[¤(surround left right body)¤]$\text{}$\\
    Surround multiparagraph text ¤body¤ by ¤left¤ and ¤right¤.
  \item[¤(hspace spc)¤ or ¤(hspace spc min max)¤]$\text{}$\\
    Horizontal space of length ¤spc¤. The optional ¤min¤ and ¤max¤
    parameters indicate that the space may be shrinked or extended to
    these values. We notice that certain units of length, like ¤fn¤,
    automatically provide shrinking and extension information.
  \item[¤(vspace* spc)¤ or ¤(vspace* spc min max)¤]$\text{}$\\
    Insert vertical space of length ¤spc¤ before this paragraph.
  \item[¤(vspace spc)¤ or ¤(vspace spc min max)¤]$\text{}$\\
    Insert vertical space of length ¤spc¤ after this paragraph.
  \item[¤(space spc bot top)¤]$\text{}$\\
    Insert horizontal space of length ¤spc¤, with bottom and top lines
    at heights ¤bot¤ resp. ¤top¤.
  \item[¤(htab spc)¤]$\text{}$\\
    Tabbing space of minimal length ¤spc¤.
  \item[¤(split pos1 ... posn)¤]$\text{}$\\
    Split the current paragraph as a table of ¤n¤ columns,
    which are alligned following ¤pos1, ..., posn¤.
  \item[¤(move t x y)¤]$\text{}$\\
    Move the tree ¤n¤ horzontally by length ¤x¤ and vertically by length ¤y¤.
  \item[¤(resize t "normal" x1 y1 x2 y2)¤]$\text{}$\\
    New logical bounding box of ¤t¤ has ¤(x1,y1)¤
    as its lower left corner and ¤(x2,y2)¤ as its upper right corner.
  \item[¤(resize t "extend" x1 y1 x2 y2)¤]$\text{}$\\
    As above, but the new bounding box is forced to include the old one.
  \item[¤(format "line break")¤]$\text{}$\\
    Forces a line break.
  \item[¤(format "new line")¤]$\text{}$\\
    Forces a new line.
  \item[¤(format "line separator")¤]$\text{}$\\
    Like the {\TeX} ¤&¤ command.
  \item[¤(format "next line")¤]$\text{}$\\
    Like the {\TeX} ¤\\¤ command.
  \item[¤(format "no line break")¤]$\text{}$\\
    Prevents a line break.
  \item[¤(format "no first indentation")¤]$\text{}$\\
    Prevent left indentation for this paragraph.
  \item[¤(format "no last indentation")¤]$\text{}$\\
    Prevent right indentation for this paragraph.
  \item[¤(format "enable first indentation")¤]$\text{}$\\
    Force left indentation for this paragraph.
  \item[¤(format "enable last indentation")¤]$\text{}$\\
    Force right indentation for this paragraph.
  \item[¤(format "page break")¤]$\text{}$\\
    Forces a page break.
  \item[¤(format "new page")¤]$\text{}$\\
    Forces a new page.
  \item[¤(format "no page break before")¤]$\text{}$\\
    Prevents a page break before this line
  \item[¤(format "no page break after")¤]$\text{}$\\
    Prevents a page break after this line
  \item[¤(format "with limits")¤]$\text{}$\\
    Notify that the preceding text has limits.
    This results subscripts and superscripts to be placed
    under and over the preceding text.
\end{description}

\section{Mathematical operators}

\begin{description}
  \item[¤(group t)¤]$\text{}$\\
    Consider ¤t¤ as an entity (a bit like enclosing ¤t¤ within
    accolades in {\TeX}).
  \item[¤(left s)¤]$\text{}$\\
    A large left delimiter ¤s¤.
  \item[¤(middle s)¤]$\text{}$\\
    A large separator ¤s¤.
  \item[¤(right s)¤]$\text{}$\\
    A large right delimiter ¤s¤.
  \item[¤(big s)¤]$\text{}$\\
    A big operator ¤s¤.
  \item[¤(lprime s)¤]$\text{}$\\
    A left prime ¤s¤.
  \item[¤(rprime s)¤]$\text{}$\\
    A right prime ¤s¤.
  \item[¤(below t sub)¤]$\text{}$\\
    Subscript ¤sub¤ below ¤t¤.
  \item[¤(above t sup)¤]$\text{}$\\
    Superscript ¤sub¤ below ¤t¤.
  \item[¤(lsub script)¤]$\text{}$\\
    Left subscript ¤script¤ for text which follows.
  \item[¤(lsup script)¤]$\text{}$\\
    Left superscript ¤script¤ for text which follows.
  \item[¤(rsub script)¤]$\text{}$\\
    Right subscript ¤script¤ for preceding text.
  \item[¤(rsup script)¤]$\text{}$\\
    Right superscript ¤script¤ for preceding text.
  \item[¤(frac num den)¤]$\text{}$\\
    Fraction with numerator ¤num¤ and denominator ¤den¤.
  \item[¤(sqrt t)¤ or ¤(sqrt t n)¤]$\text{}$\\
    Square root of ¤t¤ or ¤n¤-th root of ¤t¤.
  \item[¤(wide t accent)¤]$\text{}$\\
    Wide ¤accent¤ above ¤t¤.
  \item[¤(neg t)¤]$\text{}$\\
    Wipe out ¤t¤ with a negation slash.
  \item[¤(tree root t1 ... tn)¤]$\text{}$\\
    Tree with root ¤root¤ and children ¤t1, ..., tn¤.
  \item[¤(matrix t11 ... t1m ...... tn1 ... tnm n m)¤]$\text{}$\\
    ¤n¤ by ¤m¤ matrix with entries ¤tij¤.
  \item[¤(table t11 ... t1m ...... tn1 ... tnm n m)¤]$\text{}$\\
    ¤n¤ by ¤m¤ table with entries ¤tij¤.
  \item[¤(mosaic t11 ... t1m ...... tn1 ... tnm n m)¤]$\text{}$\\
    ¤n¤ by ¤m¤ tabel whose entries ¤tij¤ can be aligned and merged.
  \item[¤(mosaic item t pos x y bg)¤]$\text{}$\\
    This field in a mosaic contains ¤t¤, is positioned at ¤pos¤,
    spans over ¤x¤ columns and ¤y¤ rows, and has background ¤bg¤.
\end{description}

\section{Environment variables, macros, functions, etc.}

\begin{description}
  \item[¤(assign var t)¤]$\text{}$\\
    Assign the environment variable ¤var¤ with ¤t¤.
  \item[¤(with var1 val1 ... varn valn body)¤]$\text{}$\\
    Locally assign the environment variable ¤var1, ..., varn¤
    with ¤val1, ..., valn¤ inside ¤body¤.
  \item[¤(expand f t1 ... tn)¤]$\text{}$\\
    Expand the macro ¤f¤ with arguments ¤t1, ..., tn¤.
  \item[¤(apply f t1 ... tn)¤]$\text{}$\\
    Apply the function ¤f¤ to ¤t1, ..., tn¤.
  \item[¤(func arg1 ... argn body)¤]$\text{}$\\
    Function with arguments ¤arg1, ..., argn¤ and body ¤body¤.
  \item[¤(argument var)¤]$\text{}$\\
    Macro argument ¤var¤.
  \item[¤(value var)¤]$\text{}$\\
    Value of ¤var¤.
  \item[¤(symbol s)¤]$\text{}$\\
    For entering a universal symbol.
  \item[¤(latex cmd)¤]$\text{}$\\
    For entering a {\LaTeX} command.
  \item[¤(hybrid cmd)¤]$\text{}$\\
    For entering a {\TeXmacs} function call,
    a {\LaTeX} command, or a universal symbol.
  \item[¤(quote t)¤]$\text{}$\\
    Evaluates to ¤t¤.
  \item[¤(eval t)¤]$\text{}$\\
    Evaluate ¤t¤.
  \item[¤(delay (cmd t1 ... tn))¤]$\text{}$\\
    Evaluates arguments ¤t1, ..., tn¤ to ¤u1, ..., un¤ and
    returns ¤(cmd u1 ... un)¤.
\end{description}

\section{Functional operators}

\begin{description}
  \item[¤(plus t u)¤]$\text{}$\\
    Add the numbers or lengths ¤t¤ and ¤u¤.
  \item[¤(minus t u)¤]$\text{}$\\
    Subtract the numbers or lengths ¤t¤ and ¤u¤.
  \item[¤(times t u)¤]$\text{}$\\
    Multiply the numbers ¤t¤ and ¤u¤.
  \item[¤(merge t u)¤]$\text{}$\\
    Concatenate the strings ¤t¤ and ¤u¤.
  \item[¤(number t what)¤]$\text{}$\\
    The number ¤t¤ in ¤what¤ (roman, alpha, etc.).
  \item[¤(translate t from into)¤]$\text{}$\\
    Translate ¤t¤ from ¤from¤ into ¤into¤.
\end{description}

\section{Other dynamic content}

\begin{description}
  \item[¤(inactive t)¤]$\text{}$\\
    Deactivate an environmental or invisible operator for editing.
  \item[¤(label name)¤]$\text{}$\\
    Label with name ¤name¤.
  \item[¤(reference name)¤]$\text{}$\\
    Reference to label with name ¤name¤.
  \item[¤(write t aux)¤]$\text{}$\\
    Write ¤t¤ to auxiliairy data buffer ¤aux¤.
    This construct is used for creating tables of contents,
    bibliographies, glossaries, etc.
  \item[¤(specific what t)¤]$\text{}$\\
    Specifies that ¤t¤ should only appear when the document
    is converted to ¤what¤. If ¤what¤ is ¤"TeXmacs"¤,
    then ¤t¤ only appears in {\TeXmacs} itself.    
  \item[¤(postscript file width height x1 y1 x2 y2)¤]$\text{}$\\
    Postscript (or other kind of) figure in ¤file¤,
    of width ¤width¤, length ¤length¤,
    lower left clipping corner ¤(x1,y1)¤ and
    upper right clipping corner ¤(x2,y2)¤.
    The parameters ¤width, height, x1, y1, x2, y2¤ may be empty strings,
    in which case the default settings of the image are used.
    The width and the height may also be of the form ¤*mag¤ or ¤/schrink¤,
    in which case the default lengths are magnified resp. shrinked by
    a factor ¤mag¤ resp. ¤schrink¤.
\end{description}

\section{For private use}

\begin{description}
  \item[¤(tuple t1 ... tn)¤]$\text{}$\\
    The tuple ¤(t1, ..., tn)¤.
  \item[¤(collection t1 ... tn)¤]$\text{}$\\
    The set ¤{t1, ..., tn}¤.
  \item[¤(associate t u)¤]$\text{}$\\
    The association ¤t -> u¤.
\end{description}

\section{Planned changes}

\begin{enumerate}
  \item
    Currently, the arities of {\TeXmacs} operators are not allowed to vanish
    (in which case they become leaves). For operators like¤ concat¤
    this not very clean nor very handy. We therefore plan to allow
    arities of zero. The formatting operators of the form ¤(format how)¤
    will in particular become operators of arity zero.
  \item
    We are not happy at all with the way tables are formatted.
    We currently provided imperfect ¤mosaic¤ and ¤split¤ operators,
    which should be replaced with a single, more powerful operator.
    However, we are not yet very sure about the right choice.
  \item
    Several extensions of the format should be foreseen.
    In ¤Typeset/data/data.gen.cc¤, you will notice
    that we have already introduced the ¤graphics¤, ¤point¤,
    ¤line¤, ¤arc¤ and ¤bezier¤ operators, which are not yet implemented.
    Other future operators will concern footnotes, multicolums,
    dynamic texts, graphics, computer algebra output,
    database or spreadsheet facilities, etc.
\end{enumerate}
