xTxT Documentation

The Basics of Using xTxT

Basic Document Structure

An xTxT Document is fundamentally organized as a series of Lines and Paragraphs.

This is a complete and valid xTxT document.

Important definitions;

Line
A single row of text, containing no line breaks.
Blank Line
A completely blank row, containing no content.
Paragraph
A collection of one or more contiguous Lines of text, with no whitespace lines separating them. Paragraphs are always bounded by blank lines, or by the start or end of the document.

NB: Whitespace plays a crucial role in xTxT. Blank Lines are used to separate and define Paragraphs.

Declaring Elements

Each Paragraph typically represents an xTxT Element, or content within an Element.

The first Line of each Paragraph is used to declare that Paragraph as an Element.

/foo
This Paragraph has 3 lines (including the first Element line),
and declares an xTxT Element of type "foo".

Element declarations always begin with a leading /elementtype, followed by Element-specific Attribute Lines and Content Lines.

Adding Class

Add classes to your Element declaration is done by placing dot-separated class names immediately following the Element type.

/p.myClass1.myClass2
Some content here

NB: It is important not to allow any spaces before or after the period (.) delimiters.

NB: This is generally used for CSS purposes, and HTML these classes render as an HTML class attribute.

Naming Your Element

Often it is important to assign an Element a unique name (identifier) which it can be referenced by.

/p myName
Some content here

NB: The Element identifier should be unique for all Elements in the Document.

In HTML, the identifier renders as an HTML ID attribute. This is particularly useful for the targeted application of CSS.

Element Attributes

Immediately following the Element declaration Line, you can specify Attributes in the form;

$attributeName=attributeValueString

e.g.;

/p
$style=font-weight: bold; background-color: yellow;

Attributes are Element-specific. See the documentation for the Element you are writing to determine its valid Attributes and how they behave.

Implicit Elements

If you do not explicitly declare your Element

NB: Implicit Element types do not have an Element Declaraction line, they also cannot define styles, identifiers, or attributes. An Implicit Element can only contain content lines.

Paragraphs are given meaning as xTxT are also structurally related to other paragraphs

Within certain Elements, the tab character also plays an important role. In lists (/ul, /ol), the tab identifies indent item depth, whereas in other elements such as /code, the tab is simply processed as a formatting character.

Rule 1 - Element Structure

Basic element structure is;

/elementName
elementRow
elementRow
elementRow
...

Rules;

  • An element must always be preceded by a blank row (or the start of the document)
  • An element begins with a forward slash (/) which must be in the first column
  • The element name;
    • immediately follows the slash (no whitespace between)
    • ends at the end of the line, or at the first whitespace character on the line
  • Element rows;
    • may or may not exist, depending on the specific element
    • always begin on the row beneath the element name
  • The element ends at the first blank line, or at the end of the document
Rule 2 - Line breaks and styling
However, line breaks are very important to the handling of xTxT styling.

Within an element, each line of text (separated by a line break) is considered a separate chunk.

This element has two chunks;

/p 
Lorem ipsum dolor sit amet, 
consectetuer adipiscing elit.

While this element only has one;

/p 
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Rule 3 - Styles
Styles are applied within the content by wrapping the specified text in style tags, e.g.;
  • \ bold
  • \\ italics
  • \# highlight
  • see full list

So that;

Lorem \ipsum\ dolor sit amet, 
\\consectetuer\\ adipiscing \#elit\#.

Renders in HTML as;

Rule 4 - Styles only apply within an Element Row
You must begin and end a style within a row. An un-terminated style automatically terminates at the end of the row.

Consider how these rules combine.

/p
\#Lorem ipsum dolor sit amet, consectetuer\# adipiscing elit.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

/p
\#Lorem ipsum dolor sit amet, 
consectetuer\# adipiscing elit.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

element types (display, settings)...

In most display elements, chunks can also be used to keep your xTxT code readable, by beginning each sentence or phrase on a new line.

Like this;

/note
In most display elements, 
chunks can also be used to keep your xTxT code readable,
by beginning each sentence or phrase on a new line.
Rule 5 - Chunks and linking
An entire chunk can be linked as by appending a pipe character, followed by the link destination.
Google|http://www.google.com

As links are a critical element in xTxT, we need to devote a full section to the topic.

Learn all about links

Structuring Element Content Lines Effectively

Most Element types treat all lines equivalently, however xTxT formatting features and links only operate within a line, and end at the completion of the current line.

You can use this to your advantage, e.g.;

A single-line Paragraph, with styling applied;

The \quick\ brown fox jumped over the \\lazy\\ dog.

In the above example, quick is bolded, and lazy is italicized.

This Element can be written more efficiently using Lines as;

The 
\quick 
brown fox jumped over the 
\\lazy 
dog.

Because the formatting commands terminate at the end of each Line, the closing format characters are not necessary.

xTxT also has a Line-based linking syntax;

This example links just the word quick;

The 
quick|http://www.google.com/search?q=quick
brown fox

A Note on Rendering

Because xTxT is primarily a formatting language, many xTxT Elements have a one-to-one correspondence with HTML Elements, e.g.;

/p
This is a paragraph.

Renders in HTML as;

<p>This is a paragraph.</p>

However some Elements have much more complex HTML generation rules.

The xTxT /img Element, for example, can generate a compound HTML rendering comprised of a mixture of <IMG>, <P>, <DIV>, and <A> elements.