1.Built-in TeXmacs primitives

This primitive is used for sequences of logical paragraphs. A simple, plain text document is made of a sequence of paragraphs. For instance,

is internally represented as a document with two subtrees:

From the visual point of view, different paragraphs are often separated by some vertical whitespace. Alternatively, new paragraphs are indicated through the use of an additional indentation. The root of a TeXmacs document is usually a document node.

The document tag is also used for marking multi-paragraph content inside other tags, such lists or theorem-like environments. Environments which require the use of a document tag for at least one argument are called “block environments”.

This not yet implemented primitive is a variant of document. While a document is made up of logical paragraphs, a paragraph is made up of “paragraph units”. From a visual point of view, different paragraphs are singled out using some additional space or indentation. New paragraph units rather correspond to simple new lines. Typically, displayed equations are also paragraph units in a larger paragraph.

This primitive is used for sequences of line items, also called “inline content”. For instance,

is internally represented as:

The concat operator is essential to put compound structures in trees taking multiple parameters. For example, let us place the previous fragment in a multi-paragraph context:

In this example, we need the concat tag in order to indicate that “Some emphasized text.” corresponds to a single paragraph:

Notice that block tags like document may contain inline tags such as concat as its children, but not vice versa. In order to typeset line content before or after block content, one has to use the surround tag below.

Although it is not possible in TeXmacs to use block content inside horizontal concatenations, it is sometimes useful to add some additional inline content before or after a block environment. The surround primitive serves this purpose, by adding a left and right surrounding to some block content body. For instance,

produces

In general, the surround is mainly used in style files, but it occasionally turns out to be useful in regular documents as well.

This primitive inserts an elastic vertical space after the current paragraph. All operands must be length values. The len argument specifies the default length and the min and max arguments the bounds to vertical stretching for page breaking and filling. If min and max are not specified, then they are determined implicitly from the length unit of len.

Notice that operands are not evaluated, so they must be literal strings.

This primitive is similar to vspace, except that the vertical space is inserted before the current paragraph. The actual vertical space between two consecutive paragraphs is the maximum, not the sum, of the vertical spaces specified by the the vspace and vspace* tags in the surrounding paragraphs.

This primitive inserts an empty box whose width is len, and whose bottom and top sides are at distances bot and top from the baseline.

If bot and top are not specified, then an empty box is inserted whose bottom is on the baseline and whose height is the same as the lowercase letter x in the current font.

Notice that operands are not evaluated, so they must be literal strings.

This primitive inserts a stretchable horizontal space of nominal width len, which must be a length value. The min and max arguments specify bounds to horizontal stretching for line breaking and filling. If min and max are not specified, then they are determined implicitly from the length unit of len.

Notice that operands are not evaluated, so they must be literal strings.

Springs are horizontal spaces which extend so the containing paragraph takes all the available horizontal space. When a paragraph is line wrapped, split in several visual lines, only springs in the last line are extended.

A spring has a minimal width and a weight. If the weight is 0, the spring is weak, otherwise it is strong. If a line contains mixed weak and strong springs, only the strong springs extend.

The fraction of the available horizontal space taken up by each strong spring is proportional to its weight. If there are only weak springs, they share the available space evenly.

<htab|min> inserts a strong spring of minimal width min and of weight unity. The min operand must be a length value.

<htab|min|weight> specifies the weight, which can be a positive decimal number or one of the two special values documented below.

<htab|min|first> inserts a tail weak spring, only the first one in a paragraph is significant.

<htab|min|last> inserts a head weak spring, only the last one in a paragraph is significant.

Operands are not evaluated and must be literal strings.

Weak springs are useful in style-sheets. For example, tail weak springs are used to make the list environment extend to across the full paragraph, so vertical motion commands in nested lists behave as expected. In regular documents, springs are often used to place some text on the right side of the page and some other text on the left side.

This is a deprecated tag in order to split a logical paragraph into several logical paragraphs without creating explicit subtrees for all paragraphs.

We recall that logical paragraphs are important structures for the typesetting process. Many primitives and environment variables (vertical spacing, paragraph style, indentation, page breaking, etc.) operate on whole paragraphs or at the boundaries of the enclosing paragraph.

This is a tag which will become deprecated as soon as the paragraph primitive will be correctly implemented. Its usage is similar to the new-line tag with the difference that we start a new logical paragraph unit instead of a new logical paragraph.

Currently, the next-line tag can also be used in order to force a line break with the additional property that the line before the break is not justified or filled.

Print an invisible space with zero hyphenation penalty. The line breaking algorithm searches for the set of hyphenation points minimizing the total penalty, so line breaking is much more likely to occur at a line-break than anywhere else in its vicinity.

Unlike next-line, this is a hint which may or may not be obeyed by the typesetter, and it does not prevent the previous line from being filled.

Set an hyphenation point with an infinite penalty. That is useful when the hyphenation patterns for a language fall short of preventing some forbidden patterns like “arse-nal” or “con-genital”. An alternative way to prevent breaks is to use the rigid tag.

Disable or enable indentation for the current paragraph. For instance, the code

typically produces

Disable or enable indentation for the next paragraph. For instance,

typically produces

Notice that no-indent and yes-indent override no-indent* and yes-indent* directives in the previous paragraph.

Currently, the no-indent* and yes-indent* tags are mainly used in order to control the indentation after section titles or environments like equation which usually correspond to paragraph units. In the future, when sectional tags will take the section bodies as arguments, and when the paragraph tag will be correctly implemented, the no-indent* and yes-indent* will become deprecated.

Prevent the occurrence of an automatic page break after the current line. Set an infinite page breaking penalty for the current line, similarly to no-break.

Forbidden page breaking points are overridden by “new page” and “page break” primitives.

Similar to no-page-break, but set the page breaking penalty of the previous line.

Cause the next line to appear on a new page, without filling the current page. The page breaker will not try to position the current line at the bottom of the page.

Similar to new-page, but start the new page before the current line. This directive is appropriate to use in chapter headings.

Force a page break after the current line. A forced page break is different from a new page, the page breaker will try to position the current line at the bottom of the page.

Use only to fine-tune the automatic page breaking. Ideally, this should be a hint similar to line-break, but this is implemented as a directive, use only with extreme caution.

Similar to page-break, but force a page break before the current line.

This primitive moves the box with the specified content by delta-x to the right and delta-y upwards. It may be used for fine-grained positioning. During the evaluation of delta-x and delta-y, the box lengths w, h, l, r, b and t of content are defined.

This primitive is similar to move, except that the bounding box of the shifted content is the same as the bounding box of the original content.

Resize the box for the content according to new left, bottom, right and top limits left-lim, bot-lim, right-lim and top-lim. The limits may be specified in terms of the box lengths w, h, l, r, b and t of content. For instance, the code

widens the box for “Hopsa” by 5mm on each side:

This primitive is similar to resize, except that the content is clipped so as to fit in the specified new bounding box.

The box with the content is displayed as usual if the condition is satisfied and displayed as whitespace otherwise. This primitive is used in particular for the definition of the phantom macro. For instance, the non-text “” is produced using <if*|false|phantom>.

This primitive can be used to decorate some content with a given pattern. For instance, when defining the macro

the code <wipe-out|obsolete> produces obsolete. The repeat primitive may also be used to fill the current line with a given content, like the dots in tables of contents.

These primitives are used to decorate a posteriori the lines of a paragraph, the lines of a page, or the pages of a document. Currently, only decorations of atoms on lines of a paragraph have been implemented.

The first argument foo is a macro which will be applied to all boxes in the line and the second argument content is the part of the paragraph to which the decoration will be applied. For instance, the construction

may be used in order to visualize the boxes in a given paragraph:

When used in combination with the repeat primitive, one may for instance produce the dotted lines in tables of contents using the macro

Notice that the datoms primitive is quite fragile, because the foo macro has no access to the environment in which content is typeset.

These primitives are used for producing large delimiters, like in the formula

Matching left and right delimiters are automatically sized so as contain the enclosed expression. Between matching left and right delimiters, the formula may contain an arbitrary number of middle delimiters, which are sized in a similar way. Contrary to TeX, the depth of a large delimiter is not necessarily equal to its height, so as to correctly render formulas like

The user may override the automatically determined size by specifying additional length parameters size or bottom and top. For instance,

is rendered as

The size may also be a number , in which case the -th available size for the delimiter is taken. For instance,

is rendered as

This primitive is used in order to produce big operators as in

The size of the operator depends on whether the formula is rendered in “display style” or not. Formulas in separate equations, like (?), are said to be rendered in display style, contrary to formulas which occur in the main text, like . The user may use Format→Display style to override the current settings.

Notice that the formula (?) is internally represented as

The invisible big operator <big|.> is used to indicate the end of the scope of <big|sum>.

The frac primitive is used in order to render fractions like . In display style, the numerator num and denominator den are rendered in the normal size, but display style is turned of when typesetting num and den. When the display style is turned of, then the arguments are rendered in script size. For instance, the content

is rendered in display style as

The sqrt primitive is used in order to render square roots like or n-th roots like . The root symbol is automatically sized so as to encapsulate the content:

These primitives are used in order to attach a script to the preceding box in a horizontal concatenation (in the case of right scripts) or the next one (in the case of left scripts). When there is no such box, then the script is attached to an empty box. Moreover, when both a subscript and a superscript are specified on the same side, then they are merged together. For instance, the expression

is rendered as

When a right script is attached to an operator (or symbol) which accepts limits, then it is rendered below or above instead of beside the operator:

Scripts are rendered in a smaller font in non-display style. Nevertheless, in order to keep formulas readable, the size is not reduced below script-script-size.

Left and right primes are similar to left and right superscripts, except that they behave in a different way when being edited. For instance, when your cursor is behind the prime symbol in and you press backspace, then the prime is removed. If you are behind and you press backspace several times, then you first enter the superscript, next remove and finally remove the superscript. Notice also that prime-symbols is necessarily a string of concatenated prime symbols. For instance, is represented by f<rprime|'†>.

The below and above tags are used to explicitly attach a script below or above a given content. Both can be mixed in order to produce content with both a script below and above:

can be produced using

These primitives can be used in order to produce wide accents above or below some mathematical content. For instance corresponds to the markup <wide|x+y|¯>.

This primitive is mainly used for producing negated symbols or expressions, such as or .

This primitive is used to produce a tree with a given root and children child-1 until child-n. The primitive should be used recursively in order to produce trees. For instance,

corresponds to the markup

In the future, we plan to provide further style parameters in order to control the rendering.

Every tabular structure in a document contains a tformat tag.

<tformat|table> means the table and cell variables defined in the top-level table tag are not modified. The table argument may be a table or a nested tformat tag, the latter does not appear in documents but is produced by the evaluation of the top-level tag.

<tformat|with-1||with-n|table> is used when the table contains specific formatting information. The with-1 to with-n arguments must all be twith or cwith tags.

The formatting of the table as a whole is specified by a number of table variables, which are used internally and do not appear in the environment like regular typesetter variables.

The twith primitive sets the table variable var (literal string) to the value val (evaluated).

The formatting of cells is specified by a number of cell variables, which are used internally and do not appear in the environment like regular typesetter variables. Rows, columns, and generally any rectangular range of cells can associated to a cell variable setting by a single cwith tag.

The cwith primitive sets the cell variable var (literal string) to the value val (evaluated) for the range of cells spanning rows top-row to bot-row and columns left-col to right-col (literal non-zero integers).

Range coordinates must be non-zero literal integers, positive values are counted left to right and top to bottom, negative values are counted right to left and bottom to top. For example, 2 means the second row or column and -1 means the last row or column.

Typical values for are for “row ”, for “column ”, and for “the cell at row , column ”. When new cells are inserted, it makes a difference whether the rows are counted from the top or bottom, and the columns are counted from the left or right. If is the number of rows and the number of columns, then and represent the same row—the former is relative to the top border while the latter is relative the bottom border. Similarly, and represent the same column.

The only purpose of the table tag is to contain row tags. The number of rows in a table is the number of subtrees in its table tag.

The only purpose of the row tag is to contain cell tags. All row tags in a given table must have exactly as many subtrees, all cell tags, as there are columns in the table.

Table cells can contain any document fragment. A cell may directly contain an inline content tag or a concat, if it has block content it must always contain a document tree.

A cell whose operand is a document is a multi-paragraph cell. Since tables are allowed in line context, this is the only construct which allows, indirectly, the nesting of a block context within a line context. Note that most block content can only be typeset correctly within an hyphenated cell, this is controlled by the cell-hyphen table variable.

In addition to regular markup, cells can accept subtable as an operand. The operand of subtable is a tformat tree containing regular table data.

A similar effect can be obtained with normal table by setting the cell's padding to zero in all directions, the extra twist of a subtable is its inaccessible border positions.

This tag is used in the definition of cell decorations, see the documentation of the cell-decoration environment variable.

It is also used outside tables, in the switch tag to mark the currently displayed position.

This macro implements standard left aligned tables without borders. Although the tabular macro is built-in into TeXmacs, it should not really be considered as a primitive. However, it is not part of any style file either.

The operand must evaluate to a literal string, it is used as a target name which can be referred to by reference, pageref and hlink tags.

Label names should be unique in a document and in a project.

Examples in this section will make references to an example label named “there”.

The operand must evaluate to a literal string, which is the name of a label defined in the current document or in another document of the current project.

The reference is typeset as the value of the variable the-label at the point of the target label. The the-label variable is set by many numbered structures: sections, figures, numbered equations, etc.

A reference reacts to mouse clicks as an hyperlink.

The operand must evaluate to a literal string, which is the name of a label defined in the current document or in another document of the current project.

The pageref is typeset as the number of the page containing the target label. Note that page numbers are only computed when the document is typeset with page-breaking, that is not in “automatic” or “papyrus” page type.

A pageref reacts to mouse clicks as an hyperlink.

This primitive produces an hyperlink with the visible text content pointing to url. The content is typeset as inline url. The url must evaluate to a literal string in URL syntax and can point to local or remote documents, positions inside documents can be be specified with labels.

The following examples are typeset as hyperlinks pointing to the label “there”, respectively in the same document, in a document in the same directory, and on the web.

If the document is not editable, the hyperlink is traversed by a simple click, if the document is editable, a double-click is required.

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.

Bind a Scheme script to a double mouse click on content. For instance, when clicking here, you may launch an xterm. This action is encoded by

When clicking on actions, the user is usually prompted for confirmation, so as to avoid security problems. The user may control the desired level of security in Edit→Preferences→Security. Programmers may also declare certain Scheme routines to be “secure”. Scheme programs which only use secure routines are executed without confirmation from the user.

Typeset the content, which must be line content, as an atomic line item. Hyphenation within the rigid and special spacing handling on its borders are disabled.

Floating insertions are page items which are typeset “out of band”, they are associated to two boxes: the anchor box marks the structural position of the float, the floating box contains the typeset body operand. This facility is used by footnotes and floating blocks.

The first and second operands are evaluated, but for clarity the first operand appears as a literal string in the examples. Since the body is typeset out of band, it may be block content even if the float occurs in line context.

<float|footnote||body> produces a footnote insertion, this should only be used within the footnote macro and is considered style markup. The floating box of a footnote is typeset at the end of the the page containing the anchor box.

<float|float|where|body> produces a floating block, this is considered physical markup. The position of the floating box is chosen by the page breaker, which uses this extra freedom to minimize the page breaking penalty.

The where operand must evaluate to a string which may contain the following characters:

t

Allow the floating box at page top.

b

Allow the floating box at page bottom.

h

Allow the floating box “here”, in the middle of the page near the anchor box.

f

Force the floating box within the same page as the anchor box.

This primitive marks body for output only on the specified medium. The following values of medium are supported:

texmacs

The body is typeset as usual line content.

latex

The body, which must be a string, is not visible from within TeXmacs, but it will be included in a verbatim way when the document is exported to LaTeX.

html

Similar to the latex medium, but for HTML exports.

screen

The body is only typeset when the document is visualized on a screen. This may be useful to provide additional visual information to the user during the editing phase which should disappear when printing out. A similar tag which may be used for this purpose is flag.

printer

This medium is complementary to screen, when the body should only be visible when printing out, but not when the document is displayed on the screen.

In some contexts you need to embed uneditable data inside a document, most of the time this is uneditable binary data. The raw-data primitive makes it impossible to view or modify its subtree from within the editor.