TeXmacs style files

1.Writing 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 Alt+Ctrl+=, so as to create an assignment. You should see something like

Now enter “hi” as the first argument and type Alt+Ctrl+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 \HI 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 Meta+ 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 ”, Alt+Ctrl+#, “name”, and “, how are you today?”. After this you should see

The Alt+Ctrl+# shortcut is used to retrieve the macro argument name. Instead of typing Alt+Ctrl+#, “name” and , you may also use the hybrid \-key and type \NAME followed by Return. After saving your style package, you may again use the macro in any document which uses your package by typing \HELLO 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 . 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 Alt+Ctrl+C, type the name “person”, insert an argument Meta+, 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”, Meta+ 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 , 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:

   

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→Source→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→Source 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→Source→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→Source→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→Source→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 Meta++. Similarly, a piece of content may be deactivated using ? (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.

The style-sheet primitives can be obtained from the Source menu when you are in source mode. In all other modes, the Source menu becomes visible after enabling the Source macros tool in the Tools menu. Alternatively, you may use the Alt+ and Meta+E keyboard prefixes in source mode and the Meta+I and Meta+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 Meta+ and Meta+ 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 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

would correspond to a Scheme macro

(define-macro (foo x)
  ‘(let ((x (lambda () ,x)))
     (blah (x) (x)))

Conversely, the Scheme macro and function

(define-macro (foo x) (blah x x))
(define (fun x) (blah x x))

admit the following analogues in TeXmacs:

Here the primitives quote-arg and quote-value are used to retrieve the value of an argument resp. an environment variable. The TeXmacs primitives eval, quote, quasiquote and unquote behave in the same way as their Scheme analogues. The quasi primitive is a shortcut for quasi-quotation followed by evaluation.

3.5.Control flow

Besides sequences of instructions, which can be achieved using the concat primitive, and the mechanism of macro expansion, the TeXmacs style-sheet language provides a few other primitive for affecting the control flow: if, case, while and for-each. These primitives are available from the Source→Control flow menu. However, we have to warn the user that the conditional constructs are quite fragile: they only apply to inline content and the accessibility of macro arguments should not to much depend on the conditions.

The most important primitive if, which can be entered using Alt+Ctrl+?, allows for basic conditional typesetting:

In this example, appendix is a block environment consisting of a title and a body, and which is rendered as a chapter for long documents and as a section for short ones. Notice that the following implementation would have been incorrect, since the if primitive currently only works for inline content:

The if primitive may also be used in order to implement optional arguments:

However, TeXmacs is not clever enough to detect which arguments are optional and which arguments are accessible (i.e. which arguments can be edited by the user). Therefore, you will have to manually give this information using the drd-props primitive. The case, while and for-each primitives are explained in more detail in the corresponding section on the TeXmacs primitives.

3.6.Computational markup

In the menus Source→Arithmetic, Source→Text, Source→Tuple and Source→Condition you will find different primitives for computing with integers, strings, tuples and boolean values. For instance, in the following code, the new-important tag defines a new “important tag” as well as a variant in red:

Here we use the merge primitive in order to concatenate two strings. The different computational primitives are described in more detail in the corresponding section on the TeXmacs primitives.

4.Customizing the standard TeXmacs styles

Whenever the standard TeXmacs style files are inadequate for a given purpose, it is possible to write your own style files. However, designing your own style files from scratch may be a complex task, so it is usually preferable to customize the existing styles. This requires some understanding of the global architecture of the standard style files and a more precise understanding of the parts you wish to customize. In this section, we will explain the general principles. For more details, we refer to the chapter on the principal TeXmacs tags.

4.1.Organization of style files and packages

Each standard TeXmacs style file or package is based on a potentially finite number of subpackages. From an abstract point of view, this organization may be represented by a labeled tree. For instance, the tree which corresponds to the article style is represented below:

Figure 5. The tree with the packages from which the article style has been built up. In order to save space, we have regrouped the numerous children of std and env in vertical lists.

Most of the style packages correspond to a d.t.d. (data type definition) which contains the “abstract interface” of the package, i.e. the exported tags. For instance, the package std-markup corresponds to the d.t.d. std-markup. Sometimes however, several style packages match the same d.t.d.. For instance, both header-article and header-book match the d.t.d. header, since they merely implement different ways to render the same tags.

When building your own style files or packages, you may use the use-package primitive in order to include other packages. For instance, the article style essentially consists of the line

More precisely, the use-package package sequentially includes the style packages corresponding to its arguments. The packages should be in $TEXMACS_PACKAGE_PATH, which contains ., ~/.TeXmacs/packages and $TEXMACS_PATH/packages by default. Furthermore rendering information for the source code like style-with tags are discarded before evaluation of the files.

Remark 1. We strongly recommend the user to take a look at some of the standard style files and packages which can be found in

    $TEXMACS_PATH/styles
    $TEXMACS_PATH/packages

When loading using ?, these paths are in the standard load path. For instance, if you want to take a look at the std-markup package, then it suffices to type ?, followed by the file name std-markup.ts and Return.

Remark 2. It is also possible to customize the presentation of the source code of the style files and packages themselves, by using other packages in addition to source or by using another major style file based on source. In that case, the extra markup provided by such packages may be used for presentation purposes of the source code, but it is not exported when using your package in another file.

4.2.General principles for customization

Style files and packages basically enrich the current typesetting environment with a combination of

• Environment variables.

• Tags for the end-user.

• Customizable macros.

Furthermore, they may define some tags for intern implementation purposes, which will not be documented in this manual. They may also specify some logical properties of tags using the drd-props primitive.

Environment variables are almost always attributes for controlling the rendering of content, or counters for sections, equations, etc.. Although several simple tags for the end-user like strong may be redefined in your own style files, this practice is not recommended for more complex tags like section. Indeed, the section tag involves many things like resetting subcounters, entering the title into the table of contents and so on. Therefore, special additional macros are provided the customization of such tags, like section-title, section-clean and section-toc.

4.3.Customizing the general layout

The general layout of a document is mainly modified by setting the appropriate environment variables for page layout and paragraph layout. For instance, by including the following lines in your style file, you can set the page size to letter and the left and right margins to 2in:

It should be noticed that the environment variables for page layout are quite different in TeXmacs and TeX/LaTeX. In order to make it easier to adapt LaTeX style files to TeXmacs, we have therefore provided the std-latex package, which emulates the environment variables from TeX/LaTeX. Typically, this allows you determine the global layout by lines like

We notice that macros which return lengths are considered as lengths themselves. In the case of the TeX/LaTeX emulation package, we actually require all lengths to be macros.

The page headers and footers are usually not determined by global environment variables or macros, since they may change when a new chapter or section is started. Instead, TeXmacs provides the call-back macros header-title, header-author, header-primary and header-secondary. These macros are called when the document title or author are specified or when a new primary or secondary section is started (primary sections are typically chapters in books, or sections in articles). For instance, the following redefinition makes the principal section name appear on even pages, together with the current page number and a wide underline.

4.4.Customizing list environments

Lists are made up of two principal ingredients: the outer list environment and the inner items. List environments may either be customized by customizing or redefining the rendering macros for these environments, or defining additional list environments which match the same abstract interface.

The rendering of the outer list environment is controlled by the render-list macro which takes the body of the list as its argument. For instance, consider the following redefinition of render-list:

This redefinition affects the rendering of all list environments (itemize, enumerate, etc.) by reducing the right margin with a length of 3fn:

• This text, which has been made so long that it does not fit on a single line, is indented on the right hand side by 3fn.

  1. This text is indented by an additional 3fn on the right hand side, since it occurs inside a second list environment.

• Once again: this text, which has been made so long that it does not fit on a single line, is indented on the right hand side by 3fn.

In a similar way, you may customize the rendering of list items by redefining the macros aligned-item and compact-item. These macros both take one argument with the text of the item and render it either in a right-aligned way (such that subsequent text is left aligned) or in a left-aligned way (such that subsequent text may not be aligned). For instance, consider the following redefinition of aligned-item:

Then items inside all list environments with compact items will appear in red:

• This list and aligned descriptions have red items.

  C1

  First condition.

  C2

  Second condition.

• The items of compact description lists are rendered using compact-item.

  Gnus and gnats

  Nice beasts.

  Micros and softies

  Evil beings.

Remark 3. The macros aligned-item and compact-item are required to produce inline content, so that they may be used in order to surround blocks. In particular, several other internal macros (aligned-space-item, long-compact-strong-dot-item, etc.) are based on aligned-item and compact-item, and used for the rendering of the different types of lists (itemize-arrow, description-long, etc.). In the future, we also plan to extend item and item* with a compulsory body argument. When customizing the list environments, it is important to keep that in mind, so as to make your style-sheets upward compatible.

The std-list d.t.d. also provides a macro new-list to define new lists. Its syntax is <new-list|name|item-render|item-transform>, where name is the name of the new list environment, item-render an (inline) macro for rendering the item and item-transform an additional transformation which is applied on the item text. For instance, the enumerate-roman environment is defined by

4.5.Customizing numbered textual environments

TeXmacs provides three standard types of numbered textual environments: theorem-like environments, remark-like environments and exercise-like environments. The following aspects of these environments can be easily customized:

• Adding new environments.

• Modifying the rendering of the environments.

• Numbering the theorems in a different way.

Defining new environments

First of all, new environments can be added using the meta-macros new-theorem, new-remark and new-exercise. These environments take two arguments: the name of the environment and the name which is used for its rendering. For instance, you may wish to define the environment experiment by

When available in the TeXmacs dictionaries, the text “Experiment” will be automatically translated when your document is written in a foreign language. In the section about how to define new environments, it is also explained how to define other numbered textual environments (besides theorems, remarks and exercises).

Customization of the rendering

The principal rendering of the environments can be customized by redefining the render-theorem, render-remark and render-exercise macros. These macros take the name of the environment (like “Theorem 1.2”) and its body as arguments. For instance, if you want theorems to appear in a slightly indented way, with a slanted body, then you may redefine render-theorem as follows:

This redefinition produces the following effect:

Theorem 4.

By default, the theorems are rendered as remarks with the only difference that their bodies are typeset in an italic font. Hence, redefining the render-remark macro will also affect the rendering of theorems. The default render-proof macro is also based on render-remark.

Instead of redefining the entire rendering, the user might just wish to customize the way names of theorems are rendered or redefine the separator between the name and the body. As the user may have noticed by examining the above redefinition of render-theorem, these aspects are controlled by the macros theorem-name and theorem-sep. For instance, consider the following redefinitions:

Then theorem-like environments will be rendered as follows:

Proposition 5: This proposition is rendered in is a fancy way.

Customization of the numbering

In the sections about counters and counter groups, it is explained how to customize the counters of numbered environments for particular purposes. For instance, by redefining inc-theorem, you may force theorems to reset the counter of corollaries:

Notice the trick with quasi and unquote in order to take into account additional action which might have been undertaken by the previous value of the macro inc-theorem.

The following code from number-long-article.ts is used in order to prefix all standard environments with the number of the current section:

4.6.Customizing sectional tags

By default, TeXmacs provides the standard sectional tags from LaTeX part, chapter, section, subsection, subsubsection, paragraph, subparagraph, as well as the special tag appendix. TeXmacs also implements the unnumbered variants part*, chapter*, etc. and special section-like tags bibliography, table-of-contents, the-index, the-glossary, list-of-figures, list-of-tables.

Remark 6. Currently, the sectional tags take one argument, the section title, but a second argument with the body of the section is planned to be inserted in the future (see the experimental structured-section package). For this reason (among others), style files should never redefine the main sectional tags, but rather customize special macros which have been provided to this effect.

From a global point of view, an important predicate macro is sectional-short-style. When it evaluates to true, then appendices, tables of contents, etc. are considered to be at the same level as sections. In the contrary case, they are at the same level as chapters. Typically, articles use the short sectional style whereas book use the long style.

The rendering of a sectional tag x is controlled through the macros x-sep, x-title and x-numbered-title. The x-sep macro prints the separator between the section number and the section title. It defaults to the macro sectional-sep, which defaults in its turn to a wide space. For instance, after redefining

sectional titles would typically look like

The x-title and x-numbered-title macros respectively specify how to render unnumbered and numbered section titles. Usually, the user only needs to modify x-title, since x-numbered-title is based on x-title. However, if the numbers have to be rendered in a particular way, then it may be necessary to redefine x-numbered-title. For instance, consider the redefinition

This has the following effect on the rendering of subsection titles:

Notice that the section-base package provides several useful helper macros like sectional-normal.

Remark 7. Sectional titles can either be rendered in a “short” or in the “long” fashion. By default, paragraphs and subparagraphs use the short rendering, for which the body starts immediately at the right of the title:

All other sectional tags use the long rendering, in which case the section title takes a separate line on its own:

We do not recommend to modify the standard settings (i.e. to render paragraphs in a long way or sections in a short way). If you really want to do so, then we recommend to redefine the corresponding environment variables enrich-x-long. This will ensure upward compatibility when sectional tags will take an additional argument (see remark ?).

Besides their rendering, several other aspects of sectional tags can be customized:

• The call-back macro x-clean can be used for cleaning some counters when a new section is started. For instance, in order to prefix all standard environments by the section counter, you may use the following lines:

  <document|<assign|section-clean|<macro|<reset-subsection><reset-std-env>>>|<assign|display-std-env|<macro|nr|<section-prefix>nr>>>

• The call-back macro x-header should be used in order to modify page headers and footers when a new section is started. Typically, this macro should call header-primary, or header-secondary, or do nothing.

• The call-back macro x-toc should be used in order to customize the way new sections appear in the table of contents.

4.7.Customizing the treatment of title information

TeXmacs uses the doc-data tag in order to specify global data for the document. These data are treated in two stages by the doc-data macro. First, the document data are separated into several categories, according to whether the data should be rendered as a part of the main title or in footnotes or the abstract. Secondly, the data in each category are rendered using suitable macros.

Each child of the doc-data is a tag with some specific information about the document. Currently implemented tags are doc-title, doc-subtitle, doc-author, doc-date, doc-running-title, doc-running-author, doc-keywords, doc-msc and doc-note. The doc-author tag may occur several times. The author-data tag is used in order to specify structured data for each of the authors of the document. Each child of the author-data tag is a tag with information about the corresponding author. Currently implemented tags with author information are author-name, author-affiliation, author-email, author-homepage and author-note.

Most of the tags listed above also correspond to macros for rendering the corresponding information as part of the main title. For instance, if the date should appear in bold italic at a distance of at least 1fn from the other title fields, then you may redefine doc-date as

The title-block macro is used in order to make the text span appropriately over the width of the title. The doc-title and author-name are special in the sense that they also render possible references to footnotes. For this reason, you should rather customize the doc-render-title and author-render-name macros in order to customize the rendering of the title and the name themselves.

Notice also that the doc-running-title and author-running-author macros do not render anything, but rather call the header-title and header-author call-backs for setting the appropriate global page headers and footers. By default, the running title and author are extracted from the usual title and author names.

In addition to the rendering macros which are present in the document, the main title (including author information, the date, etc.) is rendered using the doc-make-title macro. The author information, as part of the main title, is rendered using render-doc-author or render-doc-authors, depending on whether the document has one or more authors. Footnotes to the title or to one of the authors are rendered using doc-title-note resp. doc-author-note. These footnote macros always expect a document tag on input, because they may compress it into a horizontal concatenation.

The first stage of processing the document data is more complex and the reader is invited to take a look at the short descriptions of the macros which are involved in this process. It is also good to study the definitions of these macros in the package itself. In order to indicate the way things work, we finish with an example on how the email address and homepage of an author can be rendered in a footnote instead of the main title:

5.Further notes and tips

5.1.Customizing arbitrary tags

Imagine that you want to change the rendering of a given tag, like lemma. As a general rule, TeXmacs provides a set of well-chosen macros which can be customized by the user so as to obtain the desired effect. For instance, as we have seen above, you should use modify one of the macros render-theorem, theorem-name or theorem-sep in order to customize the rendering of lemma and all other theorem-like environments.

However, in some cases, it may not be clear which “well-chosen” macro to customize. If we just wanted to change the presentation of lemmas and not of any other theorem-like environments, then we clearly cannot modify render-theorem, theorem-name or theorem-sep. In other cases, the user may not want to invest his time in completely understanding the macro hierarchy of TeXmacs, and find out about the existence of render-theorem, theorem-name and theorem-sep.

So imagine that you want all lemmas to appear in red. One thing you can always do is copy the original definition of lemmas in a safe place and redefine the lemma macro on top of the original definition:

Alternatively, if only the text inside the lemma should be rendered in red, then you may do:

Of course, you have to be careful that the name orig-lemma is not already in use.

Another frequent situation is that you only want to modify the rendering of a tag when it is used inside another one. On the web, the Cascading Style Sheet language (CSS) provides a mechanism for doing this. In TeXmacs, you may simulate this behaviour by redefining macros inside a with. For instance, imagine that we want the inter-paragraph space inside lists inside theorem-like environments to vanish. Then we may use:

On the one hand side, this mechanism is a bit more complex than CSS, where it suffices to respecify the par-par-sep attribute of lists inside theorems. On the other hand, it is also more powerful, since the render-theorem macro applies to all theorem-like environments at once. Furthermore, if the above mechanism is to be used frequently, then real hackers may simplify the notations using further macro magic.

5.2.Standard utilities

In the package std-utils, the user may find several useful additional macros for writing style files. It mainly contains macros for

• Writing block environments which span over the entire paragraph width. Notice that the title-base package provides some additional macros for wide section titles.

• Writing wide block environments which are underlined, overlined or in a frame box.

• Recursive indentation.

• Setting page headers and footers.

• Localization of text.

It is good practice to use these standard macros whenever possible when writing style files. Indeed, the low-level TeXmacs internals may be subject to minor changes. When building upon standard macros with a clear intention, you increase the upward compatibility of your style-sheets.