mirror of https://github.com/texmacs/doc.git
136 lines
4.8 KiB
Tcl
136 lines
4.8 KiB
Tcl
<TeXmacs|1.99.11>
|
|
|
|
<style|<tuple|tmdoc|english|old-spacing>>
|
|
|
|
<\body>
|
|
<tmdoc-title|Adding new data formats and converters>
|
|
|
|
Using the <name|Guile>/<name|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
|
|
<verbatim|~/.TeXmacs/progs/my-init-texmacs.scm> or a dedicated plug-in.
|
|
Some examples may be found in the directory
|
|
<verbatim|$TEXMACS_PATH/progs/convert>, like
|
|
<hlink|<verbatim|init-html.scm>|$TEXMACS_PATH/progs/convert/html/init-html.scm>.
|
|
|
|
<paragraph*|Declaring new formats>
|
|
|
|
A new format is declared using the command
|
|
|
|
<\scm-code>
|
|
(define-format <em|format>
|
|
|
|
\ \ (:name <em|format-name>)
|
|
|
|
\ \ <em|options>)
|
|
</scm-code>
|
|
|
|
Here <verbatim|<em|format>> is a symbol which stands for the format and
|
|
<verbatim|<em|format-name>> a string which can be used in menus. In fact, a
|
|
data format usually comes in several variants: a format
|
|
<verbatim|<em|format>-file> for files, a format
|
|
<verbatim|<em|format>-document> for entire documents, a format
|
|
<verbatim|<em|format>-snippet> for snippets, like selections, and
|
|
<verbatim|<em|format>-object> for the preferred internal scheme
|
|
representation for doing conversions (<abbr|i.e.> the parsed variant of the
|
|
format). Converters from <verbatim|<em|format>-file> to
|
|
<verbatim|<em|format>-document> and <em|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
|
|
|
|
<\scm-code>
|
|
(:suffix <em|default-suffix> <em|other-suffix-1> ... <em|other-suffix-n>)
|
|
</scm-code>
|
|
|
|
A (heuristic) routine for recognizing whether a given document matches the
|
|
format can be specified using either one of the following:
|
|
|
|
<\scm-code>
|
|
(:recognize <em|predicate>)
|
|
|
|
(:must-recognize <em|predicate>)
|
|
</scm-code>
|
|
|
|
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.
|
|
|
|
A format can be removed from menus using the following:
|
|
|
|
<\scm-code>
|
|
(:hidden)
|
|
</scm-code>
|
|
|
|
<paragraph*|Declaring new converters>
|
|
|
|
New converters are declared using
|
|
|
|
<\scm-code>
|
|
(converter <em|from> <em|to>
|
|
|
|
\ \ <em|options>)
|
|
</scm-code>
|
|
|
|
The actual converter is specified using either one of the following
|
|
options:
|
|
|
|
<\scm-code>
|
|
(:function <em|converter>)
|
|
|
|
(:function-with-options <em|converter-with-options>)
|
|
|
|
(:shell <em|prog> <em|prog-pre-args> from <em|progs-infix-args> to
|
|
<em|prog-post-args>)
|
|
</scm-code>
|
|
|
|
In the first case, the <verbatim|<em|converter>> is a routine which takes
|
|
an object of the <verbatim|<em|from>> format and returns a routine of the
|
|
<verbatim|<em|to>> format. In the second case, the
|
|
<verbatim|<em|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 <verbatim|<em|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 <math|x> to <math|y> and a converter from <math|y> to <math|z>, then
|
|
you will automatically have a converter from <math|x> to <math|z>. A
|
|
\Pdistance between two formats via a given converter\Q may be specified
|
|
using
|
|
|
|
<\scm-code>
|
|
(:penalty <em|floating-point-distance>)
|
|
</scm-code>
|
|
|
|
Further options for converters are:
|
|
|
|
<\scm-code>
|
|
(:require <em|cond>)
|
|
|
|
(:option <em|option> <em|default-value>)
|
|
</scm-code>
|
|
|
|
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 <verbatim|:penalty> option. The
|
|
<verbatim|: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.
|
|
|
|
<tmdoc-copyright|1998--2002|Joris van der Hoeven>
|
|
|
|
<tmdoc-license|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".>
|
|
</body>
|
|
|
|
<initial|<\collection>
|
|
</collection>> |