AidaDoc Wiki

Brought to you by: bdesgraupes

AidaHelp Log in to Edit

Table of contents

Introduction

The Aida project is two-fold:
it defines a simple common markup language,
designed to describe structured text; it provides a compiler which translates the
Aida syntax into various target formats (Html, Latex, Trac, Mediawiki,
Text, Markdown,...).

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 :

<HTML>
<HEAD>
<TITLE>Quick Example</TITLE>
</HEAD>
<BODY>

<H1><A NAME="AIDASEC0"/>Introduction</H1>

The <B>Aida</B> project is two-fold: 
<OL type="1" start="1">
    <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>

<H1><A NAME="AIDASEC1"/>Table</H1>

<TABLE border="1" align="center">
<TR><TD>Number</TD><TD>Element</TD><TD>Symbol</TD></TR>
<TR><TD>1</TD><TD>hydrogen</TD><TD>H</TD></TR>
<TR><TD>2</TD><TD>helium</TD><TD>He</TD></TR>
<TR><TD>3</TD><TD>lithium</TD><TD>Li</TD></TR>
<TR><TD>4</TD><TD>beryllium</TD><TD>Be</TD></TR>
</TABLE>

Updated on 2011-02-08.

</BODY>
</HTML>

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:

<TABLE border="0"> <TR><TD>`((i i))`</TD><TD>italic</TD></TR> <TR><TD>`((b b))`</TD><TD>bold</TD></TR> <TR><TD>`((u u))`</TD><TD>underline</TD></TR> <TR><TD>`((y y))`</TD><TD>monospaced (typewriter font)</TD></TR> </TABLE>

Sections

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

<TABLE border="0"> <TR><TD>`((s1 s1))`</TD><TD>level 1</TD></TR> <TR><TD>`((s2 s2))`</TD><TD>level 2</TD></TR> <TR><TD>`((s3 s3))`</TD><TD>level 3</TD></TR> <TR><TD>`((s4 s4))`</TD><TD>level 4</TD></TR> <TR><TD>`((s5 s5))`</TD><TD>level 5</TD></TR> <TR><TD>`((s6 s6))`</TD><TD>level 6</TD></TR> </TABLE>

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:

<TABLE border="0"> <TR><TD>`((ul ul))`</TD><TD>beginning/end of unordered list</TD></TR> <TR><TD>`((ol ol))`</TD><TD>beginning/end of ordered list</TD></TR> <TR><TD>`((dl dl))`</TD><TD>beginning/end of description list</TD></TR> </TABLE>

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

    ((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 <subcommand> [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:
the -d option sets the level of verbosity of the command. Its
value is a number between 0 (silent) and 3 (pedantic). the -q option sets verbosity to 0.
the -tl option enables tracing of the lexer's activity.
the -tp option enables tracing of the parser's activity.
the -x option tells aida not to delete the temporary files it
writes during processing. These files are written in a temporary location
(see the command aida info temp)
and are normally deleted when they are not used anymore. With the -x
option you can keep them for inspection. the -- option marks the end of the options.

There are also two standalone options:
the -h option prints a usage string. It is a shortcut for aida help.
the -v option returns the current version number of the
command. It is a shortcut for aida info version.

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 :
a site configuration directory located on the host
machine and specified using the AIDA_SITE_CONFIG environment variable.
a user configuration directory .aidarc located in the current user's home
directory.

Each directory can contain the following files:
config.tcl which stores configuration settings.
default.tcl which stores processing options and parameters.
convert.tcl* which stores Tcl procs.

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

    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:
the global options are parsed;
the Tcl interpreter is created. During the initialization of the
interpreter,
- global variables (aida_version, aida_library, aida_verbosity)
are created and set with default values;
- an init.tcl script is sourced if it is found;
- the configuration files config.tcl are sourced if they exist;
- finally, the basic core library is sourced (the file core.tcl).
the code to execute the subcommand is invoked. For the convert
and the split subcommands, the command specific options are first parsed,
then several files are sourced:
- the basic files default.tcl and convert.tcl located in
$aida_library/base;
- the target specific files default.tcl and convert.tcl;
- site specific files default.tcl and convert.tcl if
they are found;
- user files default.tcl and convert.tcl if they are
found. then, just before
parsing, if a preConvertHook hook exists, it is executed;

after parsing, if a postConvertHook hook exists, it is
executed. See more information about hooks below.

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
1. config_dir/config.tcl
1. ~/.aidarc/config.tcl
1. aida_library/core.tcl
1. aida_library/base/default.tcl
1. aida_library/base/convert.tcl
1. aida_library/<target>/default.tcl
1. aida_library/<target>/convert.tcl
1. config_dir/default.tcl
1. ~/.aidarc/default.tcl
1. config_dir/convert.tcl
1. ~/.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
1. config_dir/config.tcl
1. ~/.aidarc/config.tcl
1. aida_library/core.tcl
1. aida_library/base/default.tcl
1. config_dir/default.tcl
1. ~/.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

    AIDA_INPUT_ENCODING=iso8859-1 aida convert somefile.aida

Extending Aida

This section contains information about
how to modify Aida's behavior;
how to write dynamic contents in an Aida file;
* how to extend Aida and develop a
converter for a new target.

Aida's internal structure

The Aida system is essentially made of two components:
a core application (the aida command itself) written in C;
a library written in
Tcl
which contains definitions for most of the tasks to perform.

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 :
convert.tcl contains the definition of the callbacks;
default.tcl contains default values for some header
parameters and taget-specific variables.

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:

<TABLE border="1" align="center"> <TR><TD>*aida_library*</TD><TD>the location of the library directory</TD></TR> <TR><TD>*aida_path*</TD><TD>the list of all the directories visited to find targets</TD></TR> <TR><TD>*aida_verbosity*</TD><TD>the current level of verbosity</TD></TR> <TR><TD>*aida_version*</TD><TD>the current version of Aida</TD></TR> <TR><TD>*aida_cwd*</TD><TD>the current working directory</TD></TR> <TR><TD>*aida_target*</TD><TD>the current target</TD></TR> <TR><TD>*aida_name*</TD><TD>the name of the input file (if any)</TD></TR> <TR><TD>*aida_mapping*</TD><TD>a logical value to control chars mapping</TD></TR> <TR><TD>*aida_unwrap*</TD><TD>a logical value to control text wrapping</TD></TR> </TABLE>

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.

By default, the value of the aida_library variable is
computed during the compilation of the tool: it is set as
"${prefix}/lib/aida${aida_version}" where ${prefix} is the prefix
defined by the build configuration script (by default /usr/local).
For instance, with version 1.0 of aida, the site library directory would be
/usr/local/lib/aida/1.0 by default. Since aida_library is
a linked variable it can be redefined in a configuration file (see the
Configuration files section for more info about site-wide and
per-user settings).
The variable aida_path always contains the aida_library directory, but other locations can be appended in order to define other
targets which are not part of the standard distribution or modify existing
targets. A good place to modify the aida_path variable is in one of
the config.tcl files, in the site-wide or per-user configuration
directory.
The variable aida_target stores the name of the current target
when executing the aida convert or aida split
commands. It should not be modified.
The variable aida_name stores the name of the main input file
in a aida convert or a aida split command. If the input is
read from the standard input channel (stdin), this variable is empty.
The variable aida_verbosity can be used to modify the level
of verbosity of the command (between 0 and 3). All the informational
messages are sent to the error channel (stderr) and thus should not
interfere with the normal output of the aida convert and aida split
commands when they are directed to files on disk.
Recall that the verbosity can also be set on the command line with the -d
option.
The variable aida_version contains the value of the current
version of the aida command. This can be useful for the developer
of a new target who wants to distinguish between different versions of
aida.
The variable aida_cwd contains the path of the current
working directory, i-e the directory from which the command is executed.
The variable aida_unwrap can be used to set or unset the
text unwrapping. Its value is 1 or 0 respectively. The default value is 0.
If it is set to 1, then text unwrapping occurs: end-of-line characters are
replaced by a single space. This can be useful for developers of a new
target in order to achieve some effects: for instance, to ensure that a
portion of text is passed by the parser as a single line. This is a linked variable, so it
affects the behavior of the parser accordingly.
The variable aida_mapping can be used to set or unset the
characters mapping mechanism. Its value is 1 or 0 respectively. The default
value is 1. Some targets define a chars mapping array in order to
substitute some characters. For instance, the html target has such an array
in order to replace all the apostrophs by the Html entity &``apos;.
If the variable aida_mapping is set to 0, the substitution
mechanism will be disabled. This can be useful for developers.

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:
on the command line
in the input file's header
in the configuration files
in the library files containing the callbacks
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:
* in the header of the input file:

    :PageWidth:         80

in a configuration file, with a Tcl instruction like
this:
```
set aida_head(PageWidth)        80
```

If the setting concerns the text target exclusively, the instruction is:

    namespace eval text {
        variable aida_head
        set aida_head(PageWidth)        80
    }

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 definition of the proc can be placed somewhere (before it is used)
in a ((e e)) pair of tags; the proc can be stored in a file which is sourced using the
:Source: header parameter. For instance, suppose the proc is saved in a
file named myProcs.tcl located in the same folder as the Aida file.
It is enough then to write the following header instruction at the
beginning of the Aida file:

    :Source:    myProcs.tcl

same as before but the file is sourced using the -prefix command line
option. The command line would look like this:
```
aida convert -targ html -prefix myProcs.tcl foobar.aida
```

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.7989 0.6647  0.4696  0.2992 tr))
((tr 0.7605 0.3700  0.1819  0.7063 tr))
((tr 0.4163 0.1390  0.2070  0.9185 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:

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:
create a directory with the name of the target, containing two files
named convert.tcl and default.tcl;
write the callbacks for your target in the file convert.tcl and
set the value of some internal variables in the file default.tcl
if necessary.

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 executed at the end of the startup
sequence, when the Aida input file is about to be parsed; the post convert hook is executed at the end of the parsing
process.

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).
1. go to the top directory containing the sources (i-e the directory
containing the file configure.ac).
1. generate the file src/config.h.in with the command:

    autoheader

generate the configure script with the command:
```
autoconf
```
execute the configure script with the command:
```
./configure
```
compile the sources with the command:
```
make
```
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.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of Bernard Desgraupes nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.

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 15:59:10