Home | | Help | Contribute | Plug-ins | About | Contact | Search
TeXmacs plug-ins
Manual | Top | Previous | Next

There are many ways in which TeXmacs can be customized or extended: users may define their own style files, customize the user interface, or write links with extern programs. The plug-in system provides a universal mechanism to combine one or several such extensions in a single package. Plug-ins are both easy to install by other users and easy to write and maintain.

1.Installing and using a plug-in

From the user's point of view, a plug-in myplugin will usually be distributed on some web-site as a binary tarball with the name

    myplugin-version-architecture.tar.gz

If you installed TeXmacs yourself in the directory $TEXMACS_PATH, then you should unpack this tarball in the directory $TEXMACS_PATH/plugins, using

    tar -zxvf myplugin-version-architecture.tar.gz

This will create a myplugin subdirectory in $TEXMACS_PATH/plugins. As soon as you restart TeXmacs, the plug-in should be automatically recognized. Please read the documentation which comes with your plug-in in order to learn using it.

Remark 1. If you did not install TeXmacs yourself, or if you do not have write access to $TEXMACS_PATH, then you may also unpack the tarball in $TEXMACS_HOME_PATH/plugins. Here we recall that $TEXMACS_HOME_PATH defaults to $HOME/.TeXmacs. When starting TeXmacs, your plug-in should again be automatically recognized.

Remark 2. If the plug-in is distributed as a source tarball like myplugin-version-src.tar.gz, then you should first compile the source code before relaunching TeXmacs. Depending on the plug-in (read the instructions), this is usually done using

    cd myplugin; make

or

    cd myplugin; ./configure; make

Remark 3. In order to upgrade a plug-in, just remove the old version in $TEXMACS_PATH/plugins or $TEXMACS_HOME_PATH/plugins using

    rm -rf myplugin

and reinstall as explained above.

2.Writing your own plug-ins

In order to write a plug-in myplugin, you should start by creating a directory

    $TEXMACS_HOME_PATH/plugins/myplugin

where to put all your files (recall that $TEXMACS_HOME_PATH defaults to $HOME/.TeXmacs). In addition, you may create the following subdirectories (when needed):

bin

For binary files.

doc

For documentation (not yet supported).

langs

For language related files, such as dictionaries (not yet supported).

lib

For libraries.

packages

For style packages.

progs

For Scheme programs.

src

For source files.

styles

For style files.

As a general rule, files which are present in these subdirectories will be automatically recognized by TeXmacs at startup. For instance, if you provide a bin subdirectory, then

    $TEXMACS_HOME_PATH/plugins/myplugin/bin

will be automatically added to the PATH environment variable at startup. Notice that the subdirectory structure of a plug-in is very similar to the subdirectory structure of $TEXMACS_PATH.

Example 4. The easiest type of plug-in only consists of data files, such as a collection of style files and packages. In order to create such a plug-in, it suffices to create directories

    $TEXMACS_HOME_PATH/plugins/myplugin
    $TEXMACS_HOME_PATH/plugins/myplugin/styles
    $TEXMACS_HOME_PATH/plugins/myplugin/packages

and to put your style files and packages in the last two directories. After restarting TeXmacs, your style files and packages will automatically appear in the DocumentStyle and DocumentUse package menus.

For more complex plug-ins, such as plug-ins with additional Scheme or C++ code, one usually has to provide a Scheme configuration file

    $TEXMACS_HOME_PATH/plugins/myplugin/progs/init-myplugin.scm

This configuration file should contain an instruction of the following form

(plugin-configure myplugin
  configuration-options)

Here the configuration-options describe the principal actions which have to be undertaken at startup, including sanity checks for the plug-in. In the next sections, we will describe some simple examples of plug-ins and their configuration. Many other examples can be found in the directories

    $TEXMACS_PATH/examples/plugins
    $TEXMACS_PATH/plugins

Some of these are described in more detail in the chapter about writing new interfaces.

3.Example of a plug-in with Scheme code

The world plug-in

Consider the world plug-in in the directory

    $TEXMACS_PATH/examples/plugins

This plug-in shows how to extend TeXmacs with some additional Scheme code in the file

    world/progs/init-world.scm

In order to test the world plug-in, you should recursively copy the directory

    $TEXMACS_PATH/examples/plugins/world

to $TEXMACS_PATH/plugins or $TEXMACS_HOME_PATH/plugins. When relaunching TeXmacs, the plug-in should now be automatically recognized (a World menu should appear in the menu bar).

How it works

The file init-world.scm essentially contains the following code:

(plugin-configure world
  (:require #t))

(when (supports-world?)
  (display* "Using world plug-in!\n"))

The configuration option :require specifies a condition which needs to be satisfied for the plug-in to be detected by TeXmacs (later on, this will for instance allow us to check whether certain programs exist on the system). The configuration is aborted if the requirement is not fulfilled.

Assuming that the configuration succeeds, the supports-world? predicate will evaluate to #t. In our example, the body of the when statement corresponds to some further initialization code, which just sends a message to the standard output that we are using our plug-in. In general, this kind of initialization code should be very short and rather load a module which takes care of the real initialization. Indeed, keeping the init-myplugin.scm files simple will reduce the startup time of TeXmacs.

4.Example of a plug-in with C++ code

The minimal plug-in

Consider the example of the minimal plug-in in the directory

    $TEXMACS_PATH/examples/plugins

It consists of the following files:

    minimal/Makefile
    minimal/progs/init-minimal.scm
    minimal/src/minimal.cpp

In order to try the plug-in, you first have to recursively copy the directory

    $TEXMACS_PATH/examples/plugins/minimal

to $TEXMACS_PATH/progs or $TEXMACS_HOME_PATH/progs. Next, running the Makefile using

    make

will compile the program minimal.cpp and create a binary

    minimal/bin/minimal.bin

When relaunching TeXmacs, the plug-in should now be automatically recognized.

How it works

The minimal plug-in demonstrates a minimal interface between TeXmacs and an extern program; the program minimal.cpp is explained in more detail in the chapter about writing interfaces. The initialization file init-minimal.scm essentially contains the following code:

(plugin-configure minimal
  (:require (url-exists-in-path? "minimal.bin"))
  (:launch "minimal.bin")
  (:session "Minimal"))

The :require option checks whether minimal.bin indeed exists in the path (so this will fail if you forgot to run the Makefile). The :launch option specifies how to launch the extern program. The :session option indicates that it will be possible to create sessions for the minimal plug-in using InsertSessionMinimal.

5.Summary of the configuration options for plug-ins

As explained before, the Scheme configuration file myplugin/progs/init-myplugin.scm of a plug-in with name plugin should contain an instruction of the type

(plugin-configure myplugin
  configuration-options)

Here follows a list of the available configuration-options:

(:winpath package-path inner-bin-path)

Specify where to search for the plug-in under windows. The package-path is the usual place where the plug-in is installed. The inner-bin-path is the place where to look for the binary executable corresponding to the plug-in, relative to the package-path.

(:winpath package-path inner-bin-path)

Analoguous to :winpath, but under MacOS.

(:require condition)

This option specifies a sanity condition which needs to be satisfied by the plug-in. Usually, it is checked that certain binaries or libraries are present on your system. If the condition fails, then TeXmacs will continue as whether your plug-in did not exist. In that case, further configuration is aborted. The :require option usually occurs first in the list of configuration options.

(:versions version-cmd)

This option specifies a Scheme expression version-cmd which evaluates to a list of available versions of the plug-in.

(:setup cmd)

This command is only executed when the version of the plug-in changed from one execution of TeXmacs to another one. This occurs mainly when installing new versions of TeXmacs or helper applications.

(:launch shell-cmd)

This option specifies that the plug-in is able to evaluate expressions over a pipe, using a helper application which is launched using the shell-command shell-cmd.

(:link lib-name export-struct options)

This option is similar to :launch, except that the extern application is now linked dynamically. For more information, see the section about dynamic linking.

(:session menu-name)

This option indicates that the plug-in supports an evaluator for interactive shell sessions. An item menu-item will be inserted to the InsertSession menu in order to launch such sessions.

(:serializer ,fun-name)

If the plug-in can be used as an evaluator, then this option specifies the Scheme function fun-name which is used in order to transform TeXmacs trees to strings.

(:commander ,fun-name)

This command is similar to the :serializer option except that it is used to transform special commands to strings.

(:tab-completion #t)

This command indicates that the plug-in supports tab-completion.

(:test-input-done #t)

This command indicates that the plug-in provides a routine for testing whether the input is complete.

It should be noticed that the configuration of the plug-in myplugin automatically creates a few predicates:

supports-myplugin?

Test whether the plug-in is fully operational (all requirements are met).

in-myplugin?

Test whether myplugin is the current programming language.

myplugin-scripts?

Test whether myplugin is the current scripting language.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".