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 GNU 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 %appdata%\TeXmacs on Windows or $HOME/.TeXmacs on GNU/Linux and macOS. Similarly, each time you create a new buffer (either by creating a new file or opening an already existing one), the file 

    $TEXMACS_PATH/progs/init-buffer.scm

is executed, as well as 

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

if it exists.

Example 1. Suppose you want to add a style package CustomStyle.ts of your own to every new document you create. You can add the following lines to $TEXMACS_HOME_PATH/progs/my-init-buffer.scm: 

(when (buffer-newly-created? (current-buffer))
  (set-style-list (append (get-style-list) '("CustomStyle")))
  (buffer-pretend-saved (current-buffer)))

First we check whether the current-buffer has been newly created in order not to apply the style to existing files when we open them. Then we add the new package (instead of changing it with init-style) using set-style-list and finally we call buffer-pretend-saved to prevent TeXmacs from thinking the buffer has been modified by the change of style, or it would always prompt asking for confirmation before closing an empty buffer.

3.Creating your own dynamic menus

You may define a menu with name name either using 

(menu-bind name . def)

or 

(tm-menu (name) . def)

Here def 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. In the case of tm-menu, it is possible to specify additional arguments, which makes it possible to dynamically construct more complex menus which depend on parameters.

More precisely, the program def in menu-bind or tm-menu 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)
(when condition menu-definition)
(link variable)
(former)

The constructors => and -> are used to create pulldown or pullright menus and menu-definition should contain a program which creates the submenu. In the main (or system) menu bar all root items are pulldown menus and all submenus of these are pullright. Both pulldown and pullright may be used in toolbars or other widgets.

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), whereas while always inserts the item but deactivates (e.g. greying it out) it condition is not met.

If you declared a menu name, then you may use this menu indirectly using the link constructor, thus one may link any such “indirect” submenu to as many menus as desired.

Finally, new items may be added to any given menu a posteriori using former, as in the following example: 

(tm-menu (tools-menu)
  (former)
  ---
  ("New item" (noop)))

The main TeXmacs menus are:

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:

© 1999–2003 by Joris van der Hoeven