Fundamental structures (FSF GNU project)

Fundamental structures

Operator	Arity	Accessible		Process	Usage
		border	children
document	1 + n	No	All	Typesetting	Logical
concat	1 + n	No	All	Typesetting	Logical
error	1	Yes	None	Display	Never
raw-data	1	Yes	None	Display	Logical

Table 1. Fundamental structures

The document and concat operators are fundamental and pervasive structures of TeXmacs documents. They are used to assemble lines and paragraphs out of all other structures.

The texmacs concrete syntax, used to save documents to disk, is designed to make these operators implicit, so they do not get in the way of reading the document content, that is one import reason why this concrete syntax is inappropriate for hand-editing.

This primitive is used for sequences of logical paragraphs. A simple, plain text, document is made of a simple sequence of paragraphs (i.e. logical lines).

A simple document.

Made of several paragraphs.

Such a document is represented a simple document tree whose subtrees are all strings.

Actually, the root of the edit tree is always a document node. Document fragments use a root document node only when they contain several top-level paragraphs.

The document operators are also found in inner subtrees wherever a multi-paragraph structure is needed, for example in list structures and multi-paragraph table cells.

Some primitives (e.g. document, include) are block content and are not allowed in line context. A position is in block context if, after evaluation, it is immediately within:

a document tree,
a multiparagraph cell , that is a cell whose operand is a document ,
a float whose body is a document ,
the last operand of a with in block context,
the last operand of a surround in block context.

This primitive is used for sequences of line items. Since the interpretation of an operator is done according to the count and position its operands, we need an operator to glue compound operands into individual trees without introducing additional logical structure.

Some emphasized text.

This fragment is made of several line items. The concat node is used to assemble them into a single logical line.

The concat operator is essential to put compound structures in trees taking multiple parameters. For example, let us place the previous fragment in a multi-paragraph context:

Multiple paragraphs.

Some emphasized text.

We absolutely need concat as a glue operator so the multiple components of the second paragraph are no considered multiple paragraphs.

Structures which are typeset inside a concat or some operators which expect inline content, is said to be in line context. A correct document may not evaluate to a tree which contains block content within an inline context and, except for multiparagraph cells, it is not possible to nest a block context within a line context.

The error and raw-data operators are much more rarely used. However, they are versatile, may be useful in numerous context, and do not fall neatly in any category, so we chose to describe them early.

This primitive should never appear in documents. It is provided as aid in tracking down invalid constructs. It is produced at evaluation time by any kind of primitive which is given improper operands.

In some contexts you need to embed uneditable data inside a document, most of the time this is uneditable binary data. The raw-data primitive makes it impossible to view or modify its subtree from within the editor.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".