# -*- coding: utf-8; mode: structured-text -*-
# Copyright (C) 2005-2012 OUI Technology Ltd.
# Copyright (C) 2019, 2021 Tomáš Cerha <t.cerha@gmail.com>
# This is part of the LCG Documentation.
# See the file index.en.txt for copying conditions.
# Note: The examples (surronded by ---- lines) are displayed in a fixed
# width font with wrapping disabled.  Please, wrap all examples to 65
# characters to prevent this document taking too much horizontal space.

@parameter footer
@center
\- @PAGE@ -
@end footer

= Structured Text Formatting Manual =

This document describes the Structured Text format used by the
[http://www.freebsoft.org/lcg LCG].

Table of Contents: @TOC(1)@


== Introduction == intro

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 == overview

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
[#complete-manual].

Table of Contents: @TOC@


=== 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: [#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

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]
 * simple image link: [http://www.opensource.org
   http://www.opensource.org/trademarks/open_source_button.png]
 * image link with label and description:
   [http://www.opensource.org
   http://www.opensource.org/trademarks/open_source_button.png
   OSI | Open Source Initiative]
-----

Resulting images:

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

See [#images] and [#image-links] for more details.


=== Audio and Video ===

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.  Full keyboard accessibility is
also implemented.  See [#audio] for more information.

Similarly as images, also video files in OGV, MP4, WEBM a 3GP formats and links
to YouTube and Vimeo services are automatically recognized and displayed as an
embedded player.  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 == complete-manual
 
This section describes all the supported constructs and their syntax in depth.
See the [#overview] for a simplified description.

Table of Contents: @TOC@

=== 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 [#overview], 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 ==== 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 ==== toc

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 [#complete-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

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

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


==== Definition Lists ==== 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

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 ==== 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 |
------

| <>     |          |          | >      |
| <l10>  | <r>      | <r10>    | <l>    |
|        | *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.
-----

@left
This text will be placed on the left.

@right
This text will be placed on the right.


=== Inline Constructs === 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

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-links
  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 [#images
  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: [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]


==== Automatic Links ==== 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

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

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]
------

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

[<http://www.opensource.org/trademarks/open_source_button.png]
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/open_source_button.png]
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.gnu.org/graphics/heckert_gnu.small.png:24x24]
------

[http://www.gnu.org/graphics/heckert_gnu.small.png:24x24]

==== Image Links ==== 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]
------

[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 ==== 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.


==== Video ==== video

Video can be embedded into the webpage either locally as a file in the OGV,
MP4, WEBM a 3GP formats 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.

For local files 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 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.


===== 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.  With square brackets you may set title,
description, cover image or dimensions similarly as with ordinary links or
images.

-----
https://www.youtube.com/watch?v=BMUiFMZr7vk
-----

https://www.youtube.com/watch?v=BMUiFMZr7vk

Vimeo links work in the same way:

-----
http://www.vimeo.com/8719387
-----

http://www.vimeo.com/8719387

Explicit video size may be set in the same way as for images (width x
height in pixels after a colon).

-----
[https://www.youtube.com/watch?v=Wl98eZpkp-c:400x300]
-----

[https://www.youtube.com/watch?v=Wl98eZpkp-c:400x300]

/Note:/ This way of embedding has the advantage of no server side technical
requirements.


==== Interactive exercises ====

===== MultipleChoiceQuestions =====

<exercise type="MultipleChoiceQuestions">
Screen reader is:
- a person.
- a device.
+ a program.

GNU/Linux is:
- a word processor
+ an operating system
- a computer manufacturer
</exercise>

-----
<exercise type="MultipleChoiceQuestions">
Screen reader is:
- a person.
- a device.
+ a program.

GNU/Linux is:
- a word processor
+ an operating system
- a computer manufacturer
</exercise>
-----

===== Selections =====

-----
<exercise type="Selections">
+ India is located in Asia.
- China is located in Africa.

+ Australia is the smallest continent.
- Australia is the largest continent.
</exercise>
-----

<exercise type="Selections">
+ India is located in Asia.
- China is located in Africa.

+ Australia is the smallest continent.
- Australia is the largest continent.
</exercise>


===== TrueFalseStatements =====

-----
<exercise type="TrueFalseStatements">
The Microsoft Windows operating system never crashes. [F]

The largest tropical rainforest in the world is in Brazil. [T]
</exercise>
-----

<exercise type="TrueFalseStatements">
The Microsoft Windows operating system never crashes. [F]

The largest tropical rainforest in the world is in Brazil. [T]
</exercise>


===== GapFilling =====

-----
<exercise type="GapFilling">
If you want to send money to somebody, you can ____ a transfer.
- do
+ make
- have

To change money between two currencies you need to know the ____ rate.
- success
- interest
+ exchange
</exercise>
-----

<exercise type="GapFilling">
If you want to send money to somebody, you can ____ a transfer.
- do
+ make
- have

To change money between two currencies you need to know the ____ rate.
- success
- interest
+ exchange
</exercise>


===== HiddenAnswers =====

-----
<exercise type="HiddenAnswers">
What is the name of the highest mountain in the world?
Mount Everest.

What is its height?
8,848m
</exercise>
-----

<exercise type="HiddenAnswers">
What is the name of the highest mountain in the world?
Mount Everest.

What is its height?
8,848m
</exercise>


===== WrittenAnswers =====

-----
<exercise type="WrittenAnswers">
What is the name of the largest continent?
[Asia]

Use the correct form of the verb "to be":
Children [are] our future.
</exercise>
-----

<exercise type="WrittenAnswers">
What is the name of the largest continent?
[Asia]

Use the correct form of the verb "to be":
Children [are] our future.
</exercise>


===== Cloze =====

-----
<exercise type="Cloze">
Commercial banks and savings banks receive and hold deposits
[in] current accounts, savings accounts and deposit accounts,
make payments [for] their customers, lend money, [and] offer
investment advice, foreign exchange facilities, and so on.
</exercise>
-----

<exercise type="Cloze">
Commercial banks and savings banks receive and hold deposits
[in] current accounts, savings accounts and deposit accounts,
make payments [for] their customers, lend money, [and] offer
investment advice, foreign exchange facilities, and so on.
</exercise>


===== Numbered Cloze =====

-----
<exercise type="NumberedCloze">
[London] is the capital of the United Kingdom.

The city is split by the River [Thames] into North and South.
</exercise>
-----

<exercise type="NumberedCloze">
[London] is the capital of the United Kingdom.

The city is split by the River [Thames] into North and South.
</exercise>



==== 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:

@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

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.
# These lines have been 
# commented out
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.
