Adding new data formats and converters

Using the Guile/Scheme extension language, it is possible to add new data formats and converters to TeXmacs in a modular way. Usually, the additional formats and converters are declared in your personal ~/.TeXmacs/progs/my-init-texmacs.scm or a dedicated plug-in. Some examples may be found in the directory $TEXMACS_PATH/progs/convert, like init-html.scm.

Declaring new formats

A new format is declared using the command

(define-format format

(:name format-name)

options)

Here format is a symbol which stands for the format and format-name a string which can be used in menus. In fact, a data format usually comes in several variants: a format format-file for files, a format format-document for entire documents, a format format-snippet for snippets, like selections, and format-object for the preferred internal scheme representation for doing conversions (i.e. the parsed variant of the format). Converters from format-file to format-document and vice versa are provided automatically.

The user may specify additional options for the automatic recognition of formats by their file suffix and contents. The possible suffixes for a format, with the default one listed first, may be specified using

(:suffix default-suffix other-suffix-1 ... other-suffix-n)

A (heuristic) routine for recognizing whether a given document matches the format can be specified using either one of the following:

(:recognize predicate)

(:must-recognize predicate)

In the first case, suffix recognition takes precedence over document recognition and in the second case, the heuristic recognition is entirely determined by the document recognition predicate.

Declaring new converters

New converters are declared using

(converter from to

options)

The actual converter is specified using either one of the following options:

(:function converter)

(:function-with-options converter-with-options)

(:shell prog prog-pre-args from progs-infix-args to prog-post-args)

In the first case, the converter is a routine which takes an object of the from format and returns a routine of the to format. In the second case, the converter takes an additional association list as its second argument with options for the converter. In the last case, a shell command is specified in order to convert between two file formats. The converter is activated only then, when prog is indeed found in the path. Also, auxiliary files may be created and destroyed automatically.

TeXmacs automatically computes the transitive closure of all converters using a shortest path algorithm. In other words, if you have a converter from x to y and a converter from y to z, then you will automatically have a converter from x to z. A “distance between two formats via a given converter” may be specified using

(:penalty floating-point-distance)

Further options for converters are:

(:require cond)

(:option option default-value)

The first option specifies a condition which must be satisfied for this converter to be used. This option should be specified as the first or second option and always after the :penalty option. The :option option specifies an option for the converter with its default value. This option automatically become a user preference and it will be passed to all converters with options.

© 1998–2002 Joris van der Hoeven
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".