AIDAMANMARKUP(1)

NAME

DESCRIPTION
The Aida Markup Language is designed to provide a common base of tags in order to create structured text. This is useful to generate and maintain documentations, help files, etc, which must be distributed on different supports (Web pages, PDF documents, Wiki pages, etc.). The user writes his/her files using the common Aida Markup Language and converts them to some target format with the 'aida' command. This markup language is dynamic: the ''aida'' command embeds a Tcl interpreter and any Tcl code may be evaluated within a document. It is thus possible to generate contents on the fly and perform any scriptable action.

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 'NumberSections' 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 itself can contain `((include' or `((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 which splitting level has been selected.

Since version 1.3 of aida, the string following the ((input and ((include tags is parsed before being processed by aida. This means in particular that it is possible to make use of the evaluation tags ((e e)) and have the path of the file to include be specified programmatically. For instance, assume there exists Tcl variables named this:
        ((input ((e file join $dir $filename e))

In this example, the instruction between the evaluation tags will be parsed and substituted by the Tcl interpreter in order to build the path of a file to include.

  Lists
There 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 of an ordered or unordered list must be 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.

The basic list attributes are similar to those found in the Html language:
'start'
it concerns ordered lists and indicates the first value of the numbering

'type'
it concerns both ordered and unordered lists.
•   In the case of an unordered list, it specifies the kind of symbol to use at the beginning of a list item. The possible values are: 'none',
•   In the case of an ordered list, it specifies the kind of numbering at the beginning of a list item (possible values: "1" for arabic numbers, "A" for uppercase letters, "a" for lowercase letters, "I" for uppercase roman numbers, "i" for lowercase roman numbers).

Some targets support other attributes.

For instance, with the 'html' target, one can specify any of the attributes supported by the Html `<'OL`>', `<'UL`>' or `<'DL`>' tags.

Conversely, not all targets support the attributes above.

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

Note that tables can not be nested.

The basic table attributes are:
'border'
numeric value indicating the width of the border (0 means no border)

'align'
alignment of the table. Possible values: 'center', 'left' or

'format'
alignment of the columns. The value is a Latex-like specification as with the ` abular` environment in LaTeX. For instance: `format=cclr`. The vertical bar is also accepted: for instance `format=r|c|l`.

Some targets support other attributes.

For instance, with the 'html' target, one can specify any of the attributes supported by the Html `<'TABLE`>' tag.

Conversely, not all targets support the attributes above: it is always licit to specify these attributes but not all targets are able to render them.

  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 or the table tags.

The basic image attributes are:
'height'
numeric value indicating the height of the image.

'width'
numeric value indicating the width of the image.

'align'
alignment of the table. Possible values: 'center', 'left' or

'alt'
a string argument to provide a caption for the image.

Some targets support other attributes.

For instance, with the 'html' target, one can specify any of the attributes supported by the Html `<'IMG`>' tag.

With the 'latex' target, one can specify a 'clip' attribute indicating if the image should be clipped to the specified dimensions.

Conversely, not all targets support the attributes above.

Here are some examples:
        ((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 with the `((v v))` tags. It is similar to the `X format.

Finally, there is a stronger pair of tags `((q q))' designed to strictly quote a piece of text: it just copies the enclosed text as is, with no parsing and no character mapping.

Here is an example where the `((q q))' tags can be useful. Suppose you want to insert some LaTeX code in your Aida source file to provoke a line feed (this is obtained with the LaTeX macro `wpage'). Since this macro would not make sense with another target than the 'latex' target, you need to put this in an `((if' block:
        ((if $aida_target eq "latex"
        ((q wpage q))
        if))

Here the `((q q))' tags ensure that the macro will be copied as is. Otherwise, the characters mapping mechanism would convert the initial backslash and the output file would contain something like ` extbackslash{}newpage'. [1]

  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 may contain a Tcl proc which generates an Aida table (i-e a table in the Aida markup language): Aida will first execute the proc, then the table produced by this proc will be processed by the parser to convert it into the target format.

Tcl code can be stored in a separate file. In order to source such a file, one can use the '-prefix' option on the command line or declare it with the ':Source:' header parameter at the beginning of the Aida input file. Such a file may contain any Tcl code, in particular, the definition of Tcl procs invoked later in the document with `((e e))' tags.

The Tcl files specified with the '-prefix' option or with the not in the encoding specified by a '-from' option on the command line. The '-from' option lets you specify the encoding of the Aida input files, not the encoding of Tcl source code files. The system encoding is the encoding used by default on your system: you can determine it with the following command:
        aida info sysenc

To learn more about the Tcl language, see the Tcl home page <http://sourceforge.net/projects/tcl> at SourceForge or the Tcl Developer Xchange <http://www.tcl.tk/>

  Conditional blocks
Some portions of an Aida file can be made optional using a conditional block. The syntax is:
    ((if condition
        block if condition true
    ((else
        block if condition false
    if))

The `((else' part of the block is optional, so the conditional block could be just:
    ((if condition
        block if 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 like this `!!'. Such a comment is not parsed by the Aida parser but is converted into a comment in the target format.

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

LINKS
The official site of Aida is at http:/sourceforge.net/projects/aidadoc The complete documentation can be found at http://aidadoc.sourceforge.net There is an issue tracker and a mailing list.

AUTHOR

Copyright (c) 2010-2016, Bernard Desgraupes <bdesgraupes@users.sourceforge.net>, All rights reserved.

LICENSE
The Aida project is distributed under a BSD License: see the Open Source Initiative site. <http://www.opensource.org/licenses/bsd-license>

SEE ALSO
aida(1)