Mathematical Typesetting in TeXmacs

1.Overview

In this chapter we describe the algorithms used by TeXmacs in order to typeset mathematical formulas. This is a difficult subject, because esthetics and effectiveness do not always go hand in hand. Until now, TeX is widely accepted for having achieved an optimal compromise in this respect. Nevertheless, we thought that several improvements could still be made, which have now been implemented in TeXmacs. We will shortly describe the motivations behind them.

In order to obtain esthetic formulas, what criteria should we use? It is often stressed that good typesetting allows the reader to concentrate on what he reads, without being distracted by ugly typesetting details. Such distracting details arise when distinct, though similar parts of text are typeset in a non uniform way:

The eye expects text of a similar nature to be typeset with respect to a same base line. For instance, in , the bottoms of the and should be at the same height as the bottom of the -part in the . This should again be the case in .

Different components of text with approximately the same function should be separated by equal amounts of space. For instance, in , the typesetter should notice the hangover of the . This should again be the case in . Similarly, the distance between the baselines of the and the in should not be disproportionally large with respect to the height of an .

Additional difficulties may arise when considering automatically generated formulas, in which case line breaking has to be dealt with in a satisfactory way.

Unfortunately, the different esthetic criteria may enter into conflict with each other. For instance, consider the formula . On the one hand, the baselines of the scripts should be the same, but the other hand, the first subscript should not be “disproportionally low” with respect to the . Unfortunately, this dilemma can not been solved in a completely satisfactory way without the help of a human for the simple reason that the computer has no way to know whether the and are “related”. Indeed, if the and are close (like in ), then it is natural to opt for a common base line. However, if they are further away from each other (like in ), then we might want to opt for different base lines and locally optimize the rendering of the first .

Consequently, TeXmacs should offer a reasonable compromise for the most frequent cases, while offering methods for the user to make finer adjustments in the remaining ones. We provide the constructs →→ and →→ to move and resize boxes in order to perform such adjustments. For instance, if the brackets around the two sums

have different sizes, then one may resize the bottom of the subscript of the second sum to 0fn. Alternatively, one may resize the bottoms of both the and subscripts to (say) -0.3fn. For easier adjustments you may use →→ and →→ to automatically adjust the size of the contents to the height of the character “x” and the largest one in the font respectively.

Notice that one should adjust by preference in a structural and not visual way. For instance, one should prefer -0.3fn to -2mm in the above example, because the second option disallows you to switch to another font size for your document. Similarly, you should try not change the semantics of the formula. For instance, in the above example, you might have added a “dummy subscript” to the subscript of the sum. However, this would alter the meaning of the formula (whence make it non suitable as input to a computer algebra system) In the future, we plan to provide additional constructs in order to facilitate structural adjusting. For instance, in the case of a formula like

one might think of a construct to enclose the entire formula into an area, where all scripts are forced to be double (using dummy superscripts wherever necessary).

2.Mathematical primitives

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

(1)

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

Notice that the formula (1) 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.

3.The font parameters

Several font parameters are crucial for the correct positioning of the different components. The following are often needed:

The main font reference space 1fn, which can be taken as the distance between successive lines of text.

The bottom and top level for the font (we have y2-y1=quad).

The reference minimal space between distinct components, like the minimal distance between a subscript and a superscript. In fact, sep=quad/10.

The width of several types of lines, like the fraction and square root bars, wide accents, etc.

The height of the fraction bar, which is needed for the positioning of fractions and big delimiters. Usually, yfrac is almost equal to yx/2 below.

The following parameters are mainly needed in order to deal with scripts:

The height of the character, which is needed for the positioning of scripts. All the remaining parameters are actually computed as a function of yx.

Logical base line for subscripts.

Subscripts may never physically exceed this top height.

Logical base line for superscripts.

Superscripts may never physically exceed this bottom height.

Suggestion for a physical top line for superscripts.

Possible shift of the base lines when we are inside fractions or scripts.

The individual strings in a font also have several important positioning properties. First of all, they always admit left and right slopes. Furthermore, they admit left and right italic corrections, which are needed for the positioning of scripts or when passing from text in upright to text in italics (or vice versa).

4.Implementation of the mathematical primitives

The typesetting semantics of TeXmacs documents is implemented by

in src/Typeset/Concat/concat_math.cpp which dispatch according to the current tree label to more specialized routines, which we will describe below.

Tree labels for mathematical typesettings are (in scr/Kernel/Types/tree_label.hpp)

They provide labels for the primitives to typeset brackets (around, var_around, big_around, left, mid, right), sub/super-scripts (lsup, lsub, rsup, rsub), accents (lprime, rprime), above and below formulas (below, above) fractions (frac), roots (sqrt), wide under and over braces (wide, var_wide), negations (neg), and trees (tree) or syntax (syntax) constructions.

4.1.Primed expressions

Primed expressions are encoded in TeXmacs as

<math|a<rprime|'>,a<rprime|‡>,<lprime|‡>s>

and are typeset via the following code (the code for rprime is analogous and is not shown):

Note that we output an LSUP_ITEM, since later on, in a second pass, we need to reposition these boxes as we will do for sub, superscripts.

The replace_primes function:

4.2.Fractions

Fractions can be inline or in display style and have different variants (standard frac, display dfrac, small inline tfrac, continued cfrac and slashed frac*). For example

<dfrac|\<mathd\>x|\<mathd\>y>,<space|2em> <frac*|\<mathd\>x|\<mathd\>y>, <math|<dfrac|dx|dy>,<space|2em><frac*|dx|dy>,<space|2em><tfrac|dx|dy>,>

<cfrac|1|1+<cfrac|1|1+<cfrac|1|1+x>>>

Apart from frac, the others tags are implemented in std-maths.ts as:

The frac tag is primitive and typesetted by concater_rep::typeset_frac :

The "math-vpos" environment variable is set to depending on where we are in the typesetting of fractions. This is used in the finalization routines. [Add more?]

The function frac_box inserts an instance of frac_box_rep

The following heuristics are used:

• The horizontal middles of the numerator and the denominator are taken to be the same.

• The vertical spaces between the numerator resp. denominator and the fraction bar is at least sep.

• The depth (resp. height) of the numerator (resp. denominator) is descended (resp. increased) to y1 (resp. y2) if necessary. This forces the base lines of not too large numerators resp. denominators to be the same in presence of multiple fractions.

• The fraction bar has a overhang of sep/2 to both sides and the logical limits of the fraction are another sep/2 further. The logical left limit is zero.

The italic corrections are not taken into account during the positioning algorithms, because this may create the impression that the numerator and denominator are not correctly centered with respect to each other. Nevertheless, the italic corrections are taken into account in order to compute the logical bounding box of the fraction (whose has italic slopes vanish at both sides).

In the case the fraction's numerator or denominator are very wide a fallback typesetting strategy is used, according to:

4.3.Roots

The following heuristics are used:

• The vertical space between the main argument and the upper bar is at least sep.

• The root itself is typeset like a large delimiter. The positioning of a potential script is very dependent on the usage of TeX fonts. [make precise]

• The upper bar has a overhang of sep/2 at the right and the logical right limit of the root is situated another sep/2 further to the right.

We take the logical right border plus the italic correction of the main argument in order to determine the right hand limit of the upper bar. The left italic correction is not needed.

<sqrt|1+<frac|3|4>+\<cdots\>+d>

Typesetting goes as follows:

Wide versions of the square root goes as follows:

4.4.Negations

Negations are barred expressions:

The following heuristics are used:

• The negation bar passes through the logical center of the argument.

• The italic corrections of the argument are only taken into account during the computation of the logical limits of the negation box (which has zero left and right slopes).

Typesetting of negation tags is very elementary

and give rise to negation boxes:

4.5.Wide boxes

Wide boxes are used for under and over-braces and wide accents:

<wide*|x+y|\<wide-underbrace\>><rsub|s> <wide|x+\<cdots\>+y|\<wide-overbrace\>><rsup|s>

The following heuristics are used:

• We use TeX fonts for small accents and an ad hoc algorithm for the wider ones.

• The distance between the main argument and the accent is at least sep (or a distance which depends on the TeX font for small accents).

• The accent is positioned horizontally according to the right slope of the main argument.

• The slopes for the accented box are inherited from those of the main argument and the italic corrections are adjusted accordingly.

• All script height parameters of the accented box are inherited from the main argument. The only exception is ysup_hi_lim, which may be increased by the height of the accent, or determined in the generic way, whichever leads to the least value. It is indeed better to keep superscripts positioned reasonably low, whenever possible.

wide_box produces a wide_box_rep whose constructor perform further computations and handling of special cases:

The computation of the wide accent is more involved and divided in several cases.

To complete the description we discuss wide_box and wide_stix_box which are variants of the same logic:

the concrete selection of the appropriate glyph which fits the horizontal size of wide construction is performed by get_wide (or get_stix_wide):

4.6.Subscripts and superscripts

The positioning of subscripts and superscripts is a complicated affair, due to the conflict between locally and globally optimal esthetics mentioned above. The base line for a subscript is determined as follows:

1. Always pretend that the subscript has height at least y2-yshift in the script font (actually we should use the height of an instead).

2. Try to position the script at the base line given by the main argument.

3. If the top limit (given by the main argument) is physically exceeded by the subscript, then the base line is moved further down accordingly.

The base line for a superscript is determined as follows:

1. Try to physically position the superscript beneath the suggested top line. Usually, this will place the superscript to far down.

2. Move the superscript up to the logical base line if necessary. This will usually occur: most of the time, the logical base line is the just the height of an -script below the suggested top line.

3. If the superscript physically descends below the physical under limit given by the main box, then we move the superscript further upwards.

If both a subscript and a superscript were present, then we still have to adjust the base lines: if the top of the subscript and the bottom of the superscript are not physically separated by sep, then we both move the subscript and the superscript by the same amount away from each other. Because of step 1 in the positioning of the subscript, the base lines of double scripts will usually be the same in formulas with several of them.

The right slope and italic correction of a script box may be non trivial. In order to compute them, we first determine the script (or main argument), whose right limit (taking into account its italic correction) is furthest to the right (this may be the main box, in the case of a big integral with a tiny subscript). Then the right slope of the main box is inherited by the right slope of this script (or main argument). As to the italic correction, it is precisely the difference between the right offset of the script plus its italic correction minus the logical right coordinate of the entire box. The italic correction should be at least zero though. The left slope and italic correction are computed in a similar way.

[Explain the code below]

4.7.Big operators

Big operators, like the big sum, products or integrals

<big|sum><rsub|n=1><rsup|N>a<rsub|n>

<big|prod><rsub|n=1><rsup|\<infty\>> <around*|(|1-<frac|1|n>|)>

<big|int>x<rsup|2>\<mathd\>x

It has two basic shapes, either in display style as above or inline as , , .

They are typeset by:

where we note the handling of limits and of the correct spacing after the symbol. The relevant glyph for <big|sum> is <big-sum-N> where N=1,2 according to the appropriate size. Note that for Unicode fonts (type == FONT_TYPE_UNICODE) we dispatch the selection of the glyph to a rubber obtained via rubber_font.

The function big_operator_box takes care of the proper vertical placement of the glyph:

4.8.Big delimiters

The automatic positioning and computation of sizes of big delimiters is again complicated because of potential conflicts between locally and globally optimal esthetics.

First of all, TeX fonts come only with a discrete set of possible sizes for large delimiters. This is an advantage from the point of view that it favorites delimiters around slightly different expressions to have the same baselines. However, it has the disadvantage that delimiters are easily made “one size to large”. For this reason, we actually diminish the height and the depth of the delimited expression by the small amount sep, before computing the sizes of the delimiters.

Secondly, it is best when the vertical middles of big delimiters occur at the height of fraction bars. However, in a formula like

it may be worth it to descend the delimiters a bit. On the other hand, slight vertical shifts in the middles of the delimiters potentially have a bad effect on base lines, like in

In TeXmacs, we use the following compromise: we start with the middle of the delimited expression as a first approximation to the middle of the delimiters. The real middle is obtained by shifting this middle towards the height of fraction bars by an amount which cannot exceed sep.

From a horizontal point of view, we finally have to notice that we adapted the metrics of the big delimiters in a way that potential scripts are positioned in a better way. For instance, according to the TeX tfm file, in a formula like

the square rather seems to be a left superscript of the second closing bracket than a right superscript of the first one. This is particularly annoying in the case of automatically generated formulas, where this situation occurs quite often.

Markup looks like

<around*|[| <around*|{| <frac|1|2>+\<cdots\>+<frac|3|4> |}>+\<alpha\> |]>

for automatic sizing of the brackets and like

<around*|<left|[|5>| <around*|<left|{|2>| 1+\<cdots\>+3 |<right|}|2>>+\<alpha\> |<right|]|5>>

for manual sizing. The typesetting of big delimiters proceeds in various phases. A first phase fixes the basic structure and horizontal positioning of the three arguments of the around tag. If requested via an appropriate environment variable, we use different colors to emphasize the matching brackets.

The expression make_large (LEFT, t[0]) ensures that the first and third subtrees have a specific structure, of the form <left|[|5> for a fixed size or <left|[> if there is automatic sizing.

The typesetting of LEFT, RIGHT and MID markup is dispatched as follows in concater_rep::typeset:

and realised as follows:

Note that the main branch for markup like <left|[> produces only a text box with an appropriate glyph. The vertical size of the glyph is still not correct at this point. Since it depends on the globality of the current expression and not known when typesetting the left bracket. It will be determined later on. See Section 4.11.

4.9.Long arrows

Long arrows refers to the following markup:

A<long-arrow|<rubber-rightarrow>||<text|a long arrow>>B

allowing for material above and below. The typesetting of long arrows do not require further mechanisms to those already put in place for wide boxes:

It introduces lim_box_rep which takes care of the relative positioning of the various subboxes (limit_box returns a lim_box_rep):

4.10.Above and below boxes

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:

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

Like long arrows, above and below tags also rely on lim_box_rep for their graphical rendering:

4.11.Finalization

The computation of the correct size of extensible brackets and the proper placement of super/sub-scripts require a second pass through the line_item array that concater is currently typesetting. This triggered by concater_rep::finish ():

kill_spaces and pre_glue simplify the line_items array:

while pre_glue put together neightbor sub and super scripts on the same side labelling them with the line items type GLUE_LSUBS_ITEM or GLUE_RSUBS_ITEM:

The function handle_brackets fixes the size of the extensible brackets and middle marks and also the global placement of scripts :

The placement of scripts is the job of handle_scripts:

with the help of the following subsidiary routines: [explain more]

Finally, the sizing of the brackets is the job of handle_matching:

Again, a key point of this procedure is the call to delimiter_box (in src/Typeset/Boxes/Basic/text_boxes.cpp) in order to replace the “temporary” vertical delimiter, with a correctly sized one (be it a left, right or middle delimiter).

The function get_delimiter queries the font for a sequence of glyphs in the form <left-[-N> (for example) with N=0,1,2,3,4,... until we obtain the required height.

5.Final remarks

A list of possible improvements to the code reviewed in this document:

• The mechanism to select appropriate glyphs do not depend on specific details of the typesetting process apart from the required size, so maybe can be moved into the font (and possibly allow for simplification in this generic part)

• Ideally we want to try to remove dependence on specific fonts in this part of code, all the required measurements should be available in a generic way from the current font without further tweaking (or less of it).

• Allow for OpenType MATH table information (if available) to be used, e.g. in the placement of various math constructions.