Table of contents

Introduction

The Aida project is two-fold: This is useful to create and maintain documentations, help files, etc, which must be distributed on different supports (Web pages, PDF documents, Wiki pages,...). The user writes his/her files using the common Aida Markup Language and converts them to the target format with the aida command.
The system is fast, flexible and extensible. The core command aida is a strict parser (written using Bison and Flex) which analyses files written in the Aida Markup Language and invokes callbacks in order to convert them to the target format.
The aida command embeds a
Tcl language interpreter and all the callbacks are written in Tcl: the Tcl scripts constitute Aida's library. This architecture makes it easy to extend the library and define new target formats. It is also very powerful because any Tcl code can be sourced and evaluated within the Aida files and thus one can create dynamic contents, generated on the fly.
Furthermore, the Aida files are highly parameterizable via a header and the entire system is configureable both at the admin's and at the user's level.

Quick start

Here is a quick example to give a more precise idea of what the Aida mechanism is about.
Using your favorite text editor, create a new file named example.aida with a following contents:
    :DestDir:           aida_output/
    :Title:             Quick Example
    
    ((s1 Introduction s1))
    
    The ((b Aida b)) project is two-fold: 
    ((ol
    ((li it defines a simple common ((i markup language i)). li))
    ((li it provides a ((i compiler i)) to convert the markup into target 
    formats. li))
    ol))
    
    ((s1 Table s1))
    
    ((table border=1 align=center
    ((tr Number	Element	Symbol tr))
    ((tr 1	hydrogen	H tr))
    ((tr 2	helium	He tr))
    ((tr 3	lithium	Li tr))
    ((tr 4	beryllium	Be tr))
    table))
    
    Updated on ((e clock format [clock seconds] -format "%Y-%m-%d" e)).

This file is an input file written in the aida syntax. It can now be converted into various formats such as Html, Latex, Text, Mediawiki (the editing format used by Wikipedia), etc. For instance, the following command
    aida convert -target text example.aida
will produce an output like this:
1 Introduction

The Aida project is two-fold: 
	1. it defines a simple common markup language. 

	2. it provides a compiler to convert the markup into target formats. 
    

2 Table

						_______________________________                         
						| Number |  Element  | Symbol |                         
						_______________________________                         
						|   1    | hydrogen  |   H    |                         
						_______________________________                         
						|   2    |  helium   |   He   |                         
						_______________________________                         
						|   3    |  lithium  |   Li   |                         
						_______________________________                         
						|   4    | beryllium |   Be   |                         
						_______________________________                         

Updated on 2011-02-08.
Now, let us change the target to Html format like this:
    aida convert -target html example.aida
This will produce the same contents in the Html language, ready for publication on the Web :


Quick Example



Introduction

The Aida project is two-fold:
  1. it defines a simple common markup language.
  2. it provides a compiler to convert the markup into target formats.

Table

NumberElementSymbol
1hydrogenH
2heliumHe
3lithiumLi
4berylliumBe
Updated on 2011-02-08.

Similarly, the command
    aida convert -target latex example.aida
would generate output in the Latex format, and the command
    aida convert -target mediawiki example.aida
would generate output in the Mediawiki format, ready to be published in a Wikipedia article.
The previous examples demonstrate several characteristics of the markup language. It makes use of pairs of tags such as ((i i)), ((b b)) which enclose a portion of the text. In the example, the ((i tag switches the text style to italics, the ((ol tag starts an ordered list, the ((li tags start list items, etc.
The first two lines are header lines: they define settings concerning the conversion process. For instance, the following header line
    :DestDir:           aida_output/
specifies the name of an output folder. As a consequence, the command
    aida convert -target latex -output myfile.html example.aida
writes the output in a file named myfile.html located in a subdirectory named aida_output inside the current directory.
The last line of the example
    Updated on ((e clock format [clock seconds] -format "%Y-%m-%d" e)).
shows how Aida can execute instructions while processing its input. The instruction enclosed between the pair of tags ((e e)) is written in the
Tcl language and returns the date of the day. The text delimited by the ((e e)) tags is replaced by the actual date in the output.
The aida compiler embeds a Tcl interpreter making it possible to execute any valid Tcl code in a pair of tags ((e e)).

Structure of an Aida file

The structure of an Aida file is very simple. It usually starts with a header followed by the body of the text. The header contains instructions like this:
:DestDir:           aida_output/
:Title:             Quick Example

The precise syntax of the header instructions is explained in the next section. The header can be empty: Aida defines defaults for all the header parameters.
A header instruction does not have necessarily to be written at the beginning of the file. This is just easier to read.
The header instructions are processed when they are met by the Aida parser. In some circumstances, one might want to issue a header instruction later in the file, for instance in order to modify a setting while the file is being processed.
The rest of an Aida file is text marked with Aida tags. The syntax of the Aida markup language is described in a section below.
It is possible to split the input into several smaller files which can be included from a master file (or from any other input file) using either the ((input or the ((include tags.

The Aida header

An Aida file can contain header instructions in order to declare or to modify some basic settings. Header instructions are usually written at the beginning of the file but there is no requirement for this: they are processed by the Aida parser as they are met.
The settings they define are of two kinds: global or target-specific. A target-specific header instruction is executed only when this target is selected by the aida convert or the aida split commands. A global instruction is executed no matter what format is targetted.
The syntax of a global instruction is:
:parameter:    value
It is a single line containing the name of the header parameter enclosed between colons, followed by spaces and a value for this parameter. For instance:
:Title:             AidaHelp
:DestDir:           ../../Output/Help
The header parameter must be at the beginning of the line.
The main parameters defined by Aida are explained below. The command
    aida help header
returns a list of these parameters.
It is also possible to define one's own parameters in order to control advanced settings. This will be explained later.
The syntax of a target specific instruction is:
:parameter:target:    value
This is very similar to the global instruction: only the name of a target is appended to the parameter and followed by a colon. For instance:
:DestDir:html:      ../../htdocs
:DestDir:trac:      ../../Output/Trac
When a target-specific parameter is found, it always has precedence over a global parameter of the same name.

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.

Syntax of the aida command

This section contains information about the usage of the aida shell command. In order to write an Aida file, all you need is a simple text editor. When your file is ready, you will certainly want to convert it to some target format: this is where the aida command comes in. It can be viewed as a compiler which is able to read and interpret your Aida file and call the appropriate drivers to perform the conversion. The aida command can also be used to get information about the system or to display help about the Aida syntax.

Syntax

The general syntax of the aida command is
    aida  [options]
Depending on the subcommand several options and additional arguments may have to be specified. They are documented in the following subsections. All the subcommands and options can be abbreviated as long as they remain unambiguous. For instance
    aida info version
can also be written as
    aida inf vers
or even the minimalist
    aida i ve

Global options

The global options are settings which apply to the aida command itself, no matter which subcommand is invoked. They mostly concern debugging and will be of interest only for developers. Here are the currently supported global options: There are also two standalone options:

Subcommands

The currently available subcommands are convert, help, info, split.

The convert subcommand

The syntax of the convert subcommand is:
    aida convert [options] [file]
The available options are:
-from
the input encoding.
-output
the name of the output file. See details below.
-prefix
a file containing Tcl code to evaluate before starting the conversion process.
-target
the name of the target format.
-to
the output encoding.
The last argument of the command line is the name of the Aida input file to convert. If it is not specified, Aida reads from the standard input (stdin).
Available targets can be obtained with the command aida info targets.
Available encodings can be obtained with the command aida info encodings.
If the -output option is omitted, the result of the aida convert command is written to the standard output (stdout). If this option is explicitely set to an empty string, Aida builds the name of the output file from the name of the input file by removing the extension and replacing it by an appropriate extension depending on the target. For instance, the following command:
    aida convert -targ latex -output "" foobar.aida
will write the output in a file named foobar.tex. On the contrary, the following command:
    aida convert -targ latex foobar.aida
would write the output directly to the terminal window or the standard output of the shell where the command is executed.

The help subcommand

The help subcommand is used to get help about the syntax of the subcommands or about the markup language itself. Its syntax is:
    aida help [subcommand|keyword]
This means that it can be used without any additional argument, or followed by the name of a subcommand, or by a keyword. The currently supported keywords are:
header
this prints information about the parameters of the header section of an Aida file.
syntax
this prints information about the usage of tags in an Aida input file.
Here are a few examples (try them!):
    aida help
    aida help convert
    aida help help
    aida help header
    aida help syntax

The info subcommand

The syntax of the info subcommand:
    aida info arg
The arg argument can be:
attributes
print the values of all the target specific tag attributes.
configuration
print the configuration files (config.tcl, default.tcl) known to Aida in the user and in the local domains. The returned list may be empty depending on the installation's settings.
encodings
print the list of all the encodings available for the -from and -to options.
from
print the default input encoding. This is the default value for the option -from. It can be set in configuration files.
library
print the path to the Aida Tcl library on the system.
path
print the list of directories visited by Aida when looking for a target implementation.
targets
print the list of available targets.
temp
print the location of the directory where aida writes temporary files.
to
print the default output encoding. This is the default value for the option -to. It can be set in configuration files.
variables
print the values of all the variables (global or target specific) known to aida's Tcl interpreter.
version
print the version number of the command.
In the case of the attributes, encodings, variables keywords, the -q option can be useful in order to get a less verbose output, or an output in a format easier to parse in a script. Here are a few examples (try them!):
    aida info library
    aida info version
    aida info encodings
    aida info from
    aida info variables
    aida info -q variables

The split subcommand

The syntax of the split subcommand is:
    aida split [options] [file]
The available options are:
-from
the input encoding.
-level
the level at which splitting occurs. See details below.
-output
a format string to build the name of the output files. See details below.
-prefix
a file containing Tcl code to evaluate before starting the conversion process.
-target
the name of the target format.
-to
the output encoding.
The last argument of the command line is the name of the Aida file to convert. If it is not specified, aida reads from the standard input (stdin).
Available targets can be obtained with the command aida info targets.
Available encodings can be obtained with the command aida info encodings.
The -level option is a number indicating the section level at which the splitting must be performed. For instance, if the value is 1, the Aida file is split each time a new section declared with the tag ((s1 is met. If the value is 2, the Aida file is split each time a new section declared with one of the tags ((s1 or ((s2 is met, etc. One can thus specify values from 1 to 6. The default value is 1.
One can also specify a value 0 for the -level option: in that case, splitting occurs when an ((input tag is met rather than a section tag. This is the difference between the ((input and the ((include tags: the ((include tag is not considered as a splitting point.
The ((split)) tag can also be used to force a split anywhere in an Aida file (no matter what the -level option is set to).
The -output option lets you specify a format string used by Aida to build the names of the split files. Its syntax is inspired by the formats used with the C function printf. When the aida split command is executed, the output files are numbered sequentially: the numbers are represented, in the format string, by symbols like %d. For instance, one can specify the -output option like this:
    -output "foobar_%d"
This would cause the split files to be named "foobar_1", "foobar_2", etc.
The format obeys the same rules as with the printf function. For instance, if the -output option is declared like this:
    -output "%02d_foobar"
the split files will be named "01_foobar", "02_foobar", etc.
One can also use a %x or a %o specifier for hexadecimal or octal numbering respectively.
If the -output option is not specified, Aida uses a default format string built by removing the extension of the input file, appending the format specifier _%d and the appropriate extension depending on the target.

Configuration of the Aida system

Configuration files

The configuration files are Tcl source files which are read by Aida during startup. They can contain any valid Tcl code. There are two configuration directories : Each directory can contain the following files:
When one of these files needs to be sourced, the site configuration directory (if any) is always visited before the user config directory, so that user settings can override site wide settings.
The exact order in which all the files are sourced is detailed in the Startup section below.
For the site-wide directory to be taken into account, one must define the AIDA_SITE_CONFIG environment variable. How to do this depends on the shell which is used to execute the command. For instance, in the case of the bash shell, one can invoke the aida command in one of the following ways:
    AIDA_SITE_CONFIG=/path/to/dir aida convert somefile.aida
or
    export AIDA_SITE_CONFIG=/path/to/dir 
    aida convert somefile.aida

The config.tcl files are designed to contain early configuration options. This is the proper location, for instance, to modify the aida_path variable or to define a default target. For instance, it might contain instructions like this:
    lappend aida_path [file normalize ~/library/AidaLocalLib]
    set aida_head(DefaultTarget)	"latex"

Environment variables

Aida supports environment variables which can be used to define default settings from the shell environment.
The AIDA_SITE_CONFIG environment variable defines the location of a system-wide (as opposed to user-defined) location for configuration files. It is explained in the Configuration of the Aida system section.
The AIDA_TARGET environment variable specifies the default target to use with the aida convert and the aida split commands. The value defined by this variable is overridden by the -target option (if any).
The AIDA_INPUT_ENCODING and AIDA_OUTPUT_ENCODING environment variables specify a default input and output encoding respectively. See the section Input and output encodings for more information about them. These variables are read early during startup and can be overridden by the -from or the -to options, or by a call to the aida::inputEncoding or aida::outputEncoding core commands.

The startup sequence

When the aida command is invoked, the following startup sequence is executed:
Here is the exact order in which files are sourced when converting an Aida file to a particular target, i-e when executing the aida convert or the aida split command:
  1. init.tcl
  2. config_dir/config.tcl
  3. ~/.aidarc/config.tcl
  4. aida_library/core.tcl
  5. aida_library/base/default.tcl
  6. aida_library/base/convert.tcl
  7. aida_library/<target>/default.tcl
  8. aida_library/<target>/convert.tcl
  9. config_dir/default.tcl
  10. ~/.aidarc/default.tcl
  11. config_dir/convert.tcl
  12. ~/.aidarc/convert.tcl
where config_dir designates the site-wide configuration directory (if any) and aida_library is the directory containing the Aida library (which can be obtained with the command aida info library).
When a command like aida help or aida info is executed, only the following files are sourced (since there is no target in that case):
  1. init.tcl
  2. config_dir/config.tcl
  3. ~/.aidarc/config.tcl
  4. aida_library/core.tcl
  5. aida_library/base/default.tcl
  6. config_dir/default.tcl
  7. ~/.aidarc/default.tcl

Input and output encodings

The input encoding is the encoding in which the Aida file is written. The output encoding is the encoding in which the aida convert and the aida split commands write their output.
In order to know the names of the available encodings, one can execute the following instruction:
    aida info encodings
The list of available encodings depends on your Tcl installation. Here is what a standard distribution usually provides:
    ascii        cp1255          iso8859-13
    big5         cp1256          iso8859-14
    cp437        cp1257          iso8859-15
    cp737        cp1258          iso8859-16
    cp775        dingbats        jis0201
    cp850        ebcdic          jis0208
    cp852        euc-cn          jis0212
    cp855        euc-jp          koi8-r
    cp857        euc-kr          koi8-u
    cp860        gb12345         ksc5601
    cp861        gb1988          macCentEuro
    cp862        gb2312          macCroatian
    cp863        gb2312-raw      macCyrillic
    cp864        identity        macDingbats
    cp865        iso2022         macGreek
    cp866        iso2022-jp      macIceland
    cp869        iso2022-kr      macJapan
    cp874        iso8859-1       macRoman
    cp932        iso8859-2       macRomania
    cp936        iso8859-3       macThai
    cp949        iso8859-4       macTurkish
    cp950        iso8859-5       macUkraine
    cp1250       iso8859-6       shiftjis
    cp1251       iso8859-7       symbol
    cp1252       iso8859-8       tis-620
    cp1253       iso8859-9       unicode
    cp1254       iso8859-10      utf-8

The UTF8 Unicode encoding form can be designated as utf-8 or utf8. The UTF16 encoding form can be designated as unicode, utf-16 or utf16.
These encodings are specified via the command line options -from and -to or using environment variables as explained below.

Default encodings

Aida has default values for the input and output encodings. These defaults can be obtained with the command aida info like this respectively:
    aida info from
    aida info to
The default encodings are used when the options -from or -to are not specified on the command line.

Setting encodings programmatically

The aida::inputEncoding and aida::outputEncoding commands are Tcl commands defined by Aida and understood by its Tcl interpreter. They allow to get or set the current encodings. See the section Aida core Tcl commands for more information about how these commands work.
These commands can be used in a configuration file in order to establish default values for the encodings. Not that once the aida command started parsing the input file, it is not possible to change the encodings anymore. This means, in particular, that these commands have no effect if they are used in a header parameter because when the parser reads the header instructions, it is already too late to change the encodings.
If no default value has been declared, Aida uses the default encoding for the system as returned by the Tcl command [encoding system].

Encoding environment variables

Aida supports two environment variables, named AIDA_INPUT_ENCODING and AIDA_OUTPUT_ENCODING, which provide another mean of setting the input and the output default encodings.
For instance, in the case of the bash shell, one can invoke the aida command like this:
    export AIDA_INPUT_ENCODING=cp1252
    export AIDA_OUTPUT_ENCODING=macRoman
    aida convert somefile.aida
or
    AIDA_INPUT_ENCODING=iso8859-1 aida convert somefile.aida

Extending Aida

This section contains information about

Aida's internal structure

The Aida system is essentially made of two components: The core component is just a driver for the library: it contains a parser for the Aida Markup Language and a Tcl interpreter to execute the code in the library. It is responsible for calling the right code at the appropriate moment. Technically, the parser is based on a strict LALR(1) grammar and is implemented with the help of the Bison and Flex programs.
The library is where the conversion procedures corresponding to the various tags of the Aida Markup Language are defined. Since it is written in Tcl, with some basic knowledge of this language, one can understand the code and modify it if necessary. Tcl is an easy to learn, yet extremely powerful, language.
The basic library files are located in the directory $aida_library/base. For instance:
    $aida_library/base/default.tcl
To know the location of this library, one can execute the command
    aida info library
The default location on a Unix system, as of version 1.0, is '/usr/local/share/aida/1.0'.
This location can be changed if necessary (see the variable aida_path below).

Library

Here is the current structure of the Aida library (as of version 1.0):
    --- library
       |--- base
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- callbacks.tcl
       |--- core.tcl
       |--- debug.tcl
       |--- html
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- hyperref
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- latex
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- man
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- markdown
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- mediawiki
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- pmwiki
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- template
       |   |--- convert_tmpl.tcl
       |   |--- default_tmpl.tcl
       |--- text
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- trac
       |   |--- convert.tcl
       |   |--- default.tcl
       |--- utils.tcl

Each target directory has two files :

Targets mechanism

The inner mechanism of Aida relies on callbacks which are invoked from the core at the appropriate moment and which take care of providing the output corresponding to the various tags of the Aida Markup Language. For instance, when the aida parser meets the ((table tag, it automatically invokes a Tcl proc named tableProc: this proc receives all the necessary elements, like attributes and list of rows, and then is responsible for building the table in the target format.
These callbacks are Tcl procs defined in a separate file for each target. This file is named convert.tcl and is located in a directory named like the target. For instance, the procs for the html target are stored in
    $aida_library/html/convert.tcl
The procs are defined in a namespace with the same name as the target. For instance, if the target is html, all the procs are defined in the html namespace, so the table proc is named html::tableProc.
All the procs have a default definition found in the base directory of the Aida library. There is an automatic fallback mechanism: if a target specific proc, like html::tableProc, is not provided for the html target, then the default definition is used instead.

Global variables

The Aida Tcl interpreter defines a few global variables which can be useful for a user in order to control or modify Aida's behavior in a custom script, or for a developer in the definition of a new target.
The following global variables are currently available:
aida_librarythe location of the library directory
aida_paththe list of all the directories visited to find targets
aida_verbositythe current level of verbosity
aida_versionthe current version of Aida
aida_cwdthe current working directory
aida_targetthe current target
aida_namethe name of the input file (if any)
aida_mappinga logical value to control chars mapping
aida_unwrapa logical value to control text wrapping
The variables aida_library, aida_verbosity, aida_mapping and aida_unwrap are linked variables. This means that any change made to them from the Tcl code modifies them accordingly in the C code.
Some of these variables are set by the core before the default.tcl files in the configuration directories are sourced, so their values can be overriden there.

Precedence

Parameters governing Aida's behavior can be set at different levels: This list indicates the order of precedence. A command line option has precedence over any settings made in the header of the input file. The latter have precedence over settings found in the configuration files, which in turn have precedence over settings made in the library source files.
Concerning library files, a target specific definition has precedence over a global one: if the target is html, a variable defined in $aida_lib/html/default.tcl overwrites a variable set in $aida_lib/base/default.tcl.
Among the configuration files, per-user settings have precedence over site-wide settings.
Here are some examples demonstrating how to set the PageWidth header parameter at different levels:

Writing dynamic contents

The pair of tags ((e e)) can evaluate any valid Tcl code during the conversion process. This is very useful for generating contents on the fly, i-e when a file is processed. The result of the Tcl code is inserted in the document in place of the ((e e)) tags and is passed to the Aida parser.
Combining this possibility with the :Source: or :TclCmd: header parameters, or with the -prefix command line option provides with a very flexible system to generate dynamic contents.
Let us start with a simple example. The following piece of text will display the name of the currently logged user:
    This is the session of user ((e exec whoami e)).
As a result, the converted file will display: This is the session of user bernardo. Indeed exec is a Tcl command used to execute a Unix command and whoami is the Unix command reporting the name of the user of the current session.
The same Tcl interpreter is used by Aida to evaluate any piece of code so one can, for instance, define a global variable somewhere and reuse it later. Let us see a simple example making use of the :TclCmd: header parameter. The next header instruction creates a global variable symphNum:
    :TclCmd:    set symphNum 5
Then the Aida document can use it like this:
    Beethoven's symphony #((e set symphNum e))
which will result in Beethoven's symphony #5.
The ((e e)) tags can contain several lines of Tcl instructions, i-e a complete Tcl script. They can also contain the name of a proc which has been previously defined. For instance, here is a proc, written in Tcl, detecting the presence of a Music directory in the user's home directory and counting the number of albums:
    proc countAlbums {} {
        set musicDir [file normalize ~/Music]
        if {[file exists $musicDir]} {
            set albums [glob -dir $musicDir -type d *]
            set num [llength $albums]
            return "contains $num albums"
        } else {
            return "is missing"
        } 
    }
The proc can be used like this:
    The Music dir ((e countAlbums e)).
which results in something like: The Music dir contains 4 albums. This will work only if the countAlbums proc is found by the Tcl interpreter. There are several methods to achieve this:
The solution of storing the proc in a separate file is the most convenient because it allows you to define an entire library of Tcl procs and maintain them in a single location. The same Tcl file could also be used in other Aida documents.
Here is a last example demonstrating the generation of more complex Aida code. The proc randomTable constructs a table with a specified number of rows and columns in which each cell contains a random number. Here is the proc (which uses the rand() function to generate the random numbers):
    proc randomTable {nrow ncol} {
        set result [list "((table border=1 align=center"]
        for {set i 0} {$i < $nrow} {incr i} {
            set cells [list]
            for {set j 0} {$j < $ncol} {incr j} {
                lappend cells [string range [expr rand()] 0 5]
            }
            lappend result "((tr [join $cells \t] tr))"
        }
        lappend result "table))"
        return [join $result \n]
    } 
Let us now generate such a table with 3 rows and 4 columns with the following instruction:
    ((e randomTable 3 4 e))
The Tcl proc will generate the following code:
((table border=1 align=center
((tr 0.0772	0.8309	0.3638	0.6596 tr))
((tr 0.4204	0.7307	0.4537	0.2380 tr))
((tr 0.4843	0.7478	0.0226	0.2118 tr))
table))
This is a block of code written in the Aida Markup Language which will be processed by the Aida parser and will finally result in the following table:
0.07720.83090.36380.6596
0.42040.73070.45370.2380
0.48430.74780.02260.2118

Aida core Tcl commands

The Aida Tcl interpreter defines a few core commands which can be used from library code or from custom scripts in order to interact with the program. These core commands are described in the following sections. They are all defined in the aida namespace.

The [aida::splitting] command

This command does not take any argument. It returns a boolean which indicates if Aida is in the process of splitting (value 1) or of converting to a single output file (value 0).

The [aida::getDepth] command

The syntax of this command is:
    aida::getDepth ?type?
When it is used without any argument, it returns the current depth of nested lists. If the parser is not currently in a list block, the value is 0.
The type argument can be "dl", "ol" or "ul" which stands for description list, ordered list and unordered list respectively. In that case, the command returns the depth among lists of the given type : if an ordered list contains an unordered list which itself contains an ordered list, the depth (among ordered lists) inside the innermost list is 2 and not 3, and this is the value which is returned by [aida::getDepth "ol"].

The [aida::getDir] command

This command does not take any argument. It returns the path of the directory containing the Aida file which is currently parsed. This file is not necessarily the top file because it could have been included with an ((input or an ((include tag.
If the Aida input comes from stdin, the returned path is the current directory.

The [aida::inputEncoding] command

The syntax of this command is:
    aida::inputEncoding ?enc?
It lets you get or set the input encoding. When used with no argument, it returns the name of the current input encoding. Otherwise, the command sets the input encoding to enc.
Not all the encodings returned by the Tcl command [encoding names] can be used. See the command aida info encodings: it returns a list of the known encodings but some of them are marked with an asterisk indicating that they are not available as input encoding (only as output encoding). Currently dingbats, ebcdic, identity, symbol, unicode (i-e UTF16) are not supported. This restriction is due to the fact that the Aida Bison parser can not handle these encodings. It might be removed in a future version of Aida.
The UTF8 encoding is supported and can be specified as "utf-8" or "utf8".

The [aida::outputEncoding] command

The syntax of this command is:
    aida::outputEncoding ?enc?
It lets you get or set the output encoding. When used with no argument, it returns the name of the current output encoding. Otherwise, the command sets the output encoding to enc.
All the encodings returned by the Tcl command [encoding names] can be used as output encoding.

Writing a new target for Aida

Defining a new target amounts essentially to two tasks:
The directory for the new target can be located anywhere on the host machine provided this location is listed in the aida_path variable so that the aida command can find it.
A possible solution is to create a custom library and install the target in this library. For instance, suppose this custom library is named aidalocal in your home directory and you want to define a new target for the hypothetical format foobar. You just have to create the following architecture:
    --- aidalocal
       |--- foobar
           |--- convert.tcl
           |--- default.tcl
In order to make sure that Aida detects this target, the path of the aidalocal library must be appended to the aida_path variable. The Tcl instruction to do that is simply
    lappend aida_path ~/aidalocal
This instruction should be inserted in your configuration file ~/.aidarc/config.tcl (create it if it does not exist yet). See the section Configuration files for more info about this. See the section about the Global variables for more information about the aida_path variable.
Once this is done, the following command should list the new target :
    aida info targets
The following sections explain how to define the callbacks invoked by the Aida parser when the commands aida convert or aida split are executed.
As a convenience, there are template files in the Aida library for the two target files convert.tcl and default.tcl. They are located in the subdirectory template of the Aida library (you can find this library with the command aida info lib). These templates are named convert_tmpl.tcl and default_tmpl.tcl. You can just copy them to your new target directory (~/aidalocal/foobar) and remove the _tmpl suffix: then edit them and replace all the occurences of the string <TMPL> by the name of your target (foobar in our previous example) as explained at the beginning of the template files.
All that remains to do is to provide sensible definitions for the callbacks. Not all callbacks have to be defined. Aida provides simple basic definitions for the callbacks which may be enough for the new target. These definitions are invoked automatically by Aida when no target specific callback is found.
For instance, if the parser invokes the commentProc callback and if no proc named foobar::commentProc is found by the interpreter, then the default definition (named base::commentProc) is automatically invoked instead.
In order for this automatic mechanism to work correctly, it is essential that you place the following instruction at the beginning of the file convert.tcl:
    namespace eval foobar {	
    	# Ensure fallback on base commands
    	namespace path ::base
    }
Note that this piece of code is provided by the template file, so, if you applied the instructions above, there is nothing to do.
All the definitions and settings are done in a namespace with the same name as the target. If the target is foobar, the previous instruction had the effect of creating a namespace named foobar.

Callbacks

As explained in the previous section, the target directory contains a file convert.tcl with the definitions of the callbacks and a file default.tcl with target specific settings (header parameters, attributes, etc.).
The following procs may be defined in the target namespace:
    anchorProc
    commentProc
    horizRuleProc
    imageProc
    linkProc
    listProc
    navBarProc
    newLineProc
    postambleProc
    preambleProc
    printIndexProc
    refProc
    sectionProc
    setIndexProc
    styleProc
    tableProc
    tocProc
    verbProc
    verbatimProc
For instance, in the case of the html target, this should be really: html::anchorProc, html::commentProc, etc.
The precise syntax of the callbacks is explained in the following paragraphs. In order to get a better understanding of what these procs are supposed to do, it can be useful to look in the Aida library and read the definitions of the various targets. The file utils.tcl in the library also contains various utility procs which can help in writing the callbacks. These procs are documented in the comments accompanying their definition.
The following sections indicate the prototype of each callback. The core is responsible for invoking the callbacks at the appropriate moment and for filling the arguments accordingly. Everywhere, in what follows, trgt should be replaced by the actual name of the target.

The anchorProc callback

The syntax of the anchorProc callback is:
	proc trgt::anchorProc {label}
This proc must return a string which defines a label or an anchor named label in the target format.

The commentProc callback

The syntax of the commentProc callback is:
	proc trgt::commentProc {str}
This proc must return a string which represents a comment with the str argument in the target format.

The horizRuleProc callback

The syntax of the horizRuleProc callback is:
	proc trgt::horizRuleProc {}
This proc receives no argument and must return a string which represents a horizontal rule in the target format.

The imageProc callback

The syntax of the imageProc callback is:
	proc trgt::imageProc {str attr}
This proc must return a string which represents the code to insert an image in the target format. The str argument is the address of the image and the attr argument is a (possibly empty) set of attributes. 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 right.
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. lt))

The linkProc callback

The syntax of the linkProc callback is:
	proc trgt::linkProc {str url}
This proc must return a string which defines an external hyperlink named str in the target format. The url argument is the destination this link is pointing to.

The listProc callback

The syntax of the listProc callback is:
	proc trgt::listProc {type depth attr itemList}
This proc must return a string which represents the code for an entire list in the target format.
The itemList argument is a Tcl list containing all the list items.
The type argument can be on of "ol", "ul" or "dl", designating respectively an ordered list, an unordered list or a description list.
The depth argument indicates the nesting level of the list: a list at the top level has depth 1. If one of its items contains a list itself, this list will have depth 2. One can use the core command aida::getDepth to have more information about the depth.
The attr argument is a (possibly empty) set of attributes. 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 (possible values: disc, square or circle).
  • 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.

The navBarProc callback

The syntax of the newLineProc callback is:
	proc trgt::navBarProc {curr prev next top}
This proc must return a string which defines a navigation bar in the target format. It is invoked only in the case of the aida split command. Its arguments curr, prev, next, top correspond respectively to the current split file, the previous one, the next one and the top one.

The newLineProc callback

The syntax of the newLineProc callback is:
	proc trgt::newLineProc {}
This proc receives no argument and must return a string which represents a line feed in the target format.

The postambleProc callback

The syntax of the postambleProc callback is:
	proc trgt::postambleProc {}
This proc receives no argument and must generate a block of text to be written at the end of the output file in the target format.

The preambleProc callback

The syntax of the preambleProc callback is:
	proc trgt::preambleProc {}
This proc receives no argument and must generate a block of text to be inserted at the beginning of the output file in the target format.

The printIndexProc callback

The syntax of the printIndexProc callback is:
	proc trgt::printIndexProc {}
This proc receives no argument and must generate a block of text representing the list of all the terms indexed in the original Aida file using the ((x x)) pair of tags.

The refProc callback

The syntax of the refProc callback is:
	proc trgt::refProc {str label {file ""}}
This proc must return a string which defines an internal hyperlink or reference in the target format.
The str argument is the string to be displayed. The label argument is the label this reference is pointing to.
The file argument is filled only in the case of the aida split command and contains the name of the split file where the label is found.

The sectionProc callback

The syntax of the sectionProc callback is:
	proc trgt::sectionProc {str level {file ""}}
This proc must return a string which defines a section in the target format.
The str argument is the title of the section and the level argument is its level (a number between 1 and 6).
The file argument is filled only in the case of the aida split command and contains the name of the split file where the section is found.

The setIndexProc callback

The syntax of the setIndexProc callback is:
	proc trgt::setIndexProc {str {file ""}}
This proc must return a string which can generate an indexed entry in the target format if this format supports indexation. Some target implementations (like the text target for instance) manage their index entries internally and this proc may return an empty string.
The str argument is the name of the entry.
The file argument is filled only in the case of the aida split command and contains the name of the split file where the entry is found.

The styleProc callback

The syntax of the styleProc callback is:
	proc trgt::styleProc {style begin}
This proc must return a string which generates a switch to or from the specified style.
The 'style' argument can be: "i", "b", "u".
The 'begin' argument tells if it is an opening or a closing tag.

The tableProc callback

The syntax of the tableProc callback is:
	proc trgt::tableProc {attr rowList}
This proc must return a block which represents an entire table.
The rowList argument is a Tcl list containing all the rows of the table. Each row is a string in which the cells are separated by a tabulation character.
The attr argument is a (possibly empty) set of attributes. 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 right.
format
alignment of the columns. A Latex-like specification as with the \tabular environment. For instance: format=cclr.
Some targets support other attributes. For instance, with the html target, one can specify any of the attributes supported by the Html <TABLE> tag.

The tocProc callback

The syntax of the tocProc callback is:
	proc trgt::tocProc {}
This proc receives no argument and must generate a block of text representing the table of contents of the document.

The verbProc callback

The syntax of the verbProc callback is:
	proc trgt::verbProc {str}
This proc is invoked when the ((v v)) or the ((q q)) pair of tags are encountered. It must return a string which represents an inline verbatim piece of text corresponding to the str argument in the target format.

The verbatimProc callback

The syntax of the verbatimProc callback is:
	proc trgt::verbatimProc {str}
This proc must return a string which defines a verbatim block in the target format. The str argument contains the text to display.

Hooks

A hook is just a Tcl proc which is executed at the appropriate moment.
These hooks are meant mainly for developers who define a new target and want to perform some tasks related to the target (pre- or post-treatment). If a user wants to perform similar tasks, the best way to achieve this is to use the :Source: or :TclCmd: header parameters or the -prefix option.

Conversion hooks

When one of the commands aida convert or aida split is executed, two hooks can be defined:
The pre convert hook is a proc named preConvertHook and defined in the namespace of the target. For instance, if the target is html, the pre convert hook proc should be named html::preConvertHook.
Similarly, the post convert hook proc is named postConvertHook in the same namespace. With the html target, its name should be html::postConvertHook.
The preConvertHook and postConvertHook procs do not take any argument. For instance, with the html target, the prototypes are:
    proc html::preConvertHook {} {
    	# Definition here
    }
    
    proc html::postConvertHook {} {
    	# Definition here
    }

Splitting hook

In the case of the aida split command, there is an additional hook named splitHook which is executed just after a new split file has been created and before any content is written in it. The splitHook proc takes one parameter which is the name of the split file. For instance, with the html target, the prototype is:
    proc html::splitHook {file} {
    	# Definition here
    }

Compiling Aida from sources

Compiling the aida command from the sources should not be a problem with a Unix-like system provided a C compiler is present on the machine, as well as a recent version of Bison (version 2.4 or greater) and Flex (version 2.5 or greater).
The compiling process is driven by a Makefile. It is quite standard and can be performed by the following steps:
  1. retrieve the most recent aida sources (see the Download section).
  2. go to the top directory containing the sources (i-e the directory containing the file configure.ac).
  3. generate the file src/config.h.in with the command:
        autoheader
    
  4. generate the configure script with the command:
        autoconf
    
  5. execute the configure script with the command:
        ./configure
    
  6. compile the sources with the command:
        make
    
  7. install the binary and the library with the command (you must have administrator privileges):
        sudo make install
    

The Aida project

Download aida

The Aida project is an Open Source project hosted by SourceForge at this address.
The latest releases can be obtained in the File Releases area.
The latest state of the source code can be obtained from the Subversion repository with the following command :
    svn checkout http://svn.code.sf.net/p/aidadoc/svn/trunk aidadoc-svn
One can also just browse the Subversion repository here.

Reports

In order to report bugs or make requests about the project, please use the tickets system.
In order to discuss the usage of the Aida system or the Aida Markup Language, there is a mailing list.
The web page for users of the mailing list to subscribe or unsubscribe is: aidadoc-users
There is also an email-based interface for users of the list; you can get info about using it by sending a message with just the word help as subject or in the body, to:
       aidadoc-users-request@lists.sourceforge.net

License

The Aida project is distributed under a BSD License: see the Open Source Initiative site.
Copyright (c) 2010-2011, Bernard Desgraupes <bdesgraupes@users.sourceforge.net>, All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Last updated 2011-05-20 08:51:02