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

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 must 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: Introduction
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

Audio .mp3 files can be included in the document in a similar way to images.

In HTML output, the link to mp3 file will be rendered as a play button controlling a tiny shared Flash media player, which appears in the bottom right corner of the webpage.

 * play button with optional button label: [test1.mp3 Play test sound]

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

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. Each item must be indented by at least one space character.
   2. Longer item texts can be split over multiple lines, provided
      that they are indented properly.
   3. 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).

   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. Each item must be indented by at least one space character.
2. Longer item texts can be split over multiple lines, provided that they are indented properly.
3. 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).
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 pipe characters are used to separate the cells. The line must also begin and end with a pipe character.

Example:

|        | Dick   | Jane |
| height | 72"    | 65"  |
| weight | 130lbs | 150lbs |

	Dick	Jane
height	72"	65"
weight	130lbs	150lbs

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: Introduction
- explicit label: LCG Introduction
Local section:
- same document: Anchors
- other document: Running lcgmake
- 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 be used as the accessible ALT text. Link description is used as image accessible description.

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

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'.

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).

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

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.

Deprecated features

The following features remain for backwards compatibility, but should not be used in new documents, since they may be removed in future LCG versions.

Non-breakable Space

A tilde character (=~=) is interpreted as a non-breakable space, but is now deprecated in favor of the Unicode character for non-breakable space (U+00A0). Please avoid using tildes since they may not be recognized in future.

Long Dash

Double dash (two minus signs) produce a long dash on the output, but is now deprecated in favor of the Unicode character "EM DASH" (U+00A0). Please avoid using double dashes since they may not be recognized in future.

Quotations

Quotations begin with two reverse apostrophes and end with two single apostrophes. They are supposed to be replaced by relevant national quotation characters on the output, but are now deprecated in favor of language dependent Unicode characters for quotes. Please avoid using quotations since they may not be recognized in future.