
\chapter{GNU TeXmacs and its port to Guile}

Like emacs, \TeXmacs\ comes with a lisp-like extension language,
namely the {\sc Guile Scheme} dialect from the {\sc Gnome} project.
For documentation about {\sc Guile Scheme}, we refer to
\begin{verbatim}
   http://www.gnu.org/software/guile/guile.html
\end{verbatim}
{\scheme} has the advantage that it may be extended with
extern C and C++ types and routines. In our case, we have extended
{\scheme} with routines which you can use to create your own menus
and key-combinations, and even to write your own extensions to \TeXmacs.

If you have downloaded the source files of \TeXmacs,
then it may be interesting for you to take a look at the files
\begin{verbatim}
   Guile/Glue/build-glue-basic.scm
   Guile/Glue/build-glue-editor.scm
   Guile/Glue/build-glue-server.scm
\end{verbatim}
These three ``glue'' files contain the C++ routines,
which are visible within {\scheme}.
In what follows, we will discuss some of the most
important routines. We plan to write a more complete
reference guide later. You may also take a look at the scheme
€.scm€ files in the directory €$TEXMACS_PATH/progs€. %$

\section{Writing your own initialization file}

When starting up, \TeXmacs\ executes the file
€$TEXMACS_PATH/progs/Init.scm€, %$
unless you have specified your own initialization file in
€$TEXMACS_HOME_PATH/progs/Init.scm€.
By default, the path €$TEXMACS_HOME_PATH€ equals €.TeXmacs€.
Usually, you want to add some extra actions
to the default initialization file.
In this case, you should not forget to include the command
\begin{verbatim}
    (exec-file "$TEXMACS_PATH/progs" "Init.scm")
\end{verbatim}
in your personal initialization file. %$
Similarly, the file €$TEXMACS_PATH/progs/Init-buffer.scm€ is executed, %$
each time you create a new buffer, unless you provide your
own initialization file €$TEXMACS_HOME_PATH/progs/Init-buffer.scm€. %$

\section{Creating your own dynamic menus}

In particular, the default initialization file executes
\begin{verbatim}
    $TEXMACS_PATH/progs/menu/main_menu.scm
\end{verbatim}%$
in order to set up the {\TeXmacs} main menu.
We suggest you to have a look at this file in order
to see how menus are created.

Actually, any menu or part of a menu is represented by a program.
The program consists of a list of programs of one of the following forms:
\begin{verbatim}
    (=> "pulldown menu name" menu-definition)
    (-> "pullright menu name" menu-definition)
    ("entry" action)
    ("entry" "shorthand" action)
    ---
    (if condition menu-definition)
    (link variable)
\end{verbatim}
The constructors €=>€ and €->€ are used to create pulldown or pullright
menus and €menu-definition€ should contain a program which creates the submenu.
The constructor €("entry" action)€ creates an ordinary entry,
where €action€ will be compiled and executed when you click on €entry€.
The optional €"shorthand"€ stands for a keyboard macro with the same action.
Items of a menu may be separated using €---€.
The constructor €if€ is used for inserting menu items only
if a certain €condition€ is satisfied (for instance, if we are in math mode).

Finally, if we declared a {\TeXmacs} variable to be a menu by
\begin{verbatim}
    (define variable menu-definition)
\end{verbatim}
then we may use this menu indirectly using the €link€ constructor.
This indirect way of declaring submenus has two advantages
\begin{itemize}
  \item An ``indirect'' submenu may be linked to as many menus as we like.
  \item New items may be added to ``indirect'' submenus
        {\em a posteriori\/} using
\begin{verbatim}
    (set! variable (menu-merge variable menu-declaration))
\end{verbatim}
        Actually, existing terms may also be overwritten in this way.
\end{itemize}
Some standard {\TeXmacs} indirect menus are
€texmacs-menu€, €file-menu€, €edit-menu€, €insert-menu€,
€text-menu€, €paragraph-menu€, €document-menu€,
€options-menu€ and €help-menu€. The command
\begin{verbatim}
    (menu-main menu-declaration)
\end{verbatim}
is used in order to actually set the main menu.
For instance, at initialization, we execute\nopagebreak
\begin{verbatim}
    (menu-main '(link texmacs-menu))
\end{verbatim}

\section{Creating your own key-combinations}

Keymaps are specified using the command
\begin{verbatim}
    (set-keymap (list of predicates) (list of keymaps))
\end{verbatim}
The list of predicates specifies under which circumstances
the keymaps are valid. Examples of predicates are €always?€,
€in-math?€ and €in-french?€, but the user may define his
own predicates. Each map is of one of the following forms
\begin{verbatim}
    (key-combination action_1 ... action_n)
    (key-combination result)
    (key-combination help-message result)
\end{verbatim}
In the first case, the €action_i€ are {\scheme} commands
associated to the string €key-combination€.
In the second and third case, €result€ is a string which is to be inserted
in the text when the €key-combination€ has been completed.
An optional €help-message€ may be displayed when
the €key-combination€ is finished.

Kemaps can be cleared again using the command
\begin{verbatim}
    (remove-keymap (list of predicates) (list of key combinations))
\end{verbatim}
where the second arguments is a list of strings,
each of which is a €key-combination€ as above.

\section{Other files}

Some other files may also be worth looking at:
\begin{itemize}
  \item €$TEXMACS_PATH/fonts/enc€ contains encodings
        for different {\TeX} fonts. %$
  \item €$TEXMACS_PATH/fonts/virtual€ contains definitions of %$
        virtual characters.
  \item €$TEXMACS_PATH/langs/natural/dic€ contains %$
        the current dictionaries used by \TeXmacs.
  \item €$TEXMACS_PATH/langs/natural/hyphen€ %$
        contains hyphenation patterns for various languages.
  \item €$TEXMACS_PATH/progs/fonts€ contains {\scheme} programs %$
        for setting up the fonts.
\end{itemize}
