Customizing TeXmacs

One major feature of TeXmacs is that it can be highly customized. First of all, the most important aspects of the program can be configured in Edit→Preferences. Most other parts of TeXmacs can be entirely adapted or reprogrammed using the Guile/Scheme extension language. In the sequel, we give a short overview of how this works in simple cases.

1.Introduction to the Guile extension language

Like Emacs, TeXmacs comes with a Lisp-like extension language, namely the Guile Scheme dialect from the Gnome project. For documentation about Guile Scheme, we refer to

   http://www.gnu.org/software/guile/guile.html

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

   Guile/Glue/build-glue-basic.scm

   Guile/Glue/build-glue-editor.scm

   Guile/Glue/build-glue-server.scm

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.

2.Writing your own initialization files

When starting up, TeXmacs executes the file

    $TEXMACS_PATH/progs/init-texmacs.scm

as well as your personal initialization file

    $TEXMACS_HOME_PATH/progs/my-init-texmacs.scm

if it exists. By default, the path $TEXMACS_HOME_PATH equals .TeXmacs. Similarly, each time you create a new buffer, the file

    $TEXMACS_PATH/progs/init-buffer.scm

is executed, as well as

    $TEXMACS_HOME_PATH/progs/my-init-buffer.scm

if it exists.

3.Creating your own dynamic menus

You may define (or modify) a (part of a) menu with name name using

(menu-bind name . prog)

and append new entries to an existing (part of a) menu with name name using

(menu-extend name . prog)

Here prog is a program which represents the entries of the menu. In particular, you may take a look at the files in the directory

    $TEXMACS_PATH/progs/menu

in order to see how the standard TeXmacs menus are defined.

More precisely, the program prog in menu-set or menu-append is a list of entries of one of the following forms:

(=> "pulldown menu name" menu-definition)
(-> "pullright menu name" menu-definition)
("entry" action)
---
(if condition menu-definition)
(link variable)

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. 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 you declared a menu name, then you may use this menu indirectly using the link constructor. This indirect way of declaring submenus has two advantages

• An “indirect” submenu may be linked to as many menus as we like.
• New items may be added to “indirect” submenus a posteriori using menu-append.

The main TeXmacs menus are texmacs-menu, texmacs-popup-menu, texmacs-main-icons, texmacs-context-icons and texmacs-extra-icons. Other standard indirect menus are file-menu, edit-menu, insert-menu, text-menu, paragraph-menu, document-menu, options-menu and help-menu.

4.Creating your own keyboard shortcuts

Keymaps are specified using the command

(kbd-map . keymaps)

Optionally, you may specify conditions which must be satisfied for the keymap to be valid using the :mode option. For instance, the command

(kbd-map (:mode in-math?) . keymaps)

specifies a list of keyboard shortcuts which will only be valid in math-mode. Each item in keymaps is of one of the following forms:

(key-combination action_1 ... action_n)
(key-combination result)
(key-combination result help-message)

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.

5.Other interesting files

Some other files may also be worth looking at:

• $TEXMACS_PATH/fonts/enc contains encodings for different TeX fonts.
• $TEXMACS_PATH/fonts/virtual contains definitions of virtual characters.
• $TEXMACS_PATH/langs/natural/dic contains the current dictionaries used by TeXmacs.
• $TEXMACS_PATH/langs/natural/hyphen contains hyphenation patterns for various languages.
• $TEXMACS_PATH/progs/fonts contains Scheme programs for setting up the fonts.