Document syntaxes

TeXmacs represents documents as tree data structures which can be translated in plain text using different concrete syntaxes. Different syntaxes have merits and demerits and are best suited to different uses. We generally use the Scheme syntax to document TeXmacs constructs, but it is not the mythical document source code, just one particular representation.

You should always think of documents and fragments as trees. Documents can also be considered programs written the TeXmacs typesetting language, whose output is a particular typeset document. In that perspective the document tree is an abstract syntax tree.

Words in monospaced font are document tree labels, other words are document tree leaves. A tree label can either be the name of a typesetter primitive or the name of markup tag.

Documents are generally written to disk using the TeXmacs syntax. This syntax is designed to be unobtrusive and easy to read, so the content of a document can be easily understood from a plain text editor:

On the other hand, TeXmacs syntax makes style files difficult to read and is not designed to be hand-edited: whitespace has complex semantics and some internal structures are not obviously presented. Do not edit documents in the TeXmacs syntax unless you really know what you are doing.

The preferred syntax for modification is the screen display in the TeXmacs typesetting editor. If that seems surprising to you, consider that a syntax is a way to represent information in a form suitable to understanding and modification. The on-screen typeset representation of a document, together with its interactive behavior, is a particular concrete syntax:

You should always use the TeXmacs editor itself to write style files, compose document fragments for use in programs, and of course, edit whole documents. Programmatic documents, like style files, should use “preamble mode”.

In contexts where a document cannot be represented and edited in its typeset form, like in Scheme programs or in e-mails, or when the important information is the internal representation, the preferred syntax is Scheme. This syntax was designed to be predictable, easy to hand-edit, and expose the complete internal structure of the document.

(with "mode" "math" (concat "x+y+" (frac "1" "2") "+" (sqrt "y+z")))

This syntax also represent documents as conventional s-expressions and is easy to process by Scheme programs. You may also find it useful when debugging complex stylesheets.

Documents can also be represented in XML syntax. This syntax was designed to be close to the internal tree structure and use conventional XML notations which are well supported by standard tools. Whitespace generally is significant in XML, the example features some whitespace inserted at a location where it is ignored:

<with mode="math">x+y+<frac>

  <tm-arg>1</tm-arg><tm-arg>2</tm-arg></frac>+<sqrt>y+z</sqrt></with>

You should use the XML syntax only for interoperation.

This section describes the abstract syntax of documents, using the Scheme concrete syntax for reference.