Summary of the principal TeXmacs tags

1.The common base for most styles

The std d.t.d. contains the markup which is common to virtually all styles. It is subdivided into the following parts:

1.Standard markup

Various standard markup is defined in std-markup. The following textual content tags all take one argument. Most can be found in the InsertContent tag menu.

<strong|content>

Indicates an important region of text. You can enter this tag via InsertContent tagStrong.

<em|content>

Emphasizes a region of text like in “the real thing”. This tag corresponds to the menu entry InsertContent tagEmphasize.

<dfn|content>

For definitions like “a gnu is a horny beast”. This tag corresponds to InsertContent tagDefinition.

<samp|content>

A sequence of literal characters like the ae ligature æ. You can get this tag via InsertContent tagSample.

<name|content>

The name of a particular thing or concept like the Linux system. This tag is obtained using InsertContent tagName.

<person|content>

The name of a person like Joris. This tag corresponds to InsertContent tagPerson.

<cite*|content>

A bibliographic citation like a book or magazine. Example: Melville's Moby Dick. This tag, which is obtained using InsertContent tagCite, should not be confused with cite. The latter tag is also used for citations, but where the argument refers to an entry in a database with bibliographic references.

<abbr|content>

An abbreviation. Example: I work at the C.N.R.S. An abbreviation is created using InsertContent tagAbbreviation or the Alt+A keyboard shortcut.

<acronym|content>

An acronym is an abbreviation formed from the first letter of each word in a name or a phrase, such as HTML or IBM. In particular, the letters are not separated by dots. You may enter an acronym using InsertContent tagAcronym.

<verbatim|content>

Verbatim text like output from a computer program. Example: the program said hello. You may enter verbatim text via InsertContent tagVerbatim. The tag may also be used as an environment for multi-paragraph text.

<kbd|content>

Text which should be entered on a keyboard. Example: please type return. This tag corresponds to the menu entry InsertContent tagKeyboard.

<code*|content>

Code of a computer program like in “cout << 1+1; yields 2”. This is entered using InsertContent tagCode. For longer pieces of code, you should use the code environment.

<var|content>

Variables in a computer program like in cp src-file dest-file. This tag corresponds to the menu entry InsertContent tagVariable.

<math|content>

This tag is used for mathematics inside regular text. Example: the formula is well-known.

<op|content>

This is a tag which can be used inside mathematics for specifying that an operator should be considered on itself, without any arguments. Example: the operation is a function from to . This tag may become depreciated.

<tt|content>

This is a physical tag for typewriter phase. It is used for compatibility with HTML, but we do not recommend its use.

Most of the following logical size tags can be found in InsertSize tag (or InsertSize tag):

<really-tiny|content>, <tiny|content>

<really-small|content>, <very-small|content>, <smaller|content>, <small|content>

<normal-size|content>

<large|content>, <larger|content>, <very-large|content>, <really-large|content>

<huge|content>, <really-huge|content>

These logical size tags should be used by preference when typesetting parts of your document in a larger or smaller font. Environments like footnotes or captions of tables may also be based on logical size tags. Document styles from professional publishers often assign very precise font settings to each of the logical size tags. By default, the size tags are rendered as follows:

Really tiny

Tiny

Really small

Very small

Smaller

Small

Normal size

Large

Larger

Very large

Really large

Huge

Really huge

The following are standard environments:

<verbatim|body>

Described above.

<code|body>

Similar to code*, but for pieces of code of several lines.

<quote-env|body>

Environment for short (one paragraph) quotations.

<quotation|body>

Environment for long (multi-paragraph) quotations.

<verse|body>

Environment for poetry.

<center|body>

This is a physical tag for centering one or several lines of text. It is used for compatibility with HTML, but we do not recommend its use.

Some standard tabular environments are

<tabular*|table>

Centered tables.

<block|table>

Left aligned tables with a border of standard 1ln width.

<block*|table>

Centered tables with a border of standard 1ln width.

The following tags are used to adjust the typesetting of content whenever necessary:

<smash|body>

<smash-top|body>, <smash-bottom|body>
(smash vertical size to the size of an 'x')

These macros can be used to adjust the vertical extents of the body to those of the character 'x'. In the case of smash-top and smash-bottom, only the top resp. bottom are changed.

<inflate|body>

<inflate-top|body>, <inflate-bottom|body>
(increase vertical size to the largest character in font)

These macros can be used to increase the vertical extents of the body to those of the largest character in the current font. In the case of inflate-top and inflate-bottom, only the top resp. bottom are changed. This kind of adjustments may for instance be used in order to ensure that matrices with simple textual contents always have the same size:

In fact, for a more uniform appearance, swelling is activated by default inside matrices.

<extend|content|left-lim|bot-lim|right-lim|top-lim>
(extend the size)

This primitive is similar to resize, except that the new size of the content is always larger than the original size.

The following miscellaneous tags don't take arguments:

<TeXmacs>

The TeXmacs logo.

<TeXmacs-version>

The current version of TeXmacs (2.1.4).

<made-by-TeXmacs>

A macro which may be used to indicate that your document was written using TeXmacs.

<TeX>

The TeX logo.

<LaTeX>

The LaTeX logo.

<hrule>

A horizontal rule like the one you see below:


The following miscellaneous tags all take one or more arguments:

<phantom|content>

This tag takes as much space as the typeset argument content would take, but content is not displayed. For instance, <phantom|phantom> yields “”.

<overline|content>

For overlined text, which can be wrapped across several lines.

<underline|content>

For underlined text, which can be wrapped across several lines.

<folded|summary|body>

The summary is displayed and the body ignored: the macro corresponds to the folded presentation of a piece of content associated to a short title or abstract. The second argument can be made visible using InsertSwitchUnfold.

<unfolded|summary|body>

Unfolded presentation of a piece of content body associated to a short title or abstract summary. The second argument can be made invisible using InsertSwitchFold.

<switch|current|alternatives>

Content which admits a finite number of alternative representation among which the user can switch using the function keys F9, F10, F11 and F12. This may for instance be used in interactive presentations. The argument current correspond to the currently visible presentation and alternative to the set of alternatives.

2.Standard symbols

The std-symbol d.t.d. defines the special symbols ć, ď, ě, ľ, ń, ő, ř, š, ş, ź, ţ, ű, ij, ¡, ¿, £ and Ů. It also provides the macro nbsp for non-breakable spaces.

As soon as the font support will be further improved, this d.t.d. should become obsolete.

3.Standard mathematical markup

Standard mathematical markup is defined in std-math.

<binom|among|nr>

For binomial coefficients, like .

<choose|among|nr>

Alternative name for binom, but depreciated.

<shrink-inline|among|nr>

A macro which switches to scriptsize text when you are not in display style. This macro is mainly used by developers. For instance, the binom macro uses it.

The following are standard mathematical tabular environments:

<matrix|table>

For matrices .

<det|table>

For determinants .

<choice|table>

For choice lists .

4.Standard lists

4.1.Using list environments

The standard TeXmacs lists are defined in std-list. The unnumbered lists environments are:

<itemize|body>

The tag before each item depends on the nesting depth.

<itemize-minus|body>

Uses for the tag.

<itemize-dot|body>

Uses for the tag.

<itemize-arrow|body>

Uses for the tag.

The following environments can be used for producing numbered lists:

<enumerate|body>

The kind of number before each item depends on the nesting depth.

<enumerate-numeric|body>

Number the items by 1, 2, 3, etc.

<enumerate-roman|body>

Number the items by i, ii, iii, etc.

<enumerate-Roman|body>

Number the items by I, II, III, etc.

<enumerate-alpha|body>

Number the items by a), b), c), etc.

<enumerate-Alpha|body>

Number the items by A), B), C), etc.

The following environments can be used for descriptive lists:

<description|body>

The environment for default descriptive lists (usually description-compact).

<description-compact|body>

Align the left hand sides of the items in the list and put their descriptions shortly behind it.

<description-dash|body>

Similar to description-compact, but use a — to separate each item from its description.

<description-align|body>

Align the left hand sides of the descriptions, while aligning the items to the right.

<description-long|body>

Put the items and their descriptions on distinct lines.

New items in a list are indicated through the item tag or the item* tag in the case of descriptions. The item tag takes no arguments and the item* tag one argument. When using the experimental structured-list package, these tags may take an optional body argument. In the future, all list items should become structured.

By default, items in sublists are numbered in the same way as usual lists. Each list environment list admits a variant list* whose items are prefixed by the last item in the parent list. Of course, this feature can be used recursively.

4.2.Customization of list environments

The std-list provides the following redefinable macros for customizing the rendering of lists and items in lists:

<render-list|body>

This block environment is used to render the body of the list. Usually, the macro indents the body and puts some vertical space around it.

<aligned-item|item-text>

This inline macro is used to render the item-text in a right-aligned way. As a consequence, text after such items will appear in a left-aligned way.

<compact-item|item-text>

This inline macro is used to render the item-text in a left-aligned way. As a consequence, text after such items may be indented by the width of the item-text (except when the text is rendered on a different paragraph).

5.Automatic content generation

The std-automatic d.t.d. contains macros for the automatic generation and rendering of auxiliary content. There are four main types of such content in TeXmacs: bibliographies, tables of contents, indexes and glossaries. Other types of automatically generated content like lists of figures are usually similar to one of the four above types (in the case of lists of figures, we use glossaries). The rendering of the entire sections which contain the bibliographies, tables of contents, etc. are specified in the section-base d.t.d..

5.1.Bibliographies

The following macros may be used in the main text for citations to entries in a bibliographic database.

<cite|ref-1||ref-n>

Each argument ref-i is a citation corresponding to an item in a BiB-TeX file. The citations are displayed in the same way as they are referenced in the bibliography and they also provide hyperlinks to the corresponding references. The citations are displayed as question marks if you did not generate the bibliography. Once you've added a bibliography file, pressing Tab inside the arguments will auto-complete with the cite-keys in your file.

<nocite|ref-1||ref-n>

Similar as cite, but the citations are not displayed in the main text.

<cite-detail|ref|info>

A bibliographic reference ref like cite and nocite, but with some additional information info, like a chapter or a page number.

The following macros may be redefined if you want to customize the rendering of citations or entries in the generated bibliography:

<render-cite|ref>

Macro for rendering a citation ref at the place where the citation is made using cite. The content may be a single reference, like “TM98”, or a list of references, like “Euler1, Gauss2”.

<render-cite-detail|ref|info>

Similar to render-cite, but for detailed citations made with cite-detail.

<render-bibitem|content>

<transform-bibitem|content>

At the moment, bibliographies are generated by BibTeX and imported into TeXmacs. The produced bibliography is a list of bibliographic items with are based on special LaTeX-specific macros (bibitem, block, protect, etc.). These macros are all defined internally in TeXmacs and eventually boil down to calls of the render-bibitem, which behaves in a similar way as item*, and which may be redefined by the user.

The transform-bibitem is used to “decorate” the content. For instance, transform-bibitem may put angular brackets and a space around content.

<bib-list|largest|body>

The individual “bibitems” are enclosed in a bib-list, which behaves in a similar way as the description environment, except that we provide an extra parameter largest which contains a good indication about the largest width of an item in the list.

5.2.Tables of contents

The following macros may be used in the main text for adding entries to the table of contents. They are automatically called by most sectional macros, but it is sometimes desirable to manually add additional entries.

<toc-main-1|entry>

<toc-main-2|entry>

Create an important entry in the table of contents. The macro toc-main-1 is intended to be used only for very important entries, such as parts of a book; it usually has to be added manually. The macro toc-main-2 is intended to be used for chapter or sections. Important entries are usually displayed in a strong font.

<toc-normal-1|entry>

<toc-normal-2|entry>

<toc-normal-3|entry>

Add a normal entry to the table of contents, of different levels of importance. Usually, toc-normal-1 corresponds to sections, toc-normal-2 to subsections and toc-normal-3 to subsubsections.

<toc-small-1|entry>

<toc-small-2|entry>

Add an unimportant entry to the table of contents, like a paragraph. Since such entries are not very important, some styles may simply ignore the toc-small-1 and toc-small-2 tags.

By redefining the following macros, it is possible to customize the rendering of tables of contents:

<toc-strong-1|content|where>

<toc-strong-2|content|where>

Used for rendering table of contents entries created using toc-main-1 resp. toc-main-2.

<toc-1|content|where>

<toc-2|content|where>

<toc-3|content|where>

<toc-4|content|where>

<toc-5|content|where>

Used for rendering table of contents entries created using toc-normal-1, toc-normal-2, toc-normal-3, toc-small-1 resp. toc-small-2.

<toc-dots>

The separation between an entry in the table of contents and the corresponding page number. By default, we use horizontal dots.

5.3.Indexes

The following macros may be used in the main text for inserting entries into the index.

<index|primary>

Insert primary as a primary entry in the index.

<subindex|primary|secondary>

Insert secondary in the index as a subentry of primary.

<subsubindex|primary|secondary|ternary>

Similar to subindex but for subsubentries ternary.

<index-complex|key|how|range|entry>

Insert complex entries into the index. This feature is documented in detail in the section about index generation.

<index-line|key|entry>

Adds entry to the index, by sorting it according to key.

The following macros may be redefined if you want to customize the rendering of the index:

<index-1|entry|where>

<index-2|entry|where>

<index-3|entry|where>

<index-4|entry|where>

<index-5|entry|where>

Macro for rendering an entry in the index on page(s) where. The macro index-1 corresponds to principal entries, the macro index-2 to secondary entries, and so on.

<index-1*|entry>

<index-2*|entry>

<index-3*|entry>

<index-4*|entry>

<index-5*|entry>

Similar to index-1 until index-5, but without the page number(s).

<index-dots>

Macro for producing the dots between an index entry and the corresponding page number(s).

5.4.Glossaries

The following macros may be used in the main text for inserting glossary entries.

<glossary|entry>

Insert entry into the glossary.

<glossary-dup|entry>

For creating an additional page number for an entry which was already inserted before.

<glossary-explain|entry|explanation>

A function for inserting a glossary entry with its explanation.

<glossary-line|entry>

Insert a glossary entry without a page number.

The following macros can be redefined if you want to customize the rendering of the glossary:

<glossary-1|entry|where>

Macro for rendering a glossary entry and its corresponding page number(s).

<glossary-2|entry|explanation|where>

Macro for rendering a glossary entry, its explanation, and its page number.

<glossary-dots>

Macro for producing the dots between a glossary entry and the corresponding page number(s).

6.Utilities for writing style files

The std-utils package provides several macros which may be useful when writing style files. First of all, the following macros may be used for rendering purposes:

<hflush>

<left-flush>

<right-flush>

Low level tags for flushing to the right in the definition of environments. One usually should use wide-normal or wide-centered instead.

<wide-normal|body>

<wide-centered|body>

These tags are used to make the body span over the entire paragraph width. The text is left-aligned in the case of wide-normal and centered in the case of wide-centered. Making a body span over the entire paragraph width does not change the rendering on paper, but it facilitates the editing on the document. Indeed, on the one hand, the box which indicates that you are inside the environment will span over the entire paragraph width. On the other hand, when clicking sufficiently close to the text inside this box, it becomes easier to position your cursor at the start or at the end inside the environment. You may check this by clicking on one of the texts below:

>Some text inside a wide-normal environment.<

>Some text inside a wide-centered environment.<

<padded-normal|space-above|space-below|body>

<padded-centered|space-above|space-below|body>

These tags are variants of <wide-normal|body> and <wide-centered|body>, which put some vertical white space space-above and space-below above and below the body.

<wide-bothlined|top-border|bot-border|top-sep|bot-sep|body>

<wide-std-bothlined|body>

<padded-bothlined|space-above|space-below|top-border|bot-border|top-sep|bot-sep|body>

<padded-std-bothlined|space-above|space-below|body>

<wide-underlined|bborder|bsep|body>

<wide-std-underlined|body>

These tags are used to make the body span over the entire paragraph width and to put a horizontal rule above and/or below it. The widths of the rules are given by top-border and bot-border and the separation between the rules by top-sep and bot-sep. The standard width and separation (used by wide-std-bothlined, padded-std-bothlined and wide-std-underlined) are 1ln and 1sep. The padded variants specify additional spaces space-above and space-below above and below the rules. As an example, <wide-std-underlined|left<htab|5mm>right> yields:

left
right

Wide underlined environments are typically used for page headers. Wide environments which are both overlined and underlined are typically used for abstracts or floating figures and tables.

<wide-framed|border-width|hsep|vsep|body>

<wide-std-framed|body>

<wide-framed-colored|border-color|body-color|border-width|hsep|vsep|body>

<wide-std-framed-colored|border-color|body-color|body>

These tags put the body inside a frame box which spans over the whole paragraph. The user may specify a border-width, horizontal and vertical separations hsep and vsep between the border and the text, and colors border-color and body-color for the border and the background. For instance, <wide-std-framed-colored|brown|pastel green|Hi there!> yields

Hi there!

<indent-left|left-amount|body>

<indent-right|right-amount|body>

<indent-both|left-amount|right-amount|body>

These environments may be used in order to increase the current left and/or right indentation by the amounts left-amount and/or right-amount.

<margin-first-other|first-margin|other-margin|body>

This environment allows to set the margin first-margin for the first lines of paragraphs in the body, as well as the margin other-margin for the other lines. This environment is for instance useful for glossaries, indexes, etc., in which case other-margin is often larger than first-margin. Notice that this environment enables indentation for the first line of body.

The following macros may be used in order to set headers and footers:

<set-header|header-text>

A macro for permanently changing the header. Notice that certain tags in the style file, like sectional tags, may override such manual changes.

<set-footer|footer-text>

A macro for permanently changing the footer. Again, certain tags in the style file may override such manual changes.

<blanc-page>

Remove all headers and footers from this page.

<simple-page>

Remove the header of this page and set the footer to the current page number (centered). This macro is often called for title pages or at the start of new chapters.

Other macros provided by std-utils are:

<localize|text>

This macro should be used in order to “localize” some English text to the current language. For instance, <with|language|french|<localize|Theorem>> yields Théorème.

<map|fun|tuple>

This macro applies the macro fun to each of the entries in a tuple (or the children of an arbitrary TeXmacs tag) and returns the result as a tuple. For instance, <map|<macro|x|<em|x>>|<tuple|1|2|3>> yields (the quote only appears when rendering the result, not when performing further computations with it).

7.Counters and counter groups

In TeXmacs, all automatic numbering of theorems, sections, etc. is done using “counters”. Such counters may be individual counters (like equation-nr) or belong to a group of similar counters (like in the case of theorem-nr). TeXmacs allows for the customization of counters on an individual or groupwise basis. Typically, you may redefine the rendering of a counter (and let it appear as roman numerals, for instance), or undertake special action when increasing the counter (such as resetting a subcounter).

New individual counters are defined using the following meta-macro:

<new-counter|x>

Defines a new counter with name x. The counter is stored in the numerical environment variable x-nr and in addition, the following macros are defined:

<the-x>

Retrieve the counter such as it should be displayed on the screen.

<reset-x>

Reset the counter to .

<inc-x>

Increase the counter. This macro may also be customized by the user so as to reset other counters (even though this is not the way things are done in the standard style files).

<next-x>

Increase the counter, display the counter and set the current label.

For the purpose of customization, the new-counter macro also defines the following macros:

<display-x|nr>

This is the macro which is used for transforming the numerical value of the counter into the value which is displayed on the screen.

<counter-x|x>

This internal macro is used in order to retrieve the name of the environment variable which contains the counter. By default, this macro returns “nr-x”, but it may be redefined if the counter belongs to a group.

As noticed in the introduction, TeXmacs uses counter groups in order to make it possible to treat similar counters in a uniform way. For instance the counter group theorem-env regroups the counters theorem, proposition, lemma, etc. New counter groups are defined using:

<new-counter-group|g>

Create a new counter group with name g. This results in the creation of the following macros:

<display-in-g|x|nr>

<counter-in-g|x>

These macros are similar to the macros display-x and counter-x from above, but relative to the counter group. The name x of the counter in consideration is passed as an argument.

New counters can be added to the group using:

<add-to-counter-group|x|g>

Defines a new counter x and add it to the counter group g. For counters in groups, the macros display-x and counter-x are replaced with the corresponding macros display-in-g and counter-in-g for their groups. Nevertheless, two new macros ind-display-x and ind-counter-x are defined which may take over the roles of display-x and counter-x in the case when the group consists of individual counters.

At any moment, you may decide whether the counters of a group share a common group counter, or whether they all use their individual counters. This feature is used for instance in order to switch between American style numbering and European style numbering:

<group-common-counter|g>

Use a common counter for the group (which is stored in the environment variable g-nr).

<group-individual-counters|g>

Use an individual counter for each member of the group (this is the default).

We notice that group counters may recursively belong to super-groups. For instance, the following declarations are from env-base.ts:

<document|<new-counter-group|std-env>>

<new-counter-group|theorem-env>

<add-to-counter-group|theorem-env|std-env>

<group-common-counter|theorem-env>

8.Special markup for programs

The program d.t.d. provides markup for the layout of computer programs. However, these tags should be considered as very unstable, since we plan to replace them by a set of more detailed tags:

<algorithm|name|body>

The name of the algorithm and its body, which includes its possible specification.

<body|body>

The real body of the algorithm.

<indent|content>

For indenting part of an algorithm.

9.Special markup for sessions

The session d.t.d. provides the following environments for computer algebra sessions:

<session|body>

Environment for marking a session. All macros below are only for use inside sessions.

<input|prompt|body>

An input field with a prompt and the actual input.

<output|body>

An output field.

<textput|body>

Fields with ordinary text. These may for instance be used for comments and explanations.

<errput|body>

This macro is used inside output fields for displaying error messages.

In fact, these environments are based on environments of the form lan-session, lan-input, lan-output, lan-textput and lan-errput for every individual language lan.

If language-specific environments do not exist, then generic-session, generic-input, generic-output, generic-textput and generic-errput are taken instead. It is recommended to base the language-specific environments on the generic ones, which may have different implementations according to the style (e.g. the framed-session package). For this purpose, we also provide the generic-output* environment, which is similar to generic-output, except that margins remain unaltered.