AidaHelp_6

Top | Prev | Next

The Aida markup language

This section contains information about the tags defined by the Aida markup
language. They are grouped in the following sections by functionality.

One can get a quick reference about all the existing tags with the following
command:

    aida help syntax

The following tags must be at the beginning of a line:

    ((hr)) ((include ((index)) ((input ((nl)) ((toc))
    ((table table)) ((tr ((|  |))

The following tags can be indented:

    ((dl ((ol ((ul ((li ((lt
    ol)) ul)) dl))
    ((s1 ((s2 ((s3 ((s4 ((s5 ((s6

Style

The following pairs of tags modify the style of the enclosed text:

`((i i))`	italic
`((b b))`	bold
`((u u))`	underline
`((y y))`	monospaced (typewriter font)

Sections

There are six levels of sections. The title of the section must be enclosed in
the following pairs of tags:

`((s1 s1))`	level 1
`((s2 s2))`	level 2
`((s3 s3))`	level 3
`((s4 s4))`	level 4
`((s5 s5))`	level 5
`((s6 s6))`	level 6

Level 1 is the topmost level.
Depending on the target, these sections may or may not be numbered. This
is usually controlled with the SectionNumbers and the SectionDepth header
parameters.

One can force a line feed with the
((nl)) tag.

The ((hr)) tag inserts a horizontal rule.

Structures

The ((toc)) tag tells Aida to build a table of contents and insert
it at the location of this tag. This table of contents lists all the
sections of the document down to a certain level which can be controlled with
the TocDepth header parameter.

Similarly the ((index)) tag tells Aida to build an index and insert
it at the location of this tag. This is the list of all the terms which
have been marked with the ((x x)) pair of tags.

Includes

The Aida input can be organized as a set of several files which are
assembled together by a master file using either the ((include or
the ((input tags. These tags must be at the beginning of a line and
are followed by the name of the file. Included files can be nested: an
included file can contain itself ((include or
the ((input tags.

The included file can be designated either by an absolute or a
relative path. When the file to include is designated by a relative path,
this path is always relative to the calling file, i-e to the directory
containing the file with the ((input or ((include tags.
For instance, suppose we have the following architecture:

    main.aida
    --- Inputs
       |--- sub.aida
       |--- SubInputs1
       |   |--- subsub1.aida
       |--- SubInputs2
       |   |--- subsub2.aida

In order to include the file subsub2.aida from the file main.aida, the
instruction is:

    ((input Inputs/SubInputs2/subsub2.aida

In order to include the same file from the file sub.aida, the
instruction is:

    ((input SubInputs2/subsub2.aida

In order to include the same file from the file subsub1.aida, the
instruction is:

    ((input ../SubInputs2/subsub2.aida

The difference between the ((include and the ((input
tags is meaningful only with the aida split command. When this
command is invoked with a splitting level set to 0, splitting occurs at
each ((input tag and never at an ((include tag.

There is a ((split)) tag which forces a split with the aida split
command no matter what splitting level has been selected.

Lists

The are three kinds of lists: unordered lists, ordered lists and
description lists. They must be enclosed respectively in the following
pairs of tags:

`((ul ul))`	beginning/end of unordered list
`((ol ol))`	beginning/end of ordered list
`((dl dl))`	beginning/end of description list

Both tags (opening or closing) can be indented relatively to the
beginning of the line.

The list items are enclosed in ((li li)) tags.
The structure of an unordered list, for instance, is:

    ((ul attributes
        ((li item 1... li))
        ((li item 2... li))
        ...
    ul))

Note that the closing list item tag li)) is mandatory.

The attributes are optional. They must all be on the same line as the
opening list tag and are made of pairs of the form key=value.

The structure of an ordered list is exactly the same as for an unordered
list.

The structure of a description list is slightly different and makes
use of ((lt lt)) tags:

    ((dl
        ((lt term 1
            description of term 1
        lt))
        ((lt term 2
            description of term 2
        lt))
        ...
    dl))

Each term must be on the same line as the opening ((lt tag and its
description spans the following lines up to the closing lt)) tag.

Lists of any kind can be nested within one another.

Tables

The syntax of a table is

    ((table attributes
    ((tr row 1... tr))
    ((tr row 2... tr))
    table))

The
((table table)) tags indicate the beginning and the end of table
respectively. The rows are delimited by the
((tr tr)) pair of tags.

The cells within a row are simply separated by a tabulation.

The opening ((table tag may be followed, on the same line, by a set
of attributes. They obey the same convention as for the list tags above.

Images

Images can be inserted using the ((img img)) pair of tags. There
are two possible forms:

    ((img image img))

or

    ((img attributes
    image img))

In the second form, the opening ((img tag is followed by a set of
attributes using the same syntax as for the list of the table tags.

For example:

    ((img height=250 alt='some text'
      foobar.png img))

    ((img foobar.png img))

Hyperlinks

There two kinds of links: external links pointing to an external resource
and internal links which are references to another part of the document.

The external links are created using the ((lk tag. The syntax is:

    ((lk [url] text lk))

The URL pointed to by the link is enclosed between brackets and followed by
the text to be displayed as a hyperlink. How these links are rendered depends on
the target format. Not all targets offer a real navigation system.

An internal link points to a location marked by a label. A label is
anchored in the document using the ((a a)) pair of tags. Labels
must be unique. Then any reference to a label is created using the ((rf
tag. Its syntax is:

    ((rf [label] text rf))

For example:

    ((lk [http://www.free-soft.org/] Free Software Foundation lk))
    ((a plug a))
    ((rf [plug] see the Plugins section rf))

Index

In order to create an index entry for a term, enclose it
in a ((x x)) pair of tags.

The index itself can be generated and inserted somewhere in the document using the ((index)) tag.

Evaluation

Verbatim text

Verbatim text is a portion of text which is not parsed by the Aida parser
and which is sent 'as is' to the target. Each target has a callback which is
invoked to handle this piece of text. Usually the target format has
its own way of rendering verbatim text.

A verbatim block is created with the ((| and |)) tags like
this:

((|

    text of the block

|))

These tags must be at the beginning of a line.

It is also possible to insert verbatim text inside a line or a paragraph.
Two pairs of tags are available for inline verbatim: ((v v)) or
((q q)). They are synonyms.

Tcl code

The aida command contains a Tcl interpreter. Under the hood, this
interpreter is used to process the Tcl code which defines, via callbacks,
the behavior of each target.

Of interest to the user is the fact that this Tcl interpreter is also able
to evaluate Tcl code inserted in an Aida file. A block of Tcl code must be
enclosed between an ((e e)) pair of tags. The contents of this
pair of tags can be any valid Tcl code, a single instruction or an entire
script.

The same interpreter is used during all the parsing so it is possible, for
instance, to declare variables at some point and use them later.

The result of the execution of an ((e e)) block is passed to the
Aida parser. So, an evaluation block can be used to generate dynamical
contents in an Aida file. For instance, the evaluation block could contain
a Tcl proc which generates an Aida table (i-e a table in the Aida markup
language) and then this table would be
processed by the Aida parser to convert it to the target format.

Tcl code can also be stored in a separate file and sourced at the
beginning of an Aida input file using the :Source: header parameter. Such a
file could contain the definition of Tcl procs invoked later in the
document using the ((e e)) tags.

To learn more about the Tcl language, see the
Tcl home page
at SourceForge or the
Tcl Developer Xchange.

Conditional blocks

Some portions of an Aida file can be made optional using a conditional
block. The syntax is:

((if condition
    block is condition true
((else
    block is condition false
if))

The ((else part of the block is optional, so the conditional block
could be just:

((if condition
    block is condition true
if))

The condition following the opening ((if tag can be any valid Tcl
code which can be interpreted as true or false by the Tcl interpreter
embedded in the Aida parser.

For instance:

((if $aida_target eq html
   some text for the html target only
if))

Comments

There are two kinds of comments: soft and strong.

A soft comment is a line starting with a pair of exclamation marks !!.
Such a comment is not parsed by the Aida parser but is converted to a
comment in the target format.

A strong comment is a line starting with triple exclamation marks !!!.
Such a comment is ignored by the Aida parser and stripped from the output.