TeXmacs style files

One of the fundamental strengths of TeXmacs is the possibility to write your own style files and packages. The purpose of style files is multiple:

• They allow the abstraction of repetitive elements in texts, like sections, theorems, enumerations, etc.
• They form a mechanism which allow you to structure your text. For instance, you may indicate that a given portion of your text is an abbreviation, a quotation or “important”.
• Standard document styles enable you to write professionally looking documents, because the corresponding style files have been written with a lot of care by people who know a lot about typography and aesthetics.

The user may select a major style from the Document→Style menu. The major style usually reflects the kind of document you want to produce (like a letter, an article or a book) or a particular layout policy (like publishing an article in a given journal).

Style packages, which are selected from the Document→Style menu, are used for further customization of the major style. For instance, the number-europe package enables European-style theorem numbering and the maxima package contains macros for customizing the layout of sessions of the Maxima computer algebra system. Several packages may be used together.

When you want to add your own markup to TeXmacs or personalize the layout, then you have to choose between writing a principal style file or a style package. In most cases, you will probably prefer to write a style package, since this will allow you to combine it arbitrary other styles. However, in some cases you may prefer to create a new principal style, usually by personalizing an existing style. This is usually the case if you want to mimic the layout policy of some journal. In this chapter, we will both explain how to write your own style packages and how to customize the standard styles.

1.Writing a simple style package

Let us explain on an example how to write a simple style package. First of all, you have to create a new buffer using File→New and select the source document style using Document→Style→source. Now save your empty style package in your personal style package directory

    $HOME/.TeXmacs/packages

Notice that the button Texts in the file browser corresponds to the directory

    $HOME/.TeXmacs/texts

Consequently, you can go to the style package directory from there, by double clicking on .. and next on packages. Similarly, the directory

    $HOME/.TeXmacs/styles

contains your personal style files. After saving your empty style package, it should automatically appear in the Document→Package menu. Notice that style files must be saved using the .ts file extension. If you save the style file in a subdirectory of $HOME/.TeXmacs/packages, then it will automatically appear in the corresponding submenu of Document→Package.

Let us now create a simple macro hi which displays “Hello world”. First type A-=, so as to create an assignment. You should see something like

Now enter “hi” as the first argument and type A-m inside the second argument in order to create a macro. You should now see something like

Finally, type the text “Hello world” in the body of the macro. Your document should now consist of the following line:

After saving your style package, opening a new document and selecting your package in the Document→Use package menu, you may now use the macro hi in your document by typing \ h i and hitting return.

In a similar way, you may create macros with arguments. For instance, assume that we started entering a macro hello in a similar way as above. Instead of typing “Hello world”, we first type A-left inside the macro body so as to create an additional argument on the left hand side of the cursor. We next enter the name of the argument, say “name”. You should now see something like below:

In the second argument of the body, we now type “Hello ”, A-#, “name”, right and “, how are you today?”. After this you should see

The A-# shortcut is used to retrieve the macro argument name. Instead of typing A-#, “name” and right, you may also use the hybrid \-key and type \ n a m e followed by return. After saving your style package, you may again use the macro in any document which uses your package by typing \ h e l l o and hitting return.

From the internal point of view, all macro definitions are stored in the environment of the TeXmacs typesetter. Besides macros, the environment also contains normal environment variables, such as section counters or the font size. The environment variables can either be globally changed using the assign primitive, or locally, using the with primitive. For instance, when including the line

in your package, and using article as your major style, then the first section will be numbered 0. Similarly, the variant

of the hello macro displays the name of the person in Small Capitals. Notice that the with primitive can also be used to locally redefine a macro. This is for instance used in the definitions of the standard list environments, where the macro which renders list icons is changed inside the body of the list. Yet another variant of the hello macro relies on the standard person macro:

In order to produce the macro application <person|name>, you first have to start a compound tag using A-c, type the name “person”, insert an argument A-right, and enter the argument name as before. When you are done, you may press return in order to change the compound tag into a person tag. Alternatively, you may type \, “person”, A-right and “name”.

By combining the above constructs, an ordinary user should already be able to produce style packages for all frequently used notations. An interesting technique for writing macros which involve complex formulas with some subformulas which may change goes as follows:

1. Type the formula, say (a₁,…,a_n), in an ordinary document.

2. Create the skeleton of your macro in your style package:

   <assign|n-tuple|<macro|a|>>

3. Copy the formula and paste it into the body of your macro:

   <assign|n-tuple|<macro|a|(a<rsub|1>,…,a<rsub|n>)>>

4. Replace the subformulas you want to parameterize by macro arguments:

   <assign|n-tuple|<macro|a|(a<rsub|1>,…,a<rsub|n>)>>

5. You may now use the macro in documents which use your package:

   (a₁,…,a_n) = (b₁,…,b_n).

2.Rendering of style files and packages

2.1.ASCII-based or tree-based editing: an intricate choice

Most users are used to edit source code using a conventional editor like Emacs, while presenting the source code in ASCII format. Since all TeXmacs documents are stored as trees, an interesting but complicated question is which format is most suitable for editing such documents. One option is to represent the tree using an ASCII-based format, such as XML, Scheme, or the native format for storing files on a disk. The other option is to edit the trees as such, making no fundamental distinction between source code and normal documents.

In TeXmacs we have chosen to implement the second option. More precisely, any document can be edited in “source mode”, which is merely a mode for rendering the document in a way which makes its tree structure particularly apparent. It may be instructive to take an arbitrary document of yours and to take a look at it in “source mode” by enabling Document→View→Edit source tree.

The choice between ASCII-based editing and tree-based editing is non-trivial, because TeXmacs style files and packages have a double nature: they may be seen as programs which specify how to render macros, but these programs naturally contain ordinary content. There are several reasons why users often prefer to edit source code in an ASCII-based format:

1. It is easy to manually format the code so as to make it more readable.
2. In particular, it is easy to add comments.
3. Standard editors like Emacs provide tools for automatic highlighting, indentation, etc.
4. One is not constraint by any “structure” during the editing phase.

Our approach is to reproduce as much of the above advantages in a structured document environment. Although point ? will obviously be hard to meet when following this approach, we believe that the first three advantages might actually become greater in a structured environment. However, this requires a more profound understanding of how users format and edit source code.

For instance, consider a piece of manually formatted code like

if (cond) hop   = 2;
else      holala= 3;

Clearly, the user had a particular formatting policy when writing this code. However, this policy does not appear in the document: manual intervention will be necessary if the variable cond is renamed c, or if the variable holala is renamed hola.

At the moment, TeXmacs provides no tools for dealing with the above example in an automatic way, but a few tools are already provided. For instance, the user is given a great amount of control on how to indent source code and reasonable defaults are provided as a function of the structure. We also provide high level environments for comments and structured highlighting. Further tools will be developed later and we are open for any suggestions from our users.

2.2.Global presentation

In the Source tags group of the Document→View menu, you find several ways to customize the rendering of source trees in your document. We recommend you to play around with the different possibilities in a document of your own (after enabling Document→View→Source tree) or a standard style package in $TEXMACS_PATH/packages.

First of all, you may choose between the different major styles “angular”, “scheme”, “functional” and “LaTeX” for rendering source trees, as illustrated in the figure below:

Secondly, you may wish to reserve a special treatment to certain tags like concat and document. In the menu Document→View→Special you may specify to which extent you want to treat such tags in a special way:

None

No tags receive a special treatment.

Formatting

Only the formatting tags concat and document are represented as usual.

Normal

In addition to the formatting tags, a few other tags like compound, value and arg are represented in a special way.

Maximal

At the moment, this option is not yet implemented. The intention is to allow the user to write his own customizations and to allow for special rendering of basic operations like plus.

These different options are illustrated below:

Another thing which may be controlled by the user is whether the presentation of tags should be compact or stretched out across several lines. Several levels of compactification may be specified in the Document→View→Compactification menu:

Minimal

The tags are all stretched out across several lines.

Only inline tags

All non-inline tags are stretched out across several lines.

Normal

All inline arguments at the start of the tag are represented in a compact way. As soon as we encounter a block argument, the remainder of the arguments are stretched out across several lines.

Inline arguments

All inline arguments are represented in a compact way and only block tags are stretched out across several lines.

Maximal

All source code is represented in a compact way.

The “normal” and “inline arguments” options rarely differ. The visual effect of the different options is illustrated below:

Finally, the user may specify the way closing tags should be rendered when the tag is stretched out across several lines. The rendering may either be minimalistic, compact, long, or recall the matching opening tag. The different options are illustrated below:

2.3.Local customization

Even though TeXmacs tries hard to render source code in a nice way following the global rendering options that you specified, the readability of the source code often needs to be further enhanced locally. In source mode, this can be done using the menus Source→Activation and Source→Presentation. Any local hints on how to render source code are automatically removed from the document when it is being used as a style file or package.

First of all, for certain pieces of content the user may prefer to see them in their “activated” form instead as dead source code. This may for instance be the case for embedded images, or for mathematical symbols, like in

Such an active presentation may also be preferred for certain more complex macros:

A piece of code can be activated by selecting it and using Source→Activation→Activate or M-+. Similarly, a piece of content may be deactivated using M-- (we used this in the second example above for the rendering of the arguments var and dim). Activation and deactivation either apply to the whole tree, or to the root only (e.g. Source→Activation→Activate once).

Another way to customize the rendering is to override some of the global rendering options. This is mainly interesting for controlling more precisely which tags have to be stretched across several lines and which tags have to be represented in a compact fashion. For instance, the concat tag can be used in order to concatenate content, as well as for specifying a block of sequential statements, or a combination of both. For instance, in the piece of code

we have stretched the concat tag along several lines using Source→Presentation→Stretched (notice that this implies the concat tag to appear explicitly, so as to avoid confusion with the document tag). Similarly, if a part of the concatenation were to be displayed as usual, then one may use Source→Presentation→Compact:

At present, we did not implement a way to mark arguments as inline or block, but we might do this later.

A final way to customize the rendering of source code is to apply an arbitrary macro using Source→Presentation→Apply macro or Source→Presentation→Apply macro once. This macro will be automatically removed when you use your document as a style file or package.

3.The style-sheet language

In the section about writing a simple style package we already gave you a first impression about the style-sheet language of TeXmacs. In this section, we will give a more complete survey of the available features. For more detailed descriptions, we refer to the chapter about the TeXmacs primitives.

Most style-sheet primitives can be obtained from the Source menu when you are in source mode. You may also obtain them from the Insert→Macro and Insert→Executable menus when editing usual text. Alternatively, you may use the A- and M-e prefixes in source mode and the M-i and M-e prefixes otherwise. Furthermore, we recall that the hybrid \-key may be used for creating macro-applications or arguments, depending on the context. Finally, the A-right and A-left keys are used for inserting arguments.

3.1.Assignments

All user defined TeXmacs macros and style variables are stored in the “current typesetting environment”. This environment associates a tree value to each string variable. Variables whose values are macros correspond to new primitives. The others are ordinary environment variables. The primitives for operating on the environment are available from Source→Define.

You may permanently change the value of an environment variable using the assign primitive, as in the example

You may also locally change the values of one or several environment variables using the with primitive:

The value of an environment variable may be retrieved using the value primitive. This may for instance be used in order to increase a counter:

Finally, you may associate logical properties to environment variables using the drd-props primitive. This is explained in more detail in the section about macro primitives.

3.2.Macro expansion

The main interest of the TeXmacs' style-sheet language is the possibility to define macros. These come in three flavours: ordinary macros, macros which take an arbitrary number of arguments and external macros, whose expansion is computed by Scheme or a plug-in. The macro-related primitives are available from the Source→Macro menu. Below, we will only describe the ordinary macros. For more details, we refer to the section about macro primitives.

Ordinary macros are usually defined using

After such an assignment, my-macro becomes a new primitive with n arguments, which may be called using

Inside the body of the macro, the arg primitive may be used to retrieve the values of the arguments to the macro.

It is possible to call a macro with less or more arguments than the expected number. Superfluous arguments are simply ignored. Missing arguments take the nullary uninit primitive as value:

We finally notice that you are allowed to compute with macros, in a similar way as in functional programming, except that our macros are not closures (yet). For instance:

The compound tag may be used to apply macros which are the result of a computation:

3.3.Formatting primitives

This section contains some important notes on formatting primitives which are not really part of the style-sheet language, but nevertheless very related.

First of all, most TeXmacs presentation tags can be divided in two main categories: inline tags and block tags. For instance, frac is a typical inline tag, whereas theorem is a typical block tag. Some tags, like strong are inline if their argument is and block in the contrary case. When writing macros, it is important to be aware of the inline or block nature of tags, because block tags inside a horizontal concatenation are not rendered in an adequate way. If you need to surround a block tag with some inline text, then you need the surround primitive:

In this example, we surrounded the body of the theorem with the bold text “Theorem.” at the left hand side and a “right-flush” at the right-hand side. Flushing to the right is important in order to make the blue visual border hints look nice when you are inside the environment.

In most cases, TeXmacs does a good job in determining which tags are inline and which ones are not. However, you sometimes may wish to force a tag to be a block environment. For instance, the tag very-important defined by

may both be used as an inline tag and a block environment. When placing your cursor just before the with-tag and hitting return followed by backspace, you obtain

Since the body of the macro is now a block, your tag very-important will automatically become a block environment too. In the future, the drd-props primitive will give you even more control over which tags and arguments are inline and which ones are block.

Another important property of tags is whether they contain normal textual content or tabular content. For instance, consider the definition of the standard eqnarray* tag (with a bit of presentation markup suppressed):

The use of surround indicates that eqnarray* is a block environment and the use of tformat specifies that it is also a tabular environment. Moreover, the twith and cwith are used to specify further formatting information: since we are a block environment, we enable hyphenation and let the table span over the whole paragraph (unused space being equally distributed over the first and last columns). Furthermore, we have specified that the table contains exactly three columns.

Finally, it is important to bear in mind that style-sheets do not merely specify the final presentation of a document, but that they may also contain information for the authoring phase. Above, we have already mentioned the use of the right-flush tag in order to improve the rendering of visual border hints. Similarly, visual hints on invisible arguments may be given in the form of flags:

More generally, the specific tag with first argument “screen” may be used to display visual hints, which are removed when printing the document.

3.4.Evaluation control

The Source→Evaluation menu contains several primitives to control the way expressions in the style-sheet language are evaluated. The most frequent use of these primitives is when you want to write a “meta-macro” like new-theorem which is used for defining or computing on other macros. For instance:

When calling <new-theorem|theorem|Theorem> in this example, we first evaluate all unquote instructions inside the quasi primitive, which yields the expression

Next, this expression is evaluated, thereby defining a macro theorem.

It should be noticed that the TeXmacs conventions for evaluation are slightly different then those from conventional functional languages like Scheme. The subtle differences are motivated by our objective to make it as easy as possible for the user to write macros for typesetting purposes.

For instance, when TeXmacs calls a macro <macro|x₁|⋯|x_n|body> with arguments y₁ until y_n, the argument variables x₁ until x_n are bound to the unevaluated expressions y₁ until y_n, and the body is evaluated with these bindings. The evaluation of y_i takes place each time we request for the argument x_i. In particular, when applying the macro <macro|x|x and again x> to an expression y, the expression y is evaluated twice.

In Scheme, the bodies of Scheme macros are evaluated twice, whereas the arguments of functions are evaluated. On the other hand, when retrieving a variable (whether it is an argument or an environment variable), the value is not evaluated. Consequently, a TeXmacs macro