The operand must evaluate to a literal string, it is used as a target name which can be referred to by reference, pageref and hlink tags.

Label names should be unique in a document and in a project.

Examples in this section will make references to an example label named “there”.

The operand must evaluate to a literal string, which is the name of a label defined in the current document or in another document of the current project.

The reference is typeset as the value of the variable the-label at the point of the target label. The the-label variable is set by many numbered structures: sections, figures, numbered equations, etc.

A reference reacts to mouse clicks as an hyperlink.

The operand must evaluate to a literal string, which is the name of a label defined in the current document or in another document of the current project.

The pageref is typeset as the number of the page containing the target label. Note that page numbers are only computed when the document is typeset with page-breaking, that is not in “automatic” or “papyrus” page type.

A pageref reacts to mouse clicks as an hyperlink.

This primitive produces an hyperlink with the visible text content pointing to url. The content is typeset as inline url. The url must evaluate to a literal string in URL syntax and can point to local or remote documents, positions inside documents can be be specified with labels.

The following examples are typeset as hyperlinks pointing to the label “there”, respectively in the same document, in a document in the same directory, and on the web.

If the document is not editable, the hyperlink is traversed by a simple click, if the document is editable, a double-click is required.

The operand must be a literal string and is interpreted as a file name. The content of this file is typeset in place of the include tag, which must be placed in block context.

Bind a Scheme script to a double mouse click on content. For instance, when clicking here, you may launch an xterm. This action is encoded by <action|here|(system "xterm &")>.

When clicking on actions, the user is usually prompted for confirmation, so as to avoid security problems. The user may control the desired level of security in Edit→Preferences→Security. Programmers may also declare certain Scheme routines to be “secure”. Scheme programs which only use secure routines are executed without confirmation from the user.

The content of a mutator tag is automatically determined by the Scheme script. More precisely, TeXmacs periodically determines all mutator tags which are present in the currently opened. For each such tag, it sets the mutator path to the path for accessing its content and calls the Scheme script. This script is allowed to modify the content of the mutator and even other parts of the document (for efficiency reasons it is nevertheless recommended to mainly modify the content itself). In order to retrieve the mutator path from within Scheme, one should use the command (get-mutator-path).

Mutators are very useful in situations where TeXmacs communicates with extern systems in an interactive way. For instance, the current implementation of computer algebra (and other) sessions uses mutators. This allows the user to continue typing elsewhere in the document while the extern system is computing. Since mutator tags are automatically localized by the editor, the behaviour remains correct when the position of the mutator changes during the computation (this happens for instance when inserting a new paragraph at the start of your document).