
\chapter{Advanced features of GNU TeXmacs}

\section{Automatically generated content}

\subsection{Generating a table of contents}

It is very easy to generate a table of contents for your document.
Just put your cursor at the place where you want your table of contents and
click on \subsubmenu{Insert}{automatic}{table of contents}.

In order to generate the table of contents, you should be in a mode where
page breaks are visible (select paper in \subsubmenu{Document}{page}{type}),
so that the appropriate references to page numbers can be computed.
Next, use \subsubmenu{Document}{update}{table of contents} or
\subsubmenu{Document}{update}{all} to generate the table of contents.
You may have to this several times, until the document does not
change anymore. Indeed, the page numbers may change as a result of
modifications in the table of contents!

\subsection{Compiling a bibliography}

At the moment, {\TeXmacs} uses ¤bibtex¤ to compile bibliographies.
The mechanism to automatically compile a bibliography is the
following:
\begin{itemize}
  \item
    Write a ¤.bib¤ file with all your bibliographic references.
    This file should have the format of a standard bibliography
    file for {\LaTeX}.
  \item
    Use \subsubmenu{Insert}{link}{citation} and
    \subsubmenu{Insert}{link}{invisible citation} to
    insert citations, which correspond to entries in your ¤.bib¤ file.
  \item
    At the place where your bibliography should be compiled,
    click on \subsubmenu{Insert}{automatic}{bibliography}.
    At the prompt, you should enter a ¤bibtex¤ style
    (such as ¤plain¤, ¤alpha¤, ¤abbrv¤, etc.) and
    your ¤.bib¤ file.
  \item
    Use \subsubmenu{Document}{update}{bibliography}
    in order to compile your bibliography.
\end{itemize}

\subsection{Generating an index}

For the generation of an index, you first have to put index entries
in your document using \subsubmenu{Insert}{link}{index entry}.
At a second stage, you must put your cursor at the place where you
want your index to be generated and click on
\subsubmenu{Insert}{automatic}{index}.
The index is than generated in a similar way as the table of contents.

In the \subsubmenu{Insert}{link}{index entry} menu,
you find several types of index entries.
The simplest are ``main'', ``sub'', ``subsub'',
which are macros with one, two and three arguments respectively.
Entries of the form ``sub'' and ``subsub'' may be used to
subordinate index entries with respect to other ones.

A complex index entry takes four arguments.
The first one is a key how the entry has to be sorted and
it must be a ``tuple'' (created using \key{esc}-\key{i}-\key{$<$})
whose first component is the main category, the second a subcategory, etc.
The second argument of a complex index entry is either blank or
``strong'', in which case the page number of your entry will
appear in a bold typeface. The third argument is usually blank,
but if you create two index entries with the same non-blank
third argument, then this will create a ``range'' of page numbers.
The fourth argument, which is again a tuple, is the entry itself.

It is also possible to create an index line without a page number
using ``interject'' in \subsubmenu{Insert}{link}{index entry}.
The first argument of this macro is a key for how to sort
the index line. The second argument contains the actual text.
This construct may be useful for creating different
sections ``A'', ``B'', etc. in your index.

\subsection{Compiling a glossary}

Glossaries are compiled in a similar way as indexes,
but the entries are not sorted. A ``regular'' glossary entry
just contains some text and a page number will be generated for it.
An ``explained'' glossary entry contains a second argument,
which explains the notation. A ``duplicate'' entry may be used
to create a page number for the second occurence of an entry.
A glossary line creates an entry without a page number.

\section{Page insertions and page breaking}

Complex documents often contain footnotes or floating objects,
which appear differently on pages as the main text.
In fact, the content of such complex documents use several
{\em flows\/}, one for the main text, one for the footnotes,
one for floats, and still another one for two column text.
The different flows are broken across pages in
a quite independent way.

\subsection{Footnotes and multicolumn material}

In order to insert a footnote,
you may use \subsubmenu{Insert}{page insertion}{footnote}.
The number of columns of the text may be changed in
\submenu{Paragraph}{number of columns}.

\subsection{Floating objects}

Floating objects are allowed to move on the page independently
from the main text. Usually they contain figures or tables
which are too large to nicely fit into the main text.
A floating object may be inserted using
\subsubmenu{Insert}{page insertion}{floating object}.

You may also create a floating object and directly insert
a figure or table inside it using
\subsubmenu{Insert}{page insertion}{floating figure} resp.
\subsubmenu{Insert}{page insertion}{floating table}.
However, sometimes you might want to insert several smaller
figures or tables inside one floating object.
You may do this using \subsubmenu{Insert}{image}{small figure}
resp. \subsubmenu{Insert}{table}{small table}.

After creating a floating object, you may control its position
using \submenu{Insert}{position float} (when inside the float).
You may specify whether you allow the floating object to appear at
the top of the page, at the bottom, directly in the text,
or on the next page. By default, the float may appear everywhere.
However, a floating object will never appear inside the main text
at less than three lines from the bottom or the top of a page.

\subsection{Page breaking}

The page breaking may be controlled very precisely by the user inside
\subsubmenu{Document}{page}{breaking}. In the submenu \menu{algorithm},
you may specify the algorithm being used. Professional page breaking
is best in print, but may slow down the editing when being used
interactively in paper mode. Sloppy page breaking is fasted and
medium is professional except for multicolumn material,
for which the professional algorithm is significantly slower.

You may also allow the page breaking algorithm to enlarge or reduce
the length of pages in exceptional cases in the submenu \menu{limits}.
The stretchability of vertical space between paragraphs and so
may be specified in \menu{flexibility}. The factor $1$ is default;
a smaller factor enforces a more rigid spacing, but the quality
of the breaks may decrease.

\section{Books and multi-file documents}

When a document gets really large, you may want to subdivide it
into smaller pieces. This both makes the individual pieces more easily
reusable in other work and it improves the speed of editing them.
An entire file can be inserted into another one using
\subsubmenu{Insert}{link}{include}. In order to speed up
the treatment of included documents, they are being buffered.
In order to update all included documents, you should use
\subsubmenu{Options}{update}{inclusion}.

If you are writing a book, one usually puts the individual chapters
in files ¤c1.tm¤, ¤c2.tm¤ until ¤cn.tm¤. One next creates one file
¤book.tm¤ for the whole book, in which the files ¤c1.tm¤, ¤c2.tm¤
until ¤cn.tm¤ are included using the above mechanism.
The table of contents, bibliography, etc. are usually
put into ¤book.tm¤.

In order to see cross references to other chapters when editing
a particular chapter ¤ci.tm¤, one may specify ¤book.tm¤ as
a ``master file'' for ¤ci.tm¤ using \subsubmenu{Document}{master}{attach}.
Currently, the chapter numbers themselves are not dealt with
by this mechanism. You may want to manually assign the environment
variable ¤chapternr¤ at the start of each chapter in order to
get the numbering right when editing.
