When and how to use Scheme

You may invoke Scheme programs from TeXmacs in different ways, depending on whether you want to customize some aspects of TeXmacs, to extend the editor with new functionality, to make your markup more dynamic, and so on. In this section, we list the major ways to invoke Scheme routines.

User provided initialization files

In order to customize the basic aspects of TeXmacs, you may provide one or both of the initialization files

    ~/.TeXmacs/progs/my-init-texmacs.scm

    ~/.TeXmacs/progs/my-init-buffer.scm

The file my-init-texmacs.scm is loaded when booting TeXmacs and my-init-texmacs.scm is booted each time you open a file.

Usually, the file my-init-texmacs.scm contains personal keyboard bindings and menus. For instance, when putting the following piece of code in this file, the keyboard shortcuts T h . and P r o p . for starting a new theorem resp. proposition:

Similarly, the following command extends the standard Insert menu with a special section for the insertion of greetings:

The customization of the keyboard and menus is described in more detail in the chapter about the TeXmacs extensions of Scheme. Notice also that, because of the lazy loading mechanism, you can not always assume that the standard key-bindings and menus are loaded before my-init-texmacs.scm. This implies that some care is needed in the case of redefinitions.

The file my-init-buffer.scm can for instance be used in order to automatically select a certain style when starting a new document:

Notice that the check (no-name?) is important: when omitted, the styles of existing documents would also be changed to article. The command (pretend-save-buffer) is used in order to avoid TeXmacs to complain about unsaved documents when leaving TeXmacs without changing the document.

Another typical use of my-init-buffer.scm is when you mainly want to use TeXmacs as a front-end to another system. For instance, the following code will force TeXmacs to automatically launch a Maxima session for every newly opened document:

Using (url->string (get-name-buffer)) as the second argument of make-session ensures that a different session will be opened for every new buffer. If you want all buffers to share a common instance of Maxima, then you should use "default" instead, for the second argument.

User provided plug-ins

The above technique of Scheme initialization files is sufficient for personal customizations of TeXmacs, but not very convenient if you want to share extensions with other users. A more portable way to extend the editor is therefore to regroup your Scheme programs into a plug-in.

The simplest way to write a plug-in name with some additional Scheme functionality is to create two directories and a file

    ~/.TeXmacs/plugins/name

    ~/.TeXmacs/plugins/name/progs

    ~/.TeXmacs/plugins/name/progs/init-name.scm

Furthermore, the file init-name.scm should a piece of configuration code of the form

Any other Scheme code present in init-name.scm will then be executed when the plug-in is booted, that is, shortly after TeXmacs is started up. By using the additional (:prioritary #t) option, you may force the plug-in to be loaded earlier during the boot procedure.

Of course, the plug-in mechanism is more interesting when the plug-in contains more than a few customization routines. In general, a plug-in may also contain additional style files or packages, scripts for launching extern binaries, additional icons and internationalization files, and so on. Furthermore, Scheme extensions are usually regrouped into Scheme modules in the directory

    ~/.TeXmacs/plugins/name/progs

The initialization file init-name.scm should then be kept as short as possible so as to save boot time: it usually only contains lazy declarations which allow TeXmacs to load the appropriate modules only when needed.

For more information about how to write plug-ins, we refer to the corresponding chapter.

Interactive invocation of Scheme commands

In order to rapidly test the effect of Scheme commands, it is convenient to execute them directly from within the editor. TeXmacs provides two mechanisms for doing this: directly type the command on the footer using the M-X shortcut, or start a Scheme session using Insert→Session→Scheme.

The first mechanism is useful when you do not want to alter the document or when the current cursor position is important for the command you wish to execute. For instance, the command (inside? 'theorem) to test whether the cursor is inside a theorem usually makes no sense when you are inside a session.

Scheme sessions are useful when the results of the Scheme commands do not fit on the footer, or when you want to keep your session inside a document for later use. Some typical commands you might want to use inside a Scheme session are as follows (try positioning your cursor inside the session and execute them):

Command-line options for executing Scheme commands

TeXmacs also provides several command-line options for the execution of Scheme commands. This is useful when you want to use TeXmacs as a batch processor. The Scheme-related options are the following:

-x cmd

Executes the scheme command cmd when booting has completed. For instance,

texmacs -x "(display \"Hi there\\n\")"

causes TeXmacs to print “Hi there!” when starting up. Notice that the -x option may be used several times.

-q

This option causes TeXmacs to quit. It is usually used after a -x option. For instance,

texmacs text.tm -x "(print)" -q

will cause TeXmacs to load the file text.tm, to print it, and quit.

-c in out

This options may be used to convert the input file in into the output file out. The suffixes of in and out determine their file formats.

Invoking Scheme scrips from TeXmacs markup

TeXmacs provides three major tags for invoking Scheme scripts from within the markup:

<action|text|script>

This tag works like a hyperlink with body text, but such that the Scheme command script is invoked when clicking on the text. For instance, when clicking here, you will launch an xterm.

<extern|fun|arg-1|...|arg-n>

This tag is used in order to implement macros whose body is written in Scheme rather than the TeXmacs macro language. The first argument fun is a scheme function with n arguments. During the typesetting phase, TeXmacs passes the arguments arg-1 until arg-n to fun, and the result will be typeset. For instance, the code

<extern|(lambda (x) ‘(concat "Hallo " ,x))|Piet>

produces the output “Hallo Piet”. Notice that the argument “Piet” remains editable.

<mutator|text|script>

This tag may be used to implement markup which “dynamically changes itself”. More precisely, the Scheme command script is repeatedly evaluated by the editor, while storing the location of text inside the TeXmacs tree. The script may then make use of this location so as to dynamically change the text.

It should be noticed that the direct invocation of Scheme scripts from within documents carries as risk: an evil person might send you a document with a script which attempts to erase your hard disk (for instance). For this reason, TeXmacs implements a way to test whether scripts can be considered secure or not. For instance, when clicking here (so as to launch an xterm), the editor will prompt you by default in order to confirm whether you wish to execute this script. The desired level of security can be specified in Edit→Preferences→Security. When writing your own Scheme extensions to TeXmacs, it is also possible to define routines as being secure.