
\chapter{Introduction to GNU TeXmacs}

\section{Getting started}

Before starting to type some text,
you might want to do one or more of the following operations:
\begin{itemize}
  \item Give your document a name (click on \submenu{File}{save as}) or
        load an existing document (using \submenu{File}{load}).
  \item If you want to type text in a foreign language,
        you can set the language of the document in
        the \submenu{Document}{language} menu.
        In \submenu{Options}{language} you can also choose
        a foreign language for the editor's menus and messages.
  \item You usually should specify a \tmdef{document style} in the menu
        \submenu{Document}{style}, such as letter, article, book, etc.
        This provides a standard layout for section numbering,
        page headers and footers, theorems, etc.
  \item You should specify your printers paper format
        in the menu \subsubmenu{Document}{page}{size},
        if you intend to print your document (default is a4).
\end{itemize}

\begin{remark}
  When you get more familiar with the editor, you may write your
  own \tmref{initialization files}{}{},
  which perform the above operations automatically each time you
  start up the editor or when starting a new file.
\end{remark}

\section{Typing text}

\subsection{Generalities}

As soon as you have performed the preparatory actions as explained above,
you can start typing. The usual English characters and punctuation symbols
can easily be obtained on most keyboards. Accented characters from
foreign languages can systematically be obtained using the escape key.
For instance, ``\'e'' is obtained by typing \key{esc}-\key{'}-\key{e}.
Similarly, we obtain ``\`a'' via \key{esc}-\key{`}-\key{a} and so on.
Long words at borders of successive lines are automatically hyphenated.
In order to hyphenate foreign languages correctly, you should specify
the language of the document in the menu \submenu{Document}{language}.

At the left hand side of the footer, you see the document style,
the text properties at the current cursor position.
Initially, it displays ``text roman 12'', which means that
you type in text mode using a 12 point roman font and no document style.
You can change the text properties (font, font size, color, language)
in the \menu{Text} menu. You can also change the text properties
of the text you have already typed by \tmref{selecting a region}{}{}
and then change the text properties in the \menu{Text} menu.
Some text properties can also be changed for all the document
in the \submenu{Document}{font} and \submenu{Document}{language} menus.

At the right hand side of the footer, the character or object
(like a change in the text properties) just before the cursor is displayed.
We also display all environments which are active at the cursor position.
This information should help you to orient yourself in the document.

\subsection{Layout issues}

As a general rule, \TeXmacs\ takes care of the layout of your text.
Therefore, although we did not want to forbid this possibility,
we do not encourage you to typeset your document visually.
For instance, you should not insert spaces or blank lines as
substitutes for horizontal and vertical spaces between words and lines;
instead, additional space should be inserted explicitly
using \submenu{Insert}{space}. This will make your text
more robust in the sense that you will not have to reconsider
the layout when performing some minor changes, which affect
line or page breaking, or major changes, such as changing
the document style.

Several types of explicit spacing commands have been implemented.
First of all, you can insert rigid spaces of given widths and heights.
Horizontal spaces do not have a height and are either stretchable or not.
The length of a stretchable spaces depends on the way a paragraph
is hyphenated. Furthermore, it is possible to insert tabular spaces.
Vertical spaces may be inserted either at the start or
the end of a paragraph: the additional vertical space between two
paragraphs is the maximum of the vertical space after the first one
and the vertical space before the second one (contrary to {\TeX},
this prevents from superfluous space between two consecutive theorems).

As to the paragraph layout, the user may specify the paragraph style
(justified, left ragged, centered or right ragged), the paragraph
margins and the left (resp. right) indentation of the first
(resp. last) line of a paragraph. The user also controls
the spaces between paragraphs and successive lines in paragraphs.

You can specify the page layout in the \submenu{Document}{page} menu.
First of all, you can specify the way pages are displayed on the screen:
when selecting ``paper'' as page type in \subsubmenu{Document}{page}{type},
you explicitly see the page breaks. By default, the page type is ``papyrus'',
which avoids page breaking during the preparation of your document.
The ``automatic'' page type assumes that your paper size is exactly
the size of your window. The page margins and text width are specified
in \subsubmenu{Document}{page}{layout}. Often, it is convenient to
reduce the page margins for usage on the screen;
this can be done in \subsubmenu{Document}{page}{screen layout}.

\section{Typing structured text}

Usually, long documents have a structure: they are organized in chapters,
sections and subsections, they contain different types of text,
such as regular text, citations, footnotes, theorems, etc.
After selecting a \tmdef{document style} in \submenu{Document}{style},
\TeXmacs\ takes care of specific layout issues, such as numbering of
sections, pages, theorems, typesetting citations, footnotes and
theorems in a nice way and so on.

Currently, four document standard styles have been implemented:
letter, article, book and seminar. The seminar style is used for
making transparencies. As soon as you have selected such a style,
you can organize your text into sections (see \submenu{Insert}{section})
and use specific \tmdef{environments}. Examples of environments
are theorem, proposition, remark and so on (see \submenu{Insert}{environment}).
Other examples are lists of items (see \submenu{Insert}{itemize}) or
numbered lists (see \submenu{Insert}{enumerate}).

When you get more acquainted with \TeXmacs, it is possible to add
your own \tmref{new environments}{}{} in your own
\tmref{style file}{}{}. Assume for instance that
you often make citations and that you want those to appear in italic,
with left and right margins of 1cm. Instead of manually changing
the text and paragraph properties each time you make a citation,
it is better to create a citation environment.
Not only it will be faster to create a new citation when doing so,
but it is also possible to systematically change
the layout of your citations throughout the document
just by changing the definition of the citation environment.
The latter situation occurs for instance if you discover
\emph{a posteriori} that you prefer the citations to appear
in a smaller font.

\section{Typing mathematics}

Up till now, we have only considered typing in text mode.
You can enter ``math mode'' by pressing the \key{\$}-key or %$
by inserting an equation (using \subsubmenu{Insert}{mathematics}{equation}).
In math mode, you have specific commands and key-combinations to
type mathematical symbols and formulas.

The editor favorites typing mathematics with a certain meaning.
This feature, which will be developed more in future releases,
is useful when communicating with a computer algebra package.
At this moment, you should for instance explicitly type
the multiplication \key{$*$} between symbols $a$ and $b$.
By default, typing \key{a}-\key{b} will yield $\text{ab}$
and not $ab$.

\subsection{Mathematical symbols}

The Greek characters are obtained in \TeXmacs\ by combining
the \key{alt}-key with a letter. For instance, \key{alt-a} yields
$\alpha$ and \key{alt-shift-g} yields $\Gamma$. Variants are obtained by
the \key{$\star$}-key. For instance, \key{alt-p}-\key{$\star$} yields $\varpi$.

Many other mathematical symbols are obtained by ``natural''
key-combinations. For instance, \key{$-$}-\key{$>$} yields $\rightarrow$,
\key{$-$}-\key{$-$}-\key{$>$} yields $\longrightarrow$ and
\key{$>$}-\key{$=$} yields $\geqslant$. Similarly,
\key{$|$}-\key{$-$} yields $\vdash$, \key{$|$}-\key{$-$}-\key{$>$}
yields $\mapsto$ and \key{$-$}-\key{$>$}-\key{$<$}-\key{$-$}
yields $\rightleftarrows$.

Some general rules hold in order to obtain variants of symbols:
\begin{description}
  \item[\key{$\star$}] is the main key for obtaining variants.
        For instance, \key{$>$}-\key{$=$} yields $\geqslant$,
        but \key{$>$}-\key{$=$}-\key{$\star$} yields $\geq$.
        Similarly, \key{$<$}-\key{$\star$} yields $\prec$,
        \key{$<$}-\key{$\star$}-\key{$=$} yields $\preccurlyeq$ and
        \key{$<$}-\key{$\star$}-\key{$=$}-\key{$\star$} yields $\preceq$.
  \item[\key{\tmat}] is used for putting symbols into circles or boxes.
        For instance, \key{\tmat}-\key{+} yields $\oplus$ and
        \key{\tmat}-\key{x} yields $\otimes$. Similarly,
        \key{\tmat}-\key{$\star$}-\key{+} yields $\boxplus$.
  \item[\key{/}] is used for negations. For instance,
        \key{$=$}-\key{/} yields $\neq$ and \key{$<$}-\key{$=$}-\key{/}
        yields $\not{\leqslant}$. Notice that
        \key{$<$}-\key{$=$}-\key{$\star$}-\key{$\star$}-\key{/}
        yields $\nleqq$, while
        \key{$<$}-\key{$=$}-\key{$\star$}-\key{$\star$}-\key{/}-\key{$\star$}
        yields $\lneqq$.
\end{description}

\section{Editing facilities}

\subsection{Cut and paste}

You can select text and formulas by maintaining the left mouse button.
In order to delete the selected region, use \submenu{Edit}{cut}.
In order to copy the selected region, first click on \submenu{Edit}{copy}.
Next, paste it as many times as you want to the location of your cursor,
using \submenu{Edit}{paste}. Alternatively, you may copy a selected
region using the middle mouse button.

It is also possible to the change text properties of a selected region.
For instance, in order to transform some black text in red,
you select it using the left mouse button and click on
\subsubmenu{Text}{colour}{red}. Similarly, if you select a formula and
you click on \subsubmenu{Insert}{mathematics}{fraction},
then the formula becomes the numerator of some fraction.

When using the copy and paste mechanism to communicate with
other applications, text is copied and pasted using the {\TeXmacs}
data format. You may specify other import and export formats
using \submenu{Edit}{import} resp. \submenu{Edit}{export}.
By default, copying and pasting uses the primary text buffer.
Using \submenu{Edit}{copy to} and \submenu{Edit}{paste from},
you may specify as many other buffers as you like.

\subsection{Search and replace}

You can start searching text by pressing \key{ctrl-s} or
\submenu{Edit}{search}. During a search, the ``search string'' is
displayed at the left hand side of the footer. Each character you
type is appended to this search string and the next occurrence of
it is surrounded by a red box. When pressing \key{ctrl-s}
a second time during a search, the next occurrence is being searched.
A beep indicates that no more occurrences were found in the document;
pressing \key{ctrl-s} will continue the search at the beginning of
your document. You may press \key{backspace} in order to undo
keypresses during a search.

Usually, text is being searched for in a forward manner,
starting from the current cursor position. You may also
search backwards, using \key{ctrl-r}. During a search,
only text in the same mode and the same language will be found,
as those which are active at the position where you started your
search. In other words, when searching an $x$ in math-mode,
you will not find any x's in the ordinary text.
As a current limitation, the search string can only
contain ordinary text and no math-symbols or more
complicated structured text.

A query replace is started by pressing \key{ctrl-=} or
\submenu{Edit}{replace}. You are prompted for a string which
is to be replaced and the string by which to replace.
At each occurrence of the string to be replaced you are prompted
and you have to choose between replacing the string (y),
not replacing it (n) and replace this and all further occurrences (a).
Like in the case of searching, the query-replace command is
mode and language sensitive.

\subsection{Spell checker}

If the program €ispell€ has been installed on your system,
then you may use it to check your text for misspelled words
by pressing \key{esc}-\key{\$} or \submenu{Edit}{spell}. %$
Notice that you might have to verify that the dictionaries
corresponding to the languages in which your texts have
been written have been installed on your system;
this is usually the case for english.

When you launch the spell checker (either on the whole
text or a selected region), you will be prompted at each
misspelled word and the footer displays the available options:
\begin{description}
  \item[a)]
    Accepts the misspelled word and all its future occurrences
    in the text.
  \item[r)]
    Replace the misspelled word by a correction you have to enter.
  \item[i)]
    Indicate that the ``misspelled'' word is actually correct and
    that it has to be inserted in your personal dictionary.
  \item[1-9)]
    Several suggested corrections for your misspelled word.
\end{description}
Notice that €ispell€ just checks for misspelled words.
No grammatical faults will be detected.

When starting the spell checker, it will use the dictionary of
the language which is active at the current cursor position
(or the start of a selection). Only text in that language will
be checked for. If your document contains text in several
languages, then you will have to launch the spell checker once
for each language being used.

\subsection{Undo and redo}

It is possible to gradually undo the changes you made in a document
from the moment that you launched {\TeXmacs}. This can be done via
\submenu{Edit}{undo} or using the keystrokes \key{esc}-\key{[} or
\key{ctrl-/}. Undone changes can be ``redone'' using
\submenu{Edit}{redo} or \key{esc}-\key{]}.

In order to save memory, the number of successive actions which
can be undone is limited to~100 (by default).
It is possible to increase this number by adding a command like
\begin{verbatim}
    (set-maximal-undo-depth 1000)
\end{verbatim}
in our personal initialization file (see \submenu{Help}{scheme}).
When specifying a negative number as your maximal undo depth,
any number of actions can be undone.

\section{Miscellaneous issues}

\subsection{The font selection system}

In \TeXmacs, fonts have five main characteristics:
\begin{itemize}
  \item Its name (roman, pandora, concrete, etc.).
  \item Its family (roman, typewriter or sans serif).
  \item Its size (a base size (in points) and a relative size
        (normal, small, etc.).
  \item Its series (bold, medium or light).
  \item Its shape (right, italic, small caps, etc.).
\end{itemize}
Notice that in the font selection system of {\LaTeX} $2\varepsilon$,
the font name and family are only one (namely, the family).
Notice also that the base font size is specified for
the entire document in \subsubmenu{Document}{font}{size}.

\subsection{Including images}

You can include images in the text using the menu \submenu{Insert}{image}.
Currently, {\TeXmacs} recognizes the €ps€, €eps€, €tif€, €pdf€, €pdm€,
€gif€, €ppm€, €xpm€ and €fig€ file formats. Here, €gs€ (i.e. ghostscript)
is used to render postscript images. If ghostscript has not yet been
installed on your system, you can download this package from
\begin{verbatim}
    www.cs.wisc.edu/~ghost/index.html
\end{verbatim}
Currently, the other file formats are converted into postscript files
using the scripts €tiff2ps€, €pdf2ps€, €pnmtops€, €giftopnm€,
€ppmtogif€, €xpmtoppm€. If these scripts are not available on your system,
please contact your system administrator.

By default, images are displayed at their design size.
The following operations are supported on images:
\begin{itemize}
  \item Clipping the images following a rectangle.
        The lower left corner of the default image is taken as
        the origin for specifying a rectangle for clipping.
  \item Resizing an image. When specifying a new width,
        but no height at the prompt (or vice versa),
        the image is resized so as to preserve the aspect ration.
  \item Magnifying the image. An alternative way to resize an image,
        by multiplying the width and the height by a constant.
\end{itemize}

We also included a script to convert pictures,
with optional {\LaTeX} formulas in it, into encapsulated postscript.
In order to include a {\LaTeX} formula in an €xfig€ picture,
we recall you should enter the formula as text,
while selecting a {\LaTeX} font and setting the special flag
in the text flags.

\subsection{Hyperlinks and actions}

It is possible to create hyperlinks to other documents using
\key{esc}-\key{i}-\key{$>$} or \subsubmenu{Insert}{link}{hyperlink}.
The first field of the hyperlink is the associated text,
which is displayed in blue when activated.
The second field contains the name of a document,
which may be on the web.

In a similar fashion, an action may be associated to a piece of
text or graphics using \key{esc}-\key{i}-\key{*} or
\subsubmenu{Insert}{link}{action}.
The second field now contains a Guile/Scheme script command,
which is executed whenever you double click on the text,
after its activation. For security reasons, such scripts
are not always accepted. By default, you are prompted for
acceptation; this default behaviour may be changed in
\submenu{Options}{security}. Notice that the Guile/Scheme command
\begin{verbatim}
    (system "shell-command")
\end{verbatim}
evaluates €shell-command€ as a shell command.

\section{Conversion of TeXmacs documents}

\subsection{Printing}

You can print the current file using \subsubmenu{File}{print}{print all}.
By default, \TeXmacs\ assumes that you have a 600dpi printer for a4 paper.
These default settings can be changed using
\subsubmenu{File}{print}{setup printer}.
You can also print to a postscript file using
\subsubmenu{File}{print}{print all to file} (in which case
the default printer settings are used for creating the output) or
\subsubmenu{File}{export}{postscript} (in which case the printer
settings are ignored).

As to the WYSYWYG-ness of \TeXmacs, the editor guarantees that
you get the same output on paper as on screen as long as
the screen characters use the same number of dots per inch
as your printer (see \subsubmenu{Document}{font}{dpi}).
This is due to the fact that the bounding boxes for
the ink of TeX characters are currently computed from
the .pk and not from the .tfm files. Hence minor typesetting
changes may occur when changing the dpi, which may globally
affect the document through line and page breaking.
In a future release this drawback should be removed.

For matching dpi's, if you notice a real change between the appearance
on paper and on the screen (apart from pixel order changes in position
and boldness), then this means that you found a bug and please let me know.

\subsection{Compatibility with {\LaTeX}}

\TeXmacs\ has not been designed to be fully compatible with {\LaTeX}.
As to the conversion from {\LaTeX} to \TeXmacs, our main aim is to
\emph{help} you in converting old documents to \TeXmacs.
As long as you did not define weird environments and
as long as you did not use weird style files and commands,
you should be able to convert your old documents reasonably well.
Otherwise, we suggest to modify your old document in a way that is
does convert reasonably well and to apply some final changes in the result.

The conversion from \TeXmacs\ to {\LaTeX} is more reliable,
apart from minor changes in the layout, and as long as you do
not use specific features of \TeXmacs, mainly
\begin{itemize}
  \item Left primes.
  \item big separators between big parentheses.
  \item Mosaics.
  \item Trees.
  \item Vertical spaces ``before'' and ``after''.
  \item Indentation flags ``before'' and ``after''.
\end{itemize}

You may convert {\TeXmacs} documents to {\LaTeX}
using \subsubmenu{File}{export}{latex}.
We have provided a {\TeXmacs} style file in €misc/latex/TeXmacs.sty€.
By default, this style file is included in converted documents,
by the €usepackage€ command. If you send such a converted document
to someone else (i.e. a publisher), make sure that this person has
a copy of the file €TeXmacs.sty€.

We also notice that it is possible to use {\LaTeX} command names
for keyboard input. For instance, in math mode, you can create a fraction
by typing \key{$\backslash$}-\key{f}-\key{r}-\key{a}-\key{c}-\key{return}.

For more details about the conversion of {\TeXmacs} documents to
{\LaTeX} and vice versa can be found in the chapter
``compatibility with {\LaTeX}''.

\subsection{Compatibility with HTML}

We have started to implemented the conversion between
HTML and {\TeXmacs}. At this moment, it is only possible
to import HTML documents using \subsubmenu{File}{import}{html}.
Most of HTML 2.0 and parts of HTML 3.0 are currently supported.
However, no browsing facilities have been added yet.
In the future, we plan to implement Math-ML.

When importing HTML documents, files whose names start with
€http:€ or €ftp:€ will be downloaded from the web using €wget€.
If you compiled {\TeXmacs} yourself, then you can download €wget€ from
\begin{verbatim}
  ftp://ftp.gnu.org/pub/gnu/wget/
\end{verbatim}
In the binary distributions, we have included €wget€.
