1.Primitives for writing style files

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.

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.

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.

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.

This primitive returns a macro (the TeXmacs analogue of a -expression) with 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.

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:

• The argument namespace is distinct from the environment, <arg|var> and <value|var> will generally evaluate to different values (although you should not rely on this).

• The value of arg retains the position of the macro argument in the document tree, that makes it possible to edit the arguments of a macro-defined tag while it is active.

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.

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 -th individual argument can then be accessed using <arg|var|i>.

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 -th child of var, where is the result of evaluating first. If last has been specified too, then we stop at the -th child of var (the -th child not being included), where is the result of evaluating last. In this last case, the arity of the returned tree is therefore .

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.

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.

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.

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, )

Sets the arity to the given fixed value (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.

Returns the label of the tree obtained when evaluating expression.

Returns the arity of the tree obtained when evaluating expression.

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 accessibility 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 accessibility 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:

These commands are respectively equivalent to

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

the code <count|1|50> produces

Typeset the result of the evaluation of expr. This primitive is usually combined with a tag like quote or quasiquote for delaying the 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.

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,

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

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

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.

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

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

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

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

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

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

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.

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

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

roman

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

Roman

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

alpha

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

Alpha

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

arabic

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

fnsymbol

Footnotes symbols: <number|2|fnsymbol> .

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 “March 25, 2024”, <date||french> to “25 mars 2024” and <date|%d %B om %k:%M|dutch> to “25 March om 16:42”.

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 Document→Language menu. The built-in TeXmacs dictionaries can be found in

$TEXMACS_PATH/languages/natural/dic

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.

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.

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.

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

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.

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

Tests whether a given expression expr evaluates to a tuple.

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

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

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 .

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 .

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 deactivate 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 ⌫. 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*):

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 Document→Source→Source tags menu, or by modifying the src-style, src-special, src-compact and src-close environment variables.

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

is rendered by default as

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

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.

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.

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.

Typeset the body using some indentation.

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.

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.

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.

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:

It has been foreseen that the accessibility 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 Edit→Preferences→Security→Accept all scripts.

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.

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 Document→Informative 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 Document→Informative flags→Detailed. 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.

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

This primitive is mainly used for default uninitialized 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

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.

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

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

would typically be represented as

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

Used to represent temporarily saved values on a stack.

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

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

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

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.