Help for version 1.3 of Aida.

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


Quick Example

Introduction

The Aida project is two-fold:

it defines a simple common markup language.
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 html -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.

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. But a global setting is always registered for the current target, so make sure global declarations come before target specific ones. For instance, the following settings :
:PageWidth:text:      70
:PageWidth:           50

will result in the PageWidth being set to 50 when the target is text.
One can also define a target-specific header parameter which will be valid for any target by specifying an asterisk instead of the target. For instance:
:DestDir:*:      Output/Any

This is not the same as defining the parameter as a global parameter because a particular target may define a default value for a setting which will override the global setting. The asterisk notation was introduced in version 1.2 of Aida.
The value of the DestDir parameter can contain Tcl variables. They are substituted before the value is used. For instance:
    :DestDir:        Output/$aida_target  This instruction means that if the target is html, the output file will be in the directory Output/html, and if the target is latex, it will be in the directory Output/latex. Similarly, with the following instruction:  :DestDir: Output/[string toupper$aida_target]

the output directories would be respectively Output/HTML and Output/LATEX with names in uppercase letters.

## Reserved parameters

A few header parameters are reserver by the aida command and used by the library. The most important parameters are:
DestDir
specifies the output directory. Its path can be absolute, otherwise it is relative to the directory containing the file where this parameter is declared.
Source
specifies a Tcl file to be sourced in the Tcl interpreter. There can be several :Source: declarations. The path can be absolute, otherwise it is relative to the directory containing the file where this parameter is declared.
TclCmd
specifies a Tcl instruction or a Tcl proc to evaluate in the Tcl interpreter. There can be several :TclCmd: declarations. It can be useful to declare variables used later in the file with the ((e e)) pair of tags or in the condition of an ((if tag.
Output
specifies a default filename when the output is sent to a file rather than to the Terminal (stdout). This parameter, if present, is used when the -output option of the aida convert command is specified as an empty string: in that case, aida has to build a default name (see the description of the 'aida convert' command for more informations). This parameter was introduced in version 1.2.
Here are a few examples:
    :DestDir:        output
:DestDir:html:   ../htdocs
:Source:         scripts/foobar.tcl
:TclCmd:         set versionNumber "1.2b1"

Other useful parameters are
Title
specify the title of the document. This is used by some targets, like the html target, to give a title to the document.
Preamble
specify the name of a file whose contents will be inserted in the preamble of the output document. See the section Writing a custom preamble.
specify a string which will be inserted verbatim in the preamble of the output document. If you need to insert more than one string in the preamble, use the Preamble option instead.
TocDepth
specify the level of sections to include in the table of contents (a value between 0 and 6).
SectionDepth
specify the level of sections receiving a number (a value between 1 and 6). It is meaningful only if the NumberSections parameter is set to 1.
NumberIndices
specify if the indexed terms should be attributed a number (value 0 or 1).
NumberRefs
specify if the labels and references should be attributed a number (value 0 or 1).
NumberSections
specify if sections should be numbered (value 0 or 1).
NavBar
specify if a navigation bar should be inserted in split files.
NavExtension
NavNext
NavPrev
NavTop
PageWidth
specify the page width.
The default values for these parameters may vary depending on the target. Use the following command to get the current settings:
    aida info parameters ?target?


## Multiple targets

Some header parameters are supported by several targets but not all.
Extension
modify the default extension used for the output file. This parameter is supported by the html, hyperref, latex, man, text targets. For instance, the following setting will produce a file for the Sweave system defined by the statistical package R:
    :Extension:latex:  .Snw

IndexMark
specify the base name used to build labels for the index entries (the default is usually AIDAIDX). This parameter is supported by the html, markdown, mediawiki, pmwiki, trac targets.
SectionMark
specify the base name used to build labels for the sections (the default is usually AIDASEC). This parameter is supported by the html, latex, markdown, mediawiki, pmwiki, trac targets.

## User defined parameters

Internally the settings made via header parameters are stored in a Tcl array called aida_head. It is possible to set a value in this array directly in a Tcl file sourced in aida's Tcl interpreter: this could be a configuration file, a file sourced with the :Source: header parameter, or a file sourced from the command line with the -prefix option. The aida_head array is defined in the global scope for general settings or in a namespace named after the target for target-specific settings. For instance, the following header declaration
:DestDir:        output

is equivalent to the following Tcl instruction
set aida_head(DestDir)        "output"

:DestDir:html:        ../htdocs

is equivalent to the following Tcl instruction
namespace eval html {
}

Getting and setting parameter values can be done using the procs aida::getParam and aida::setParam defined in the Aida core library. For instance, a prefix file may contain the following instructions which are equivalent to the previous examples:
    aida::setParam DestDir output
aida::setParam DestDir ../htdocs html

The procs aida::getParam and aida::setParam can also be used in a configuration file default.tcl or convert.tcl (but not config.tcl which is sourced before they are defined. In that case, you should use the aida_head array directly). See the section
Configuration of the Aida system.

# 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 NumberSections and the SectionDepth header parameters.
One can force a line feed with the ((nl)) tag.
The ((hr)) tag inserts a horizontal rule.

## Structures

The ((toc)) tag tells Aida to build a table of contents and insert it at the location of this tag. This table of contents lists all the sections of the document down to a certain level which can be controlled with the TocDepth header parameter.
Similarly the ((index)) tag tells Aida to build an index and insert it at the location of this tag. This is the list of all the terms which have been marked with the ((x x)) pair of tags.

## Includes

The Aida input can be organized as a set of several files which are assembled together by a master file using either the ((include or the ((input tags. These tags must be at the beginning of a line and are followed by the name of the file. Included files can be nested: an included file itself can contain ((include or ((input tags.
The included file can be designated either by an absolute or a relative path. When the file to include is designated by a relative path, this path is always relative to the calling file, i-e to the directory containing the file with the ((input or ((include tags. For instance, suppose we have the following architecture:
    main.aida
--- Inputs
|--- sub.aida
|--- SubInputs1
|   |--- subsub1.aida
|--- SubInputs2
|   |--- subsub2.aida

In order to include the file subsub2.aida from the file main.aida, the instruction is:
    ((input Inputs/SubInputs2/subsub2.aida

In order to include the same file from the file sub.aida, the instruction is:
    ((input SubInputs2/subsub2.aida

In order to include the same file from the file subsub1.aida, the instruction is:
    ((input ../SubInputs2/subsub2.aida


The difference between the ((include and the ((input tags is meaningful only with the aida split command. When this command is invoked with a splitting level set to 0, splitting occurs at each ((input tag and never at an ((include tag.
There is a ((split)) tag which forces a split with the aida split command no matter which splitting level has been selected.

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

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

## Lists

There are three kinds of lists: unordered lists, ordered lists and description lists. They must be enclosed respectively in the following pairs of tags:
 ((ul ul)) beginning/end of unordered list ((ol ol)) beginning/end of ordered list ((dl dl)) beginning/end of description list
Both tags (opening or closing) can be indented relatively to the beginning of the line.
The list items of an ordered or unordered list must be enclosed in ((li li)) tags. The structure of an unordered list, for instance, is:
    ((ul attributes
((li item 1... li))
((li item 2... li))
...
ul))

Note that the closing list item tag li)) is mandatory.
The attributes are optional. They must all be on the same line as the opening list tag and are made of pairs of the form key=value.
The structure of an ordered list is exactly the same as for an unordered list.
The structure of a description list is slightly different and makes use of ((lt lt)) tags:
    ((dl
((lt term 1
description of term 1
lt))
((lt term 2
description of term 2
lt))
...
dl))

Each term must be on the same line as the opening ((lt tag and its description spans the following lines up to the closing lt)) tag.
Lists of any kind can be nested within one another.
The basic list attributes are similar to those found in the Html language:
start
it concerns ordered lists and indicates the first value of the numbering
type
it concerns both ordered and unordered lists.
• In the case of an unordered list, it specifies the kind of symbol to use at the beginning of a list item. The possible values are: none, 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.
Conversely, not all targets support the attributes above.

## Tables

The syntax of a table is
    ((table attributes
((tr row 1... tr))
((tr row 2... tr))
table))

The ((table table)) tags indicate the beginning and the end of a table respectively. The rows are delimited by the ((tr tr)) pair of tags.
The cells within a row are simply separated by a tabulation.
The opening ((table tag may be followed, on the same line, by a set of attributes. They obey the same convention as for the list tags above.
Note that tables can not be nested.
The basic table attributes are:
border
numeric value indicating the width of the border (0 means no border)
align
alignment of the table. Possible values: center, left or right.
format
alignment of the columns. The value is a Latex-like specification as with the \tabular environment in LaTeX. For instance: format=cclr. The vertical bar is also accepted: for instance format=r|c|l.
Some targets support other attributes.
For instance, with the html target, one can specify any of the attributes supported by the Html <TABLE> tag.
Conversely, not all targets support the attributes above: it is always licit to specify these attributes but not all targets are able to render them.

## Images

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

or
    ((img attributes
image img))

In the second form, the opening ((img tag is followed by a set of attributes using the same syntax as for the list or the table tags.
The basic image attributes are:
height
numeric value indicating the height of the image.
width
numeric value indicating the width of the image.
align
alignment of the table. Possible values: center, left or 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.
Conversely, not all targets support the attributes above.
Here are some examples:
    ((img height=250 alt="some text"
foobar.png img))

((img foobar.png img))


There two kinds of links: external links pointing to an external resource and internal links which are references to another part of the document. The external links are created using the ((lk tag. The syntax is:
    ((lk [url] text lk))

The URL pointed to by the link is enclosed between brackets and followed by the text to be displayed as a hyperlink. How these links are rendered depends on the target format. Not all targets offer a real navigation system.
An internal link points to a location marked by a label. A label is anchored in the document using the ((a a)) pair of tags. Labels must be unique. Then any reference to a label is created using the ((rf tag. Its syntax is:
    ((rf [label] text rf))

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


## Index

In order to create an index entry for a term, enclose it in a ((x x)) pair of tags. The index itself can be generated and inserted somewhere in the document using the ((index)) tag.

## Evaluation

### Verbatim text

Verbatim text is a portion of text which is not parsed by the Aida parser and which is sent 'as is' to the target. Each target has a callback which is invoked to handle this piece of text. Usually the target format has its own way of rendering verbatim text. A verbatim block is created with the ((| and |)) tags like this:
((|
    text of the block

|))
These tags must be at the beginning of a line.
It is also possible to insert verbatim text inside a line or a paragraph with the ((v v)) tags. It is similar to the \verb macro in LaTeX format.
Finally, there is a stronger pair of tags ((q q)) designed to strictly quote a piece of text: it just copies the enclosed text as is, with no parsing and no character mapping.
Here is an example where the ((q q)) tags can be useful. Suppose you want to insert some LaTeX code in your Aida source file to provoke a line feed (this is obtained with the LaTeX macro \newpage). Since this macro would not make sense with another target than the latex target, you need to put this in an ((if block:
    ((if $aida_target eq "latex" ((q \newpage q)) if))  Here the ((q q)) tags ensure that the macro will be copied as is. Otherwise, the characters mapping mechanism would convert the initial backslash and the output file would contain something like \textbackslash{}newpage. ### Tcl code The aida command contains a Tcl interpreter. Under the hood, this interpreter is used to process the Tcl code which defines, via callbacks, the behavior of each target. Of interest to the user is the fact that this Tcl interpreter is also able to evaluate Tcl code inserted in an Aida file. A block of Tcl code must be enclosed between an ((e e)) pair of tags. The contents of this pair of tags can be any valid Tcl code, a single instruction or an entire script. The same interpreter is used during all the parsing so it is possible, for instance, to declare variables at some point and use them later. The result of the execution of an ((e e)) block is passed to the Aida parser. So, an evaluation block can be used to generate dynamical contents in an Aida file. For instance, the evaluation block may contain a Tcl proc which generates an Aida table (i-e a table in the Aida markup language): Aida will first execute the proc, then the table produced by this proc will be processed by the parser to convert it into the target format. Tcl code can be stored in a separate file. In order to source such a file, one can use the -prefix option on the command line or declare it with the :Source: header parameter at the beginning of the Aida input file. Such a file may contain any Tcl code, in particular, the definition of Tcl procs invoked later in the document with ((e e)) tags. The Tcl files specified with the -prefix option or with the :Source: header parameter are assumed to be in the system encoding, not in the encoding specified by a -from option on the command line. The -from option lets you specify the encoding of the Aida input files, not the encoding of Tcl source code files. The system encoding is the encoding used by default on your system: you can determine it with the following command:  aida info sysenc  To learn more about the Tcl language, see the Tcl home page 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 if condition true ((else block if condition false if))  The ((else part of the block is optional, so the conditional block could be just: ((if condition block if condition true if))  The condition following the opening ((if tag can be any valid Tcl code which can be interpreted as true or false by the Tcl interpreter embedded in the Aida parser. For instance: ((if$aida_target eq "html"
some text for the html target only
if))


There are two kinds of comments: soft and strong.
A soft comment is a line starting with a pair of exclamation marks like this !!. Such a comment is not parsed by the Aida parser but is converted into a comment in the target format.
A strong comment is a line starting with triple exclamation marks like this !!!. Such a comment is ignored by the Aida parser and stripped from the output.

## Syntax summary

One can display a quick reminder of the Aida markup syntax with the following command:
    aida help syntax

Here is what it prints out:
Divisions
=========
((nl))               New line
((hr))               Horizontal rule
((index))            Insert an index
((split))            Force a split
((include            Include a file (non splittable)
((input              Input a file (splittable)

Style
=====
((i       i))        Italic
((b       b))        Bold
((u       u))        Underline
((y       y))        Typewriter

Lists
=====
((dl     dl))        Beginning/end of description list
((ol     ol))        Beginning/end of ordered list
((ul     ul))        Beginning/end of unordered list
((li     li))        Ordered/unordered list item
((lt     lt))        Description list term

Tables
======
((table  table))     Beginning/end of table
((tr        tr))     Table row (cells are tab-separated)

=====
((x         x))      Index entry
((img     img))      Insert an image
((a         a))      Named anchor (label)
((lk [url] txt lk))  Hyperlink (external)
((rf [lab] txt rf))  Reference (internal)

Evaluation
==========
((|       |))        Beginning/end of verbatim block
((v       v))        Inline verbatim
((q       q))        Quote as is
((e       e))        Eval sequence
((if     if))        Conditional block
((else               Alternative inside ((if block
!!                   Comment
!!!                  Stripped comment

The following tags must be at the beginning of a line:
((hr)) ((include ((index)) ((input ((nl)) ((split))
((table table)) ((toc)) ((tr ((| |))
The following tags can be indented:
((dl ((ol ((ul ((li ((lt
ol)) ul)) dl))
((s1 ((s2 ((s3 ((s4 ((s5 ((s6



# 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:
• the -d option sets the level of verbosity of the command. Its value is a number between 0 (silent) and 3 (pedantic).
• the -L option specifies the location of an Aida library. Its value is a path to the directory containing the library files (core.tcl, etc.). This is useful only if you want to run the aida command with another library than the default one. By default, aida knows where its library is located. This option was introduced in version 1.3.
• the -q option sets verbosity to 0.
• the -tl option enables tracing of the lexer's activity. This option is available only if aida was compiled with tracing enabled.
• the -tp option enables tracing of the parser's activity. This option is available only if aida was compiled with tracing enabled.
• 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.

## 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:
-collapse
a positive integer indicating the maximum number of successive end-of-line symbols. See details below.
-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 -collapse option is set to n, any sequence of more than n end-of-lines will be reduced to n (thus leaving n-1 blank lines between paragraphs). A useful value is n=2 which leaves one blank line between paragraphs. By default, this option is set to 2. If you want that no collapsing of blank lines be performed, set its value to 0. The -collapse option has no effect within lists, tables or verbatim environments.
If the -output option is omitted, the result of the aida convert command is written to the standard output (stdout). If this option is set, the result is written to a file. If the value of the option is not empty, it is used as the name of the file.
If the -output option is explicitly set to an empty string, Aida builds a default name for the output file. The default name is built like this:
• if an :Output: header parameter is found (target-specific or global), its value is used as the default name;
• otherwise, if the input comes from a file, the name of the input file is used, its extension being replaced by the default extension for the current target;
• finally, if the input comes from the standard input (stdin), the output file is named aida_out by default.

For instance, the following command:
    aida convert -targ latex -output "" foobar.aida

sends the output to a file named foobar.tex unless the input file foobar.aida contains an :Output: header parameter. If it contains for instance:
    :Output:latex:  raboof.xet

then the output file will be named raboof.xet.
On the other hand, 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:
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 syntax


### The info subcommand

The syntax of the info subcommand:
    aida info arg ?target?

The arg argument can be:
attributes
print the values of all the target-specific tag attributes. Starting from version 1.3, one can specify a target as an additional argument to get the attributes for this specific target. For instance: aida info attributes html.
configuration
print the name of 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.
extensions
print a table of the default file extensions used by the various targets. One can specify a target as an additional argument to get the default extension for this specific target. For instance: aida info ext latex. This option was introduced in version 1.2.
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.
mapping
print the values of the characters mapping array for every target defining such an array. Starting from version 1.3, one can specify a target as an additional argument to get the mapping for this specific target. For instance: aida info mapping html.
parameters
print the values of all the header parameters (global or target-specific) known to aida's Tcl interpreter. Starting from version 1.3, one can specify a target as an additional argument to get the default parameters for this specific target. For instance: aida info param latex.
path
print the list of directories visited by Aida when looking for a target implementation.
sysenc
print the system encoding (used when sourcing a Tcl source file). This option was introduced in version 1.2.
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.
version
print the version number of the command.
In the case of the attributes, encodings, mapping, and parameters 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 parameters
aida info -q parameters
aida info -q mapping


### The split subcommand

The syntax of the split subcommand is:
    aida split [options] [file]

The available options are:
-collapse
a positive integer indicating the maximum number of successive end-of-line symbols. See details with the convert command.
-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).
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.
Note that the -output option behaves slightly differently with the aida split command than with the aida convert command.
If the -output option is not specified or is specified as an empty string, Aida uses the name of the input file, if any, removes the extension, appends the format specifier _%d and the appropriate extension for the given target. If the input comes from stdin, the output base file name is aida_split with the suffix and the extension.
If the string specified in the -output option does not contain a format specifier, then the _%d specifier is inserted automatically before the extension.

# 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 one of these directories can contain some of 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 configuration directory, so that user settings 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]


## 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:
    $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.3, is '/usr/local/share/aida/1.3'. 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.3):  --- 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 target-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:
 aida_cwd the current working directory aida_library the location of the library directory aida_mapping a logical value to control chars mapping aida_name the name of the input file (if any) aida_output the value of the -output option (if any) aida_path the list of all the directories visited to find targets aida_target the current target aida_temp the temporary directory aida_unwrap a logical value to control text wrapping aida_verbosity the current level of verbosity aida_version the current version of Aida

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.
• 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_library 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). This can be useful to use to a non-standard library. • 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. • 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_output stores the value of the -output option in a aida convert or a aida split command. It the -output option was not specified, this variable is empty. It was first introduced in version 1.2 of Aida. • 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_temp contains the path of the temporary directory where all the intermediary files are written. This is the same directory returned by the aida info temp command. This variable was first introduced in version 1.2 of Aida. • 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_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. 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 5 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))"

## Compiling options

The configure script has an option which lets you compile aida without the tracing options and the debugging facilities. It is the --enable-tracing option which is on by default. If you want to disable it, you must rerun the configure script like this:
    ./configure --enable-tracing=no

and then run the make command.
Since version 1.3 of aida, there is a new configure option called --with-aidalib-loc which specifies a location where to install the Aida library. Its value is a path to a directory which will contain the Tcl library files (core.tcl, etc.). For instance, in order to have the library installed in /path/to/library, you must run the configure script like this:
    ./configure --with-aidalib-loc=/path/to/library

and then run the make command.
To know all the available configure options, execute the following command:
    ./configure --help

The --prefix option in particular can be used to install aida in another location than /usr/local. If you want aida to be installed under /opt/local, you just have to modify the configure command when compiling and replace it by
    ./configure --prefix=/opt/local

In that case, the binary command will be installed in /opt/local/bin and the library in /opt/local/share/aida.
Since version 1.3 of aida, the DESTDIR variable is supported by the make install target in order to install the binary and the library relatively to a specified location. For instance, if you don't have permissions to install into the default areas (in /usr/local for instance), and want to install in a directory called /some/custom/dir where you have write permission, you should execute the configure script and the make commands like this:
    ./configure --with-aidalib-loc=/some/custom/dir bindir=/
make
make DESTDIR=/some/custom/dir install


## Troubleshooting

You need a recent version of Bison (version 2.4 or greater) in order to compile aida with all the tracing options. The configure script will warn you if an older version of Bison is found: since version 1.2 of aida this is not fatal anymore, the tracing options will just be disabled.

# The Aida project

The Aida project is an Open Source project hosted by SourceForge at this address.
The current version is 1.3.
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 Aida


## Reports

In order to report bugs or make requests about the project, please use the issue tracking 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
To post a message to all the list members, send an e-mail here.
You can get info about using the list by sending a request message with just the word help as subject or in the body.