Structured Text Formatting Manual

This document describes the Structured Text format used by the LCG.

Table of Contents:

Introduction
Brief Overview of Most Important Constructs
General Recommendations
Detailed Structured Text Formatting Manual

Introduction

Structured text is a very simple and straightforward set of rules how to format a plain text document. The formatting allows to mark the logical structure of sections, paragraphs, bullet lists etc.

The constructs mostly have a semantical, not presentational nature. This means that we should not decide based on the intended appearance of the content, but it's semantical meaning. For example we don't use a heading, because we want a large font in bold, but because it is the title of following logical section of the document.

Presentational properties of particular logical elements can be systematically changed using style sheets. Thus they are completely independent of the content itself. This is on of the major preconditions for the consistence of the final document and a smooth user experience.

Another advantage of this approach is that the document source stays easily readable and editable without any particular software tool. Just a simple text editor can do the job. This makes it totally portable and accessible. A number of different target formats may be generated from one source.

Misunderstanding or not respecting the fundamental principal of separation of the logical and the presentational aspect of the document may lead to an initial frustration for users, who are used to format documents visually, however once you get used to the fact that your only goal is to mark the text up properly and you leave all the job of choosing the right presentation to the computer, you discover it does not restrict you, but it gives you more freedom. You can fully concentrate on the content itself and don't care too much of its presentation. This, however, would not work without your knowledge of the rules used for recognizing different logical elements of the document. So we will explain the most important constructs now.

Brief Overview of Most Important Constructs

The following section contains only a brief and simplified description of the most important constructs. You will find a complete description of all supported constructs in the second part of this document called Detailed Structured Text Formatting Manual.

Table of Contents:

Paragraphs
Sections
Bullet Lists
Definition Lists
Field-Sets
Links
Images
Audio and Video

Paragraphs

A paragraph is each continual block of text. Whenever you leave a blank line, you start a new paragraph. The line-breaks within the paragraph are ignored, since the paragraph will be reformatted to fit the output media (i.e. browser window).

Sections

Sections let you create an additional logical structure within the text content. The section hierarchy can be listed in a Table of Contents, which allows easy navigation within this hierarchy (similarly as in this manual).

A section starts with a sections header. The header is marked by a section title surrounded by equation signs. The number of the equation signs determines the level.

Example:

 = Main Heading =

 Top level content.

 == First Section ==

 This paragraph belongs to the first section.

 === Subsection of the First Section ===

 This text belongs to the subsection.

 == Second Section ==

 This is a second section on the same level as the first one.

Bullet Lists

Bullet lists should be used whenever the content can be split into a sequence of separate items. Each item is marked by an asterisk and may be indented.

Example:

 * cat
 * dog
 * hamster

This will be presented as:

cat
dog
hamster

Bullet lists can be nested, you can also make ordered lists etc. More details can be found in the Bullet Lists and Ordered Lists.

Definition Lists

Definition lists are useful for writing down a series of terms or expressions and their corresponding descriptions. You write them down by indenting the description following immediately after the term.

Example:

Learning Content Generator (LCG)
  LCG is a software tool able to process structured textual and multimedia data
  and produce an output presentation which is suitable for use in an on-line or
  off-line learning environment.

Wiking
  Wiking is an accessible content management system written on top of the Pytis
  toolkit and LCG.

This will be presented as:

Learning Content Generator (LCG): LCG is a software tool able to process structured textual and multimedia data and produce an output presentation which is suitable for use in an on-line or off-line learning environment.
Wiking: Wiking is an accessible content management system written on top of the Pytis toolkit and LCG.

See Definition Lists for a detailed syntax description.

Field-Sets

In general, a field-set can be used to represent any logically paired data set. They are similar to definition lists, but they are more suitable for label/value type of pairs (rather than term/description).

Example:

:Phone:   254 354 645
:Fax:     254 354 648
:e-mail:  info@yourdomain.com

This will be presented as:

Phone

254 354 645

Fax

254 354 648

e-mail

info@yourdomain.com

See Field-Sets for a detailed syntax description.

Links

Links are hypertext references to other documents or sections within them. They are written using square brackets. Each link has its target, may have an explicit label (text displayed in place of the link) and an optional description for tooltip text. Target is the first text in the brackets up to the first space, label follows and description may follow after the pipe character (`|'). If the link label is not defined explicitly, the system will use the title of the target document or section where possible. Certain kinds of targets are recognized automatically and thus don't require square brackets.

Examples:

 * link to another document: [intro]
 * link to another section of the same document: [#bullet-lists]
 * with an explicit name: [#bullet-lists Bullets]
 * with a description (tooltip): [#bullet-lists Bullets | Using Bullet Lists]
 * external link: [http://www.freebsoft.org Free(b)soft laboratory]
 * automatic link: http://www.gnu.org
 * email address: yourname@yourdomain.com

Resulting links:

link to another document: intro
link to another section of the same document: Bullet Lists
with an explicit name: Bullets
with a description (tooltip): Bullets
external link: Free(b)soft laboratory
automatic link: http://www.gnu.org
email address: yourname@yourdomain.com

See Links and Automatic Links for more details.

Images

Links with an image in place of a link target display the image inline. Links with an image instead of link label display an image which acts as a link.

 * simple image: [http://www.google.com/accounts/google_white.gif]
 * with ALT text: [http://www.google.com/accounts/google_white.gif Google logo]
 * image link: [http://www.opensource.org http://www.opensource.org/trademarks/open_source_button.png]
 * image link with label: [http://www.opensource.org
   http://www.opensource.org/trademarks/open_source_button.png 
   OSI | Open Source Initiative]

Resulting images:

simple image:
with ALT text:
simple image link:
image link with label and description:

See Images and Image Links for more details.

Audio and Video

Similarly as images, also audio files in MP3 format, videos in FLV format and links to YouTube and Vimeo services are automatically recognized.

Links to audio recordings will appear as ordinary links in HTML, but these links will act as a remote control of the audio player displayed at the bottom right corner of the browser window. Full keyboard accessibility is also implemented. See Audio for more information.

Links to videos in FLV format are represented by an embedded multimedia player. Also links to Youtube and Vimeo videos are detected and an embedded player is displayed automatically. See Video for more information.

General Recommendations

Get familiar with the available constructs and always use those, which best fit given purpose. Nearly everything can be written down as one long paragraph of text, but using the constructs, such as bullet lists, definition lists etc. can make the text much better readable. You will also greatly simplify the orientation and navigation for users of assistive technologies.
Never miss-use any logical construct just to achieve it's presentational properties (such as font size or type, indentation etc.) unless it really fits logically. Try to re-consider the logical structure of the information if you can't find a suitable construct.
Use tables only if there is no other means to express the information and only when it really is tabular data. It is, for example, often possible to express the same information by nested lists instead of tables. This form may be often more accessible to the users of assistive technologies.
Use hypertext links as much as possible to simplify navigation between documents and their sections. See Links for more information.
Whenever there is some information repeated at different places, detach it to a separate document/section and link to it from those places.
Avoid long sentences. Short, simple and clear sentences are much better readable.
Don't overuse text emphasizing. A document blazing with many different font sizes and styles is hard to read.

Detailed Structured Text Formatting Manual

This section describes all the supported constructs and their syntax in depth. See the Brief Overview of Most Important Constructs for a simplified description.

Table of Contents:

Block Constructs
Inline Constructs
Other Features
Deprecated Features
- Non-breakable Space
- Long Dash

Block Constructs

Block (or structural) constructs influence the document structure. They usually work with blocks of text. Inline Constructs, on the other hand, are used within these blocks.

Sections

As described in the Brief Overview of Most Important Constructs, sections form a hierarchical structure of the document.

Section headings are marked by equation characters at the beginning and end of the line. The text between the equation signs is a section title. The number of the equation signs determines the level.

Example:

 = Main Heading =

 Everything after the section heading belongs to this section, until another
 section heading is found.  Any number of paragraphs or other constructs can be
 used within the text of a section.

 == First Section ==

 Since the heading has more equation signs than the previous one, this section
 logically belongs to the previous section in the hierarchy.

 === Subsection of the First Section ===

 This text belongs to the subsection.

 == Second Section ==

 This is a second section on the same level as the first one.

The space between the title and the equation marks is important. Otherwise the section is not recognized.

Anchors

Additionally an anchor name can be defined for each section heading. The anchor can consist of alpha-numerical characters, underscores and dashes and is written at the end of the heading line separated with at least one blank character (space).

 == Introduction == intro

An anchor can be used to refer to the section. The link [#intro], for example, will refer to the above section header and the full section title will be supplied as the link name (see Links for more details).

Tables of Contents

Table of contents is a hierarchical list of all sections within a document or it's part. It can be included in the document using the @TOC@ macro.

Example:

Table of Contents: @TOC@

This source line will be replaced with the table of contents. The text before the colon is used for the caption and the TOC includes all the subsections of the section, within which the macro is used. This means you can also create local tables of contents in particular subsections.

The TOC at the beginning of the Detailed Structured Text Formatting Manual was made the same way.

@TOC@ is used to list sections within one document. You may also wish to list documents of the document hierarchy. This can be done by using the @NodeIndex@ macro. The syntax is the same.

The Tables of Content are hierarchical by default. You may wish to restrict the depth of the hierarchy. This can be done by supplying a number in round brackets, such as:

Index: @TOC(1)@

This will list just the top level sections without their subsections. The TOC at the top of this document was made the same way.

Bullet Lists

Bullet lists are marked by an asterisk (or optionally a minus sign) at the beginning of each item. The indentation determines the level (lists can be nested).

Example:

 * cats
   - black
   - white
   - other
 * dogs
   * big
   * little
 * frogs

This will be presented as:

cats
- black
- white
- other
dogs
- big
- little
frogs

Ordered Lists

Ordered lists work like Bullet Lists but you use a number or a letter with a period (or round brackets) instead of an asterisk.

Example:

 * General rules:
   1. Longer item texts can be split over multiple lines, provided
      that they are indented properly.
   2. Tabs and spaces can be used for indentation, but tab is always considered
      8 characters wide, so you may have problems when your editor sets the tab
      width differently (then converting tabs to spaces is recommended).
   3. A list item may contain one or more paragraphs of text.

   4. Empty lines between the list items are optional and have no effect on the
      output.  That's just a matter of your preference.

 * Rules for ordered lists:
   0. The numbers in the source document are ignored, since the output numbers
      are automatically generated.  Thus you are free to mark all items with
      zero, for example, or you can use real order numbers if you prefer.
   0. You can also use letters for alphabetically ordered lists.
 * Intermixing different kinds of lists:
   a) There are basically three different kinds of lists:
      (1) unordered
      (2) numerically ordered
      (3) alpha-ordered
   b) Whenever you switch from one kind to another (at the same indentation
      level), the previous list is finished and ordering starts from the
      beginning.
   c. It does not matter, whether you use a dot or brackets in the source
      text.  The output style of each list kind is given by the style sheet.

This will be presented as:

General rules:
1. Longer item texts can be split over multiple lines, provided that they are indented properly.
2. Tabs and spaces can be used for indentation, but tab is always considered 8 characters wide, so you may have problems when your editor sets the tab width differently (then converting tabs to spaces is recommended).
3. A list item may contain one or more paragraphs of text.
4. Empty lines between the list items are optional and have no effect on the output. That's just a matter of your preference.
Rules for ordered lists:
1. The numbers in the source document are ignored, since the output numbers are automatically generated. Thus you are free to mark all items with zero, for example, or you can use real order numbers if you prefer.
2. You can also use letters for alphabetically ordered lists.
Intermixing different kinds of lists:
1. There are basically three different kinds of lists:
  1. unordered
  2. numerically ordered
  3. alpha-ordered
2. Whenever you switch from one kind to another (at the same indentation level), the previous list is finished and ordering starts from the beginning.
3. It does not matter, whether you use a dot or brackets in the source text. The output style of each list kind is given by the style sheet.

Definition Lists

Definition lists are useful for writing down a series of terms or expressions and their corresponding descriptions. The term/description pairs are separated by blank lines from each other.

Example:

Term syntax
   Definition term is a one line text immediately followed by a description.

Description syntax 
   Definition description follows immediately after the term and is indented by
   one or more spaces.  Multiple lines are allowed as long as they are all
   indented.

This will be presented as:

Term syntax: Definition term is a one line text immediately followed by a description.
Description syntax: Definition description follows immediately after the term and is indented by one or more spaces. Multiple lines are allowed as long as they are all indented.

Field-Sets

Field-sets can be used for generic two-column tabular data, where the first column is the label and the second column is the corresponding value. The label is marked with colons from both sides. Values can be multi-line, but must be indented properly.

:Birth Date: 1975-08-30
:Address:
   38 Ocean View Dr. //
   Laguna Beach
:Occupation: Oil Magnate

Birth Date

1975-08-30

Address

38 Ocean View Dr.
Laguna Beach

Occupation

Oil Magnate

Preformatted Text

You can mark a block of text as a preformatted text by surrounding it by lines of five or more dashes.

No further formatting is then applied to the preformatted text. It is rendered as it appears in the source document.

Example:

 ------
  foo   bar
   x     y
   1     2
 ------

This will be presented as:

 foo   bar
  x     y
  1     2

All the examples in this manual are written as preformatted text.

Tables

You can make simple tables with constant number of cells per row. Each row is on one line and vertical bars characters are used to separate the cells. The line must also begin and end with a vertical bar character. If the vertical bar character is immediately followed by a dash, horizontal line is generated at that place (some backends may omit the horizontal line).

Example:

|        | *Height* | *Weight* | *Sex*  |
|---------------------------------------|
| Dick   |      72" |   130lbs | male   |
| Jane   |      65" |   150lbs | female |

	Height	Weight	Sex
Dick	72"	130lbs	male
Jane	65"	150lbs	female

Column headers are automatically recognized if the whole first row contains only bold or empty cells, as in the example above.

Cell alignment is also detected — if left padding (spaces or tabs) is greater than right padding within a cell, the cell is aligned left. You can also define cell alignments and widths explicitly by including a special row with cells of the form like <r20> or <c> where the letter is one of l (left), r (right), c (center) and the optional number defines cell width in characters. Paddings within cells are ignored if such a specification row is present and the specification row doesn't appear in the output. Note that some backends may ignore alignment and width specifications.

If you want to separate table columns by vertical bars, you can use another specification row containing cells of the form < (bar on the left), > (bar on the right) or <> (bars on both left and right). Note that some backends may not produce the vertical bars.

Example of a table with format specification rows:

| <>     | <        |          | >      |
| <l10>  | <r>      | <r10>    | <l>    |
|        | *Height* | *Weight* | *Sex*  |
|---------------------------------------|
| Dick   |      72" |   130lbs | male   |
| Jane   |      65" |   150lbs | female |

	Height	Weight	Sex
Dick	72"	130lbs	male
Jane	65"	150lbs	female

Horizontal Alignment

You can request the following object to be put on the left, on the right or in the center by preceding it with @left, @right or @center (or @centre) respectively on a separate line. Note alignment currently works only on tables and paragraphs and only in some backends.

Example:

@left
This text will be placed on the left.

@right
This text will be placed on the right.

This text will be placed on the left.

This text will be placed on the right.

Inline Constructs

Inline constructs are used inside blocks of text. They don't influence the document structure, but they allow you to use different kinds of elements within blocks.

Text Emphasizing

You can use emphasized text, strong text, underlined text, fixed font, or their combinations.

The source code for the paragraph above looks like:

You can use /emphasized text/, *strong text*, _underlined text_, =fixed font=,
/*or their _combinations_*/.

Links

Links can be used to refer to other documents, web addresses, sections etc. They are marked by square brackets and they have the following structure:

[<link-target> <link-label> | <link-description>]

Link target: This is the first text within square brackets up to the first space. It can be a document or section identifier or an external URL. See examples below for possible link targets.
Link label: Defines the user visible link text. If not present, the system will try to supply the label automatically (depending on link target type as described below). An image may be used in place of label to produce an image link.
Link description: Also optional, separated by the `|' pipe character. It's output presentation depends on the output media. In HTML, for example, the description is represented as a tooltip by most browsers.

Possible link targets are:

Local document: Local documents (other documents within the same hierarchy) are referenced by their identifier directly. Document title becomes the link label automatically.
Local section: A section within the same document is referenced by its anchor name (see Anchors) prefixed by a hash (`#' character). A section of another document is a concatenation of document title and anchor. Section title is used for link label automatically.
External target: Target which is not recognized as local document or section is treated as an external URL. Labels are not determined automatically for external links so if you don't specify an explicit label, the URL itself is used for the label.
Image: If the target is detected to be an image the link is presented as inline image.

Examples:

 * Local document: 
   - automatic label: [intro]
   - explicit label: [intro LCG Introduction]
 * Local section:
   - same document: [#anchors]
   - other document: [usage#run]
   - explicit label: [#links Using links in documents]
   - description: [#links Links | Complete description of using links in LCG structured text]
 * External links:
   - [http://www.gnu.org GNU | Homepage of the GNU project]

Local document:
- automatic label: intro
- explicit label: LCG Introduction
Local section:
- same document: Anchors
- other document: usage#run
- explicit label: Using links in documents
- description: Links
External links:
- GNU

Automatic Links

External links beginning with URL scheme, such as 'http://', are recognized automatically, so the square brackets are not necessary, unless you want to give the link a more descriptive name. Also e-mail addresses become links automatically.

See GNU project homepage at http://www.gnu.org (contact bill@microsoft.com for
more information).

See GNU project homepage at http://www.gnu.org (contact bill@microsoft.com for more information).

Images

Images are a special kind of Links. Any link pointing to an image will automatically display the target image in-line. Images are recognized by filename extension. JPEG, PNG and GIF images are currently supported.

Example:

http://www.google.com/images/logo_sm.gif

If a link label is given, this label is used as the accessible ALT text for the image. Similarly, if link description is defined, it is also included in the ALT text (see the example below).

Example:

[http://www.gnu.org/graphics/heckert_gnu.small.png GNU logo | A handsome 
GNU Head with typical beard and smart-looking curled horns]

GNU logo: A handsome
GNU Head with typical beard and smart-looking curled horns

Images can be also aligned to the left or right side of the text which follows them. Simply use a left or right angle bracket (less than or greater than sign) preceding the image name inside square brackets. The OSI logo floating on the left side of this paragraph was written like this:

[<http://www.opensource.org/trademarks/opensource/web/opensource-55x48.jpg]
Images can be also aligned ...

Images can be styled through external style sheets. In HTML output, each image automatically has the `class' attribute set according to the name of the image without file type extension. For example the image `http://www.google.com/images/logo_sm.gif' will have class `logo_sm'.

The image size may be specified explicitly using a colon and width x height in pixels at the end of the image filename:

[http://www.opensource.org/trademarks/opensource/web/opensource-55x48.jpg:27x24]

Image Links

Image links are a combination of image and link, presented as an inline image which acts as a link (can be clicked to get to the link target). They are created simply by using an image target (document-local resource filename or URL) in place of the link label. Textual link label (used for image accessible ALT text) and description (used for link tooltip) may follow in the usual form.

[http://www.google.com http://www.google.com/accounts/google_white.gif]
[http://www.opensource.org http://www.opensource.org/trademarks/open_source_button.png
OSI logo | Open Source Initiative]

Image links can be aligned using < and > similarly as ordinary images and styled (see above).

Audio

Links to audio recordings in MP3 format will appear as ordinary links in HTML, but these links will act as a remote control of the audio player displayed at the bottom right corner of the browser window. Single player is used for all recordings present on the page, so only one recording will be played at a time.

Full keyboard accessibility is also implemented. The following keyboard commands are available when the audio file link has keyboard focus:

Space — Start/stop playback
Arrow left — Fast forward
Arrow right — Rewind
Arrow up — Increase volume
Arrow down — Decrease volume

Since the technical requirements (see below) can not be easily enforced for distribution of this documentation, the examples don't include a player demo, but a simple link like this should work:

If you are interested, [recording.mp3 listen to the recording].

If it doesn't, check the requirements below.

Note: The player is currently not used for external links. Only local files will work.

Technical Requirements

User side requirements: A JavaScript enabled browser with Adobe Flash support is required on the user side to use the embedded media player. If not, the link will simply download the file.

Server side requirements: LCG must be configured properly to be able to embed the media player. This means JW Media Player and SWF Object must be available in the resource path. LCG will complain to the error output with more details.

Video

Video can be embedded into the webpage either locally as a file in the FLV format or as a link to the YouTube or Vimeo services. In either case, the user is presented with an embedded player, in which it is possible to directly play the video.

Local FLV Video Files

Links to video files in FLV format will be automatically represented by an embedded multimedia player. Most video formats can be converted to FLV — find out more about FLV conversion tools.

It is possible to control the size of the player in the same way as the size of images (colon and width x height after the filename).

If an image is used in place of link label, this image will be used as the video preview (the player will display the image until the user starts playback).

Note: Embedding currently doesn't work for external links. Only local videos may be embedded this way, but see below how to embed videos from public video services, such as YouTube.

Note: The same technical requirements as for audio embedding apply here.

Since the technical requirements can not be easily enforced for distribution of this documentation, the examples don't include a player demo. The following example should work, however, when the requirements are fulfilled:

[video.flv:400x300 preview.jpg]

Embedded Video from YouTube or Vimeo

A link to a video on YouTube or Vimeo will be in HTML rendered as an embedded video player. Thus you don't need to use any special code to embed these videos. Just the URI is enough.

http://www.youtube.com/watch?v=aKULi72yUko

If the link is specified in square brackets, it is also possible to specify the explicit video size in the same way as for images (colon and width x height after the filename).

Youtube video with specified size 400x250:

[http://www.youtube.com/watch?v=FdRklzmfzRM&aaa=1:400x250]

Vimeo links work in the same way:

[http://www.vimeo.com/8719387]

Youtube video with specified size 400x250:

Vimeo links work in the same way:

Note: This way of embedding has the advantage of no server side technical requirements. Client side requirements are the same as for other types of multimedia embedding (JavaScript enabled browser with Adobe Flash support).

Vertical Space

Explicit vertical space may be added using @vspace mark with the required space given in millimeters:

@vspace 20mm

This mark should be used only in places where explicit vertical space is needed. In many cases better means such as higher level elements, alignment or style sheets can be used.

Page Numbers

You can include page numbers and total number of pages in document headers and footers by using the marks @PAGE@ and @PAGES@. Note this works only in document headers and footers and only those backends where actual document pages are created (e.g. in PDF, but not in HTML).

Other Features

Escaping

You can avoid the special meaning of all the constructs described in this document by prefixing them with a backslash.

Example:

Slashes are used for /emphasizing/, however sometimes you want them \/like
here\/.  Double backslash must be used to force the \\/backslash/ itself in
front of a markup (anywhere else in the text, backslashes can be used freely).
Other backslash combination examples: \*one* \\*two* \\\*three* \\\\*four*
\\\\\*five*.

This will be presented as:

Slashes are used for emphasizing, however sometimes you want them /like here/. Double backslash must be used to force the \backslash itself in front of a markup (anywhere else in the text, backslashes can be used freely). Other backslash combination examples: *one* \two \*three* \\four \\*five*.

Explicit Line Break

Two slashes force a line break:

This sentence will break//in the middle.

This sentence will break
in the middle.

Horizontal Lines

Horizontal line can be made with 4 dashes on a separate line surrounded by blank lines.

Example:

Above

----

Below

This will be presented as:

Above

Below

Page Headers and Footers

You can set document headers and footers by declaring corresponding parameters:

@parameter header TEXT: Text to be put into the header of every page.
@parameter first_page_header TEXT: Header to be used on the first page of the document. If this parameter is not present, the header is the same as on other pages.
@parameter footer TEXT: Text to be put into the footer of every page.
@parameter background TEXT: Text to be put on the background of every page.

If the text is longer or more complicated, you can use the multiline form of parameter definition, e.g.:

@parameter footer
@center
@PAGE@/@PAGES@
@end footer

Note that page headers and footers may make sense only in some document formats and may be supported only by some backends while being ignored by other backends.

Presentation Parameters

It is possible to set some presentation parameters using @parameter mark:

@parameter font_size NUMBER: Changing default font size by multiplying it by NUMBER.
@parameter font_name NAME: Name of the default font of the document, e.g. DejaVu or Bitstream Vera. Whether the given font can be actually used in the document depends on the system installation. If the given font cannot be found, another font is used.
@parameter font_family NAME: Default font family of the document, NAME can be one of SERIF, SANS_SERIF, FIXED_WIDTH.
@parameter heading_font_family NAME: The same as font_family except that it applies only to section headings.
@parameter noindent ONE_OR_ZERO: If set to 1, don't indent first lines of paragraphs. If set to 0, indent them.
@parameter line_spacing NUMBER: Line spacing is set to NUMBER times the size of the current font.

Note that not all presentation parameters make sense in all backends or are supported by all of them, the may be ignored.

Variables

You can define a named piece of a structured text (variable) for later (typically repeated) use:

@define pi 3.14
@define repeated_text
One of the most famous mathematical constants is π.
Its value is $pi.
@end repeated_text

$repeated_text

I repeat: $repeated_text

@define pi 3.14159
Let's be more exact now:
$repeated_text

This will be presented as:

One of the most famous mathematical constants is π. Its value is 3.14.

I repeat:

One of the most famous mathematical constants is π. Its value is 3.14.

Let's be more exact now:

One of the most famous mathematical constants is π. Its value is 3.14159.

Variable names (e.g. pi or repeated_text) may consist only of lower-case English letters and underscores. The replacement text is a standard structured text. Note that in the multi-line version of a variable definition the text is interpreted as a block while in the single-line version the text can be embedded in a paragraph. A variable definition applies from its first occurrence, until it possibly gets redefined by another definition of a variable of the same name.

Comments

You can comment out any text with '# ' at the beginning of a line. This will make the text invisible on output media (e.g. by making it an HTML comment in the HTML output):

 The first line.
 # These lines have been 
 # commented out.
 The last line.

This will be presented as:

The first line. The last line.