Home | | Help | Contribute | Plug-ins | About | Contact | Search
The style-sheet language
Manual | Top | Previous | Next

1.Environment primitives

The current environment both defines all style parameters which affect the typesetting process and all additional macros provided by the user and the current style. The primitives in this section are used to access and modify environment variables.

(variable mutation)

This primitive sets the environment variable named var (string value) to the value of the val expression. This primitive is used to make non-scoped changes to the environment, like defining markup or increasing counters.

This primitive affects the evaluation process through value, provides, and macro definitions and the typesetting process through special typesetter variables.

Example 1. Enabling page breaking by style.

The page-medium is used to enable page breaking. Since only the initial environment value for this variable is effective, this assignation must occur in a style file, not within a document.


Example 2. Setting the chapter counter.

The following snippet will cause the immediately following chapter to be number 3. This is useful to get the the numbering right in book style when working with projects and include.


The operand must be a literal string and is interpreted as a file name. The content of this file is typeset in place of the include tag, which must be placed in block context.

(variable scope)

This primitive temporarily sets the environment variables var-1 until var-n (in this order) to the evaluated values of val-1 until val-n and typesets body in this modified environment. All non-scoped change done with assign to var-1 until var-n within body are reverted at the end of the with.

This primitive is used extensively in style files to modify the typesetter environment. For example to locally set the text font, the paragraph style, or the mode for mathematics.

(variable value)

This primitive evaluates the current value of the environment variable var (literal string). This is useful to display counters and generally to implement environment-sensitive behavior.

This primitive is used extensively in style files to modify the typesetter environment. For example to locally set the text font, the paragraph style, or the mode for mathematics.

(definition predicate)

This predicate evaluates to true if the environment variable var (string value) is defined, and to false otherwise.

That is useful for modular markup, like the session environments, to fall back to a default appearance when a required package is not used in the document.

2.Macro primitives

Macros can be used to define new tags and to build procedural abstractions in style files.

Older versions of TeXmacs used to make a distinction between macros (all children accessible) and functions (no accessible child). In modern TeXmacs there are only macros: the accessibility of children is determined heuristically and can be controlled with drd-props.

(macro of fixed arity)

This primitive returns a macro (the TeXmacs analogue of a λ-expression) with n arguments, named after the literal strings var-1 until var-n.

New tags are defined by storing macros in the environment. Most of the time, macros are stored without scope with assign, but it is sometimes useful to redefine a tag locally within the scope of a with. For example, itemized and enumerated environment redefine item locally.

Example 3. Definition of the abbr tag


Storing a macro in the environment defines a tag whose arity is fixed to the number of arguments taken by the macro.

(retrieve macro arguments)

This primitive is used to retrieve the arguments of a macro within its body. For instance, <arg|var> expands the content of the macro argument with name var (literal string). Of course, this argument must be defined by a macro containing the arg tag.

This tag is similar to value, but differs in important ways:

When more than one argument is specified, <arg|var|index-1||index-n> expands to a subtree of the argument var. The value of the named argument must be a compound tree (not a string). The operands var until index-n must all evaluate to positive integers and give the path to the subtree of the macro argument.

(macro with a variable arity)

This primitive returns a macro (the TeXmacs analogue of a λ-expression) capable of taking any number of arguments. The arguments are stored in the macro variable with name var (a literal string) during the evaluation of the body. The i-th individual argument can then be accessed using <arg|var|i>.



(map a tag on subtrees of an argument)

This primitive evaluates to a tree whose root is labeled by root and whose children are the result of applying the macro foo to the children of the macro argument with name var.

By default, the macro foo is applied to all children. If first has been specified, then we rather start at the i-th child of var, where i is the result of evaluating first. If last has been specified too, then we stop at the j-th child of var (the j-th child not being included), where j is the result of evaluating last. In this last case, the arity of the returned tree is therefore j - i.

Stated otherwise, map-args applies foo to all subtrees of the macro argument var (or a range of subtrees if first and last are specified) and collects the result in a tree with label root. In addition, the second argument to foo gives its position of the first argument in the expansion of var.

The map-args is analogue to the Scheme function map. Since TeXmacs use labeled trees, the label of the mapping list must also be specified.

Example 4. Comma-separated lists.

The comma-separated tag has any arity (though it does not make much sense with arity zero) and typesets its operands interspersed with commas.

<assign|comma-extra|<macro|x|, x>>








(macro with a variable arity)

This primitive evaluates to the tree with the same label as the expansion of the argument var and whose subtrees are the result of the evaluation of the subtrees of the expansion of var.

(expand an unnamed macro)

This primitive is useful to expand macros which are the result of a computation: it applies the macro which is the result of the evaluation of foo to the arguments arg-1 until arg-n. The compound primitive is useful in call-back and lambda programming idioms, where a higher-level macro is given a macro as an operand, which it may later apply under certain conditions or with operands which are not known to the client code.

Actually, in the current implementation, foo may either evaluate to a macro or to a literal string which gives the name of a macro. However, we discourage users to rely on the second case.

Example 5. Lambda programming with macros.

In the code below, <filter|pred|t> expects a macro pred and a tuple t on input and returns a tuple containing the elements of t for which pred evaluates to true.




















As an application, we may define a macro <evens|t>, which expects t to be a tuple containing integers, and which returns the tuple of integers in t which are divisible by 2.


(set D.R.D. properties of a tag)

The arity and children accessibility of tags defined by macros are determined heuristically by default. The drd-props primitive overrides this default for the environment variable (usually a macro) with name var. The currently supported property-value pairs are:

(arity, n)

Sets the arity to the given fixed value n (literal integer).

(accessible, all)

Make it impossible to deactivate the tag with normal editor actions. Inaccessible children become effectively uneditable.

(accessible, none)

Make it impossible to position the caret within the tag when it is active, so children can only be edited when the tag is inactive.

(label of an expression)

Returns the label of the tree obtained when evaluating expression.

(arity of an expression)

Returns the arity of the tree obtained when evaluating expression.

3.Flow control primitives


(conditional markup)

This primitive can be used to typeset if-body only if the condition is satisfied. If the optional else-body is specified, then it is typeset if and only if the condition fails.

Remark 6. It should be noticed that the use of conditional markup can be a bit tricky due to the fact that the accessability of arguments cannot necessarily be checked beforehand. For instance, in the macro definition


the macro argument x is accessible if and only if <visibility-flag> evaluates to true. This condition cannot necessarily be checked a priori. For certain editing operations, like searches or spell checking, the incorrect determination of the accessability may lead to the positioning of the cursor at unaccessible places, or to the ignorance of certain markup. In the future, we plan to improve this aspect of the editor, but it is better to avoid conditional markup whenever another solution can be found.

Remark 7. The conditional constructs are only fully implemented for inline markup. In the case when you need conditional markup for block structures you currently have to write macros for the if-case and the else-case and use the compound tag. For instance:





(case distinction)

These commands are respectively equivalent to



(repeated evaluation)

This construct maybe used in order to repeatly execute a given body while a given condition is satisfied. For instance, when declaring



<while|<less|i|to>|i, <assign|i|<plus|i|1>>>





the code <count|1|50> produces

1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50

4.Evaluation control primitives

This section describes several primitives for controlling the way expressions in the style-sheet language are evaluated. The primitives are analoguous to the Scheme primitives eval, quote, quasiquote, etc., although the TeXmacs conventions are slightly different than those used by conventional functional languages like Scheme.

(force evaluation)

Typeset the result of the evaluation of expr. This primitive is usually combined with a tag like quote or quasiquote for delaying the evaluation.

(delayed evaluation)

Evaluation of the expression <quote|expr> yields expr itself. This kind of delayed evaluation may be useful in combination with the eval primitive which forces evaluation.

(delay evaluation and substitution)

This tag is a variant of the quote tag, which returns the expression expr in which all subexpressions of the form <unquote|subexpr> have been replaced by the evaluations of subexpr. For instance,

<assign|hello|<quasiquote|<macro|name|<unquote|<localize|Hello>> name.>>>

may be used to define a macro hello whose value is localized for the current language. In a French document, the declaration would typically be equivalent to

<assign|hello|<macro|name|Bonjour name.>>

Notice however that it is usually better not to use the quasiquote primitive for such applications. When defining

<assign|hello|<macro|name|<localize|Hello> name.>>

the typesetting of <hello|Name> would naturally adapt itself to the current language, while the above version would always use the language at the moment of the definition of the macro. Nevertheless, the first form does have the advantage that the localization of the word “Hello” only has to be computed once, when the macro is defined. Therefore, the quasiquote primitive may sometimes be used in order to improve performance.

(mark substitutable subexpressions)

This tag is used in combination with quasiquote and quasi in order to mark the subexpressions which need to be evaluated.

(unquote splicing)

This tag is similar to unquote, except that the argument subexprs now evaluates to a list of subexpressions, which are inserted into the arguments of the parent node. For instance, consider the macro






Then <fun|a|b|c> is typeset as


This tag is a shortcut for <eval|<quasiquote|expr>>. This primitive is often used in the TeXmacs style files in order to write macros which define sets of other macros. For instance, the macro

<assign|new-theorem|<macro|name|text|<quasi|<assign|<unquote|name>|<macro|body|<surround|<no-indent><strong|<unquote|text>. >|<right-flush>|body>>>>>>

may be used in order to define new theorem-like environments.

(retrieve a value but don't evaluate)

When retrieving an environment variable var, one is usually interested in its typesetted value, as given by <value|var>. In some cases, it may be useful to access the real, non-typesetted value. This can be done with <quote-value|var>.

(retrieve an argument but don't evaluate)

When retrieving (a subexpression of) a macro argument var, one is usually interested in its typesetted value, as given by <arg|var|index-1||index-n>. In some cases, it may be useful to access the real, non-typesetted value. This can be done with <quote-arg|var|index-1||index-n>.

5.Functional operators

Functional operators are used for computational purposes during the typesetting phase, such as increasing counters, localizing strings like “theorem” and so on. A fundamental set of basic functional operators are built-in primitives. New functional operators can easily be added using the extern primitive. Functional operators operate on five main types of arguments: strings, numbers, lengths, booleans and tuples. Some operators are overloaded, so that they can be used for several types.

5.1.Operations on text

(length of a string)

If expr is a string, the length of the string is returned. For instance, <length|Hello> evaluates to 5.

(extract a substring)

Return the substring of expr starting at position start and ending at position end (not included). For instance, <range|hottentottententententoonstelling|9|15> evaluates to tenten.

(concatenate strings)

This primitive may be used to concatenate several strings expr-1 until expr-n. For instance, <merge|Hello|World> produces HelloWorld.

(alternative rendering of numbers)

Renders a number in a specified way. Supported values for render-as are


Lower case Roman: <number|18|roman> xviii.


Upper case Roman: <number|18|Roman> XVIII.


Lower case letters: <number|18|alpha> r.


Upper case letters: <number|18|Alpha> R.


Arabic numbers: <number|18|arabic> 18.


Footnotes symbols: <number|2|fnsymbol> .



(obtain the current date)

Returns the current date in a specified format (which defaults to a standard language-specific format when empty) and a specified language (which defaults to English). The format is similar to the one used by the Unix date command. For instance, <date> evaluates to “July 8, 2016”, <date||french> to “8 juillet 2016” and <date|%d %B om %k:%M|dutch> to “08 July om 14:22”.

(translation of strings)

Returns the translation of a string what of the language from into the language into, using the built-in TeXmacs dictionaries. The languages should be specified in lowercase letters. For instance, <translate|File|english|french> yields “Fichier”.

The list of currently available languages can be checked in the DocumentLanguage menu. The built-in TeXmacs dictionaries can be found in


When attempting to use a non-existing dictionary, the program may quit. For most purposes, it is more convenient to use the localize macro, which converts a string from English into the current language.

5.2.Arithmetic operations


(addition and subtraction)

Add or subtract numbers or lengths. For instance, <plus|1|2.3|5> yields 8.3 and <plus|1cm|5mm> produces . In the case of subtractions, the last argument is subtracted from the sum of the preceding arguments. For instance, <minus|1> produces -1 and <minus|1|2|3|4> yields 2.


Multiply two numbers expr-1 until expr-n. One of the arguments is also allowed to be a length, in which case a length is returned. For instance, <times|3|3> evaluates to 9 and <times|3|2cm> to .


Divide the product of all but the last argument by the last argument. For instance, <over|1|2|3|4|5|6|7> evaluates to 102.857, <over|3spc|7> to , and <over|1cm|1pt> to 28.4528.


(division with remainder)

Compute the result of the division of an integer expr-1 by an integer expr-2, or its remainder. For instance, <div|18|7>=2 and <mod|18|7>=4.






(comparing numbers or lengths)

Return the result of the comparison between two numbers or lengths. For instance, <less|123|45> yields false and <less|123mm|45cm> yields true.

5.3.Boolean operations



Returns the result of the boolean or/and on the expressions expr-1 until expr-n. For instance, <or|false|<equal|1|1>|false> yields true.


Returns the exclusive or of two expressions expr-1 and expr-2, i.e. <xor|true|true> yields false.


Returns the negation of expr.

5.4.Operations on tuples

(construct a tuple)

Forms a tuple from the expressions expr-1 until expr-n.

(tuple predicate)

Tests whether a given expression expr evaluates to a tuple.

(length of a tuple)

If expr is a tuple, then we return its arity. For instance, <length|<tuple|hop|hola>> evaluates to 2.

(access an entry in a tuple)

Returns the element with index which in tuple. For instance, <look-up|<tuple|a|b|c>|1> yields b.

(extract a subtuple)

Return the subtuple of expr starting at position start and ending at position end (not included). For instance, <range|<tuple|a|hola|hop|b|c>|2|4> evaluates to .

(concatenate tuples)

This primitive may be used to concatenate several tuples expr-1 until expr-n. For instance, <merge|<tuple|1|2>|<tuple|3|4|5>> produces .

6.Transient markup

The tags described in this section are used to control the rendering of style files and style file elements. It both contains markup for activation and disactivation of content and for the rendering of tags.




(activation/disactivation of content)

These tags can be used to temporarily or permanently change the activity of the content . In usual documents, tags are by default active. In style files, they are by default inactive. For instance, an activated fraction is rendered as

; when deactivated, it is rendered as < frac | 1 | 2 > .

The active and inactive tags only activate or desactivate the root tag of the content. Typically, a tag which contains hidden information (like hlink) can be deactivated by positioning the cursor just behind it and pressing backspace. This action just deactivates the hyperlink, but not the potentially complicated body of the hyperlink. Therefore, the hyperlink is transformed into an inactive tag of the form <inactive|<hlink|body|ref>>.

The active* and inactive* variants are used to activate or deactivate the whole content (except when other (dis-)activation tags are found inside the content). The inactive* is used frequently inside the present documentation in order to show the inactive representation of TeXmacs content. Nevertheless, it is sometimes desirable to reactivate certain subtrees inside deactivated content. For instance, the following piece of deactivated code (using disactive*) contains the reactivated subexpression (using active*):

<assign|love|<macro|from| from from.>>

(rendering of inline tags)

This tag is used for the default inline rendering of an inactive tag with a given name and arguments arg-1 until arg-n. For instance, <inline-tag|foo|x|y> produces <foo|x|y>. The style of the rendering may be customized in the DocumentSourceSource tags menu, or by modifying the src-style, src-special, src-compact and src-close environment variables.



(rendering of multi-line tags)

These tags are similar to inline-tag, when some of the arguments of the tag run over several lines. Typical HTML-like tags would correspond to <open-tag|name> and <close-tag|name>. Since TeXmacs macros may take more than one argument, a middle-tag is provided for separating distinct multi-paragraph arguments. Moreover, the opening, middle and closing tags may take additional inline arguments for rendering in a compact fashion. For instance, the code

<document|<open-tag|theorem>|<indent|The weather should be nice today.>|<close-tag|theorem>>

is rendered by default as


The weather should be nice today.


The rendering may be customized in a similar way as in the case of inline-tag.


(alter presentation in style files only)

This tag may be used in order to temporarily modify the rendering of inactive tags, by setting each environment variable var-i to val-i in the local typesetting context of body. When importing a style file, each style-with/style-with* tag is replaced by its body. In the case of style-with, the modified rendering is only applied to the root tag of the body. In the case of style-with*, the rendering is modified for the entire body.


(content for use in style files only)

This tag may be used in order to render an inactive tags as whether we applied the macro foo on it. When importing a style file, each style-only/style-only* tag is replaced by its content. In the case of style-only, the modified rendering is only applied to the root tag of the content. In the case of style-only*, the rendering is modified for the entire content.




(auxiliary tags for entering special content)

These tags are used only temporarily when entering special content.

When pressing ⌃Q, a symbol tag is created. After entering the name of the symbol, or the ASCII-code of the symbol and pressing return, the symbol tag is replaced by the corresponding symbol (usually a string enclosed in <>).

When pressing \, a hybrid tag is created. After entering a string and pressing return, it is determined whether the string corresponds to a LaTeX command, a macro argument, a macro or an environment variable (in this order). If so, then the hybrid tag is replaced by the appropriate content. When pressing \ while a selection is active, then the selection automatically becomes the argument of the hybrid command (or the hybrid command itself, when recognized).

The latex tag behaves similarly as the hybrid tag except that it only recognizes LaTeX commands.

The rendering macros for source trees are built-in into TeXmacs. They should not really be considered as primitives, but they are not part of any style file either.

(indent some content)

Typeset the body using some indentation.

(indent some content)

Flush to the right. This macro is useful to make the end of a block environment run until the right margin. This allows for more natural cursor positioning and a better layout of the informative boxes.







(syntactic highlighting on purpose)

These macros are used for the syntactic highlighting of source trees. They determine how to render subtrees which correspond to macro names, variable names, argument names, verbatim content, integers, lengths and error messages.




(style and package administration)

These macros are used for the identification of style files and packages and their corresponding D.T.D.s. The src-title is a container for src-style-file, src-package, src-package-dtd as well as src-license and src-copyright macros.

The src-style-file tag specifies the name and version of a style file and sets the environment variable with name-style to version. The src-package-dtd specifies the name and version of a package, as well as the corresponding dtd and its version dtd-version. It sets the environment variable name-package to version and dtd-dtd to dtd-version. The src-package tag is a shorthand for src-package-dtd when the name of the D.T.D. coincides with the name of the package.

7.Miscellaneous style-sheet primitives

(apply extern typesetting macro)

This primitive allows the user to implement macros in Scheme. The primitive applies the Scheme function or macro scheme-foo to the arguments arg-1 until arg-n. For instance, the code <extern|(lambda (name) ‘(concat "hi " ,name))|dude> yields “hi dude”.

The arguments arg-1 until arg-n are evaluated and then passed as trees to scheme-foo. When defining a macro which relies on extern scheme code, it is therefore recommended to pass the macro arguments using the quote-arg primitive:



(lambda (x y) ‘(frac ,x (concat "1+" ,y)))







It has been foreseen that the accessability of the macro arguments x and y is preserved for this kind of definitions. However, since TeXmacs does not heuristically analyze your Scheme code, you will have to manually set the D.R.D. properties using drd-props.

Notice also that the Scheme function scheme-foo should only rely on secure scheme functions (and not on functions like system which may erase your hard disk). User implemented Scheme functions in plug-ins may be defined to be secure using the :secure option. Alternatively, the user may define all Scheme routines to be secure in EditPreferencesSecurityAccept all scripts.

(write auxiliary information)

Adds content to the auxiliary section aux of the document. This tag is used for instance by <nocite|citekey> to add entries to the automatically generated bibliography at the end of the document, without inserting a citation in the text.


(display an informative flag)

This tag is used to in order to inform the user about information which is present in the document, but not visible when printed out. TeXmacs displays such informative flags for labels, formatting directives such as page breaks, and so on. In DocumentInformative flags, the user may specify how the informative flags should be rendered.

The two-argument variant displays an informative flag with a given content and color. The content is only rendered when selecting DocumentInformative flagsDetailed. For instance, <flag|warning|red> is rendered as . The optional var argument may be used in order to specify that the flag should only be visible if the macro argument var corresponds to an accessible part of the document. For instance, TeXmacs automatically generates labels for section titles (so as to include them in the table of contents), but it is undesirable to display informative flags for such labels.

8.Internal primitives

The primitives in this section are merely for internal use by TeXmacs only. They are documented for the sake of completeness, but you should only use them if you really know what you are doing.

(unknown content or unintialized data)

This primitive is mainly used for default uninialized value of environment variables; the main advantage of this tag is to be distinct from the empty string.

(unknown content or unintialized data)

This primitive is mainly used for default uninialized value of environment variables; the main advantage of this tag is to be distinct from the empty string.

This value is less likely to be encountered than uninit

(error messages)

This primitive should never appear in documents. It is provided as aid in tracking down invalid constructs. It is produced at evaluation time by any kind of primitive which is given improper operands.


(collections of bindings)

The collection tag is used to represent hashtables with bindings binding-1 until binding-n. Each binding is of the form <associate|key|value>, with a key and an associated value.

(XML-like attributes)

This tag is included for future compatibility with XML. It is used for encoding XML-style attributes by TeXmacs trees. For instance, the fragment

<blah color="blue" emotion="verbose">
  Some XML stuff

would typically be represented as

<blah|<attr|color|blue|emotion|verbose>|Some XML stuff>


(associate a meaning to some content)

Associate a special meaning to some content. Currently, no real use has been made of these tags.

(save values on stack)

Used to represent temporarily saved values on a stack.

(marker for decorations)

This primitive is only intended for internal use by the datoms, dlines and dpages primitives.

(internal primitive for rendering inactive markup)

This internal primitive is used for rewriting an inactive tree into a new tree whose rendering corresponds to the rendering of the inactive tree. It may be successfully invoked from within a macro.

e.g. <assign|show-inactive|<macro|x|<rewrite-inactive|x|>>>

which might be invoked to show itself or another assigned variable using quasiquote in this manner: <quasiquote|<show-inactive|<unquote|show-inactive>>>


(new double page)

Yet to be implemented primitives for starting a new double page.

(identity macro)

The identity macro is built-in into TeXmacs. It should not really be considered as a primitive, but it is not part of any style file either.

In addition to these primitives for internal use only, there are also quite a few obsolete primitives, which are no longer being used by TeXmacs, but whose names should be avoided when creating your own macros. The full list of obsolete primitives is: format, line-sep, with-limits, split, old-matrix, old-table, old-mosaic, old-mosaic-item, set, reset, expand, expand*, hide-expand, apply, begin, end, func, env, authorize.

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".