TeXmacs primitives (FSF GNU project)

TeXmacs primitives

In this chapter, we describe those built-in TeXmacs primitives which are intended to be used in normal documents. The additional primitives which are used for writing style files are described in a separate chapter.

1.Fundamental primitives

<document|par-1|⋯|par-n>

(vertical sequence of paragraphs)

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

A simple document.

Made of several paragraphs. The second paragraph is very long, so that it is hyphenated across several line.

is internally represented as a document with two subtrees:

<document|A simple document.|Made of several paragraphs. The second paragraph is very long, so that it is hyphenated across several line.>

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

<paragraph|unit-1|⋯|unit-n>

(vertical sequence of paragraph units)

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.

<concat|item-1|⋯|item-n>

(horizontal sequence of inline markup)

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

Some emphasized text.

is internally represented as:

<concat|Some |<em|emphasized>| text.>

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:

Multiple paragraphs.

Some emphasized text.

In this example, we need the concat tag in order to indicate that “Some emphasized text.” correponds 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.

<surround|left|right|body>

(surround block content with inline content)

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,

<document|<surround|↯ ||<document|<theorem|<document|Given P∈T{F} and f<g∈T with P(f) P(g)<0, there exists an h∈T with P(h) = 0.>>>>>

produces

↯ Theorem 1. Given P∈T{F} and f<g∈T with P(f) P(g)<0, there exists an h∈T with P(h) = 0.

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

2.Formatting primitives

2.1.White space primitives

<vspace|len>

<vspace|len|min|max>

(vertical space after)

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.

<vspace*|len>

<vspace*|len|min|max>

(vertical space before)

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.

<space|len>

<space|len|bot|top>

(rigid horizontal space)

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.

<hspace|len>

<hspace|len|min|max>

(stretchable horizontal space)

This primitive inserts 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.

<htab|min>

<htab|min|weight>

(horizontal spring)

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.

2.2.Line breaking primitives

A simple document is a sequence of logical paragraphs, one for each subtree of a document or paragraph node. Paragraphs whose width exceed the available horizontal space are broken into physical lines by the hyphenation algorithm. By default, hyphenated lines are justified: horizontal spaces can be shrunk or extended in order to produce a good-looking layout.

<new-line>

(start a new paragraph)

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.

<next-line>

(start a new line)

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 addional property that the line before the break is not justified or filled.

<line-break>

(line breaking hint, with filling)

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.

<no-break>

(forbid line breaking at this point)

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 group tag.

2.3.Indentation primitives

There are two main ways to distinguish between successive paragraphs: separate them by a small vertical space, or use an indentation for each new paragraph. The indentation can be explicitly controlled using the no-indent, yes-indent, no-indent* and yes-indent* tags. The no-indent and yes-indent primitives apply to the current paragraph, while the no-indent* and yes-indent* apply the next paragraph.

<no-indent>

<yes-indent>

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

<document|<no-indent>This is a long paragraph which demonstrates the disabling indentation using the <markup|no-indent> primitive.|<yes-indent>This is a long paragraph which demonstrates enabling indentation using the <markup|yes-indent> primitive.>

typically produces

This is a long paragraph which demonstrates the disabling indentation using the no-indent primitive.

This is a long paragraph which demonstrates enabling indentation using the yes-indent primitive.

<no-indent*>

<yes-indent*>

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

<document|A first paragraph.<yes-indent*>|A second paragraph.>

typically produces

A first paragraph.

A second paragraph.

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.

2.4.Page breaking primitives

The physical lines in a document are broken into pages in a way similar to how paragraphs are hyphenated into lines. The page breaker performs page filling, it tries to distribute page items evenly so text runs to the bottom of every page. It also tries to avoid orphans and widows, which are single or pairs of soft lines separated from the rest of their paragraph by a page break, but these can be produced when there is no better solution.

<no-page-break>

(prevent automatic page breaking after this line)

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.

<no-page-break*>

(prevent automatic page breaking before this line)

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

<new-page>

(start a new page after this 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.

<new-page*>

(start a new page before this line)

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

<page-break>

(force a page break after this line)

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.

<page-break*>

(force a page break before this line)

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

When several “new page” and “page break” directives apply to the same point in the document, only the first one is effective. Any new-page or page-break after the first one in a line is ignored. Any new-page or page-break in a line overrides any new-page* or page-break* in the following line. Any new-page* or page-break* after the first one in a line is ignored.

2.5.Box operation primitives

<move|content|delta-x|delta-y>

(adjust position)

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.

(adjust size)

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 either be empty strings (in which case the old limit is taken), an absolute coordinate, or a limit computed as a function of the old limit.

In the last case, the limit string should be of the form <pos><op><len>. The first character <pos> indicates a position in the old box and should be either l (left), b (bottom), c (center), r (right) or t (top). The second character <op> indicates the operation which will be performed on this position and the remaining length string <len> in order to yield the new position. Possible operations are +, -, [ and ]. The brackets [ and ] stand for “minimum” and “maximum”. For instance, the code

(<resize|Hopsa|l-5mm||r+5mm||>)

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

(Hopsa)

<if*|condition|content>

(conditional appearance of 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>.

<repeat|content|pattern>

(fill line)

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.

<datoms|foo|content>

<dlines|foo|content>

<dpages|foo|content>

(decorations)

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

<\datoms|

< macro | x |

body

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

Here is a sufficiently long paragraph. Here is a sufficiently long paragraph. Here is a sufficiently long paragraph. Here is a sufficiently long paragraph. Here is a sufficiently long paragraph. Here is a sufficiently long paragraph.

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

<\assign|

toc-dots

<\macro|

<\datoms|

<macro|x|<repeat|x|<space|0.2fn>.<space|0.2fn>>>

<htab|5mm>

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

3.Mathematical primitives

<left|large-delimiter>

<left|large-delimiter|size>

<left|large-delimiter|bottom|top>

<mid|large-delimiter|⋯>

<right|large-delimiter|⋯>

(large delimiters)

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

langle

a₁

a₂

|⋯|

a_n

rangle.

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

f (

x +

y +

z

)

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

f<left|(|-8mm|4mm>x<mid|||8mm>y<right|)|-4mm|8mm>

is rendered as

f(x|y)

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

g<left|(|0><left|(|1><left|(|2><left|(|3>z<right|)|3><right|)|2><right|)|1><right|)|0>

is rendered as

g((((z))))

<big|big-symbol>

(big symbols)

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

∑_{∞

i = 0}a_i zⁱ

(1)

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 ∑

∞

i = 0

a_i zⁱ. 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>.

<frac|num|den>

(fractions)

The frac primitive is used in order to render fractions like

x

y

. 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

a₀ +

a₁ +

a₂ + ⋱

<sqrt|content>

<sqrt|content|n>

(roots)

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

sqrt _{i + j} (

f(x)

y² + z²

)

<lsub|script>

<lsup|script>

<rsub|script>

<rsup|script>

(scripts)

These primitives are used in order to attach a script to the preceeding 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

_{b

a} + ₁²x_{4

3} = y₁ + _c

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:

lim_n→∞a_n

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.

<lprime|prime-symbols>

<rprime|prime-symbols>

(primes)

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 f' and you press backspace, then the prime is removed. If you are behind fⁿ and you press backspace several times, then you first enter the superscript, next remove n and finally remove the superscript. Notice also that prime-symbols is necessarily a string of concatenated prime symbols. For instance, f'† is represented by f<rprime|'†>.

<below|content|script>

<above|content|script>

(scripts above and below)

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:

above (below (xor, i = 1), ∞) x_i

can be produced using

<above|<below|xor|i=1>|∞> x<rsub|i>

<wide|content|wide-symbol>

<wide*|content|wide-symbol>

(wide symbols)

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

<neg|content>

(negations)

This primitive is mainly used for producing negated symbols or expressions, such as not(↣) or not(a).

<tree|root|child-1|⋯|child-n>

(trees)

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

<tree|+|x|y|<tree|×|2|y|z>>

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

4.Table primitives

Tables are always present in documents inside evaluable tags which take a tformat operand. All fundamental table structures have inaccessible borders. The basic top-level table tag is tabular.

<tformat|with-1|⋯|with-n|table>

(table formatting container)

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.

<twith|var|val>

(set a table variable)

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

(set a cell variable for a range)

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 (top-row,bot-row,left-col,right-col) are (r,r,1, - 1) for “row r”, (1, - 1,c,c) for “column c”, and (r,r,c,c) for “the cell at row r, column c”. 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 m is the number of rows and n the number of columns, then r and r - m - 1 represent the same row—the former is relative to the top border while the latter is relative the bottom border. Similarly, c and c - n - 1 represent the same column.

<table|row-1|⋯|row-n>

(row container)

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.

<row|cell-1|⋯|