Help for version 1.4.3 of Aida.
Table of contents

Introduction

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

Quick start

Here is a quick example to give a more precise idea of what the Aida mechanism is about.
Using your favorite text editor, create a new file named example.aida with a following contents: 
:DestDir:           aida_output/
:Title:             Quick Example

((s1 Introduction s1))

The ((b Aida b)) project is two-fold: 
((ol
((li it defines a simple common ((i markup language i)). li))
((li it provides a ((i compiler i)) to convert the markup into target 
formats. li))
ol))

((s1 Table s1))

((table border=1 align=center
((tr Number	Element	Symbol tr))
((tr 1	hydrogen	H tr))
((tr 2	helium	He tr))
((tr 3	lithium	Li tr))
((tr 4	beryllium	Be tr))
table))

Updated on ((e clock format [clock seconds] -format "%Y-%m-%d" e)).

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

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

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

2 Table

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

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

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. 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"
:Output:text:    README
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.
AddHeader
specify a string which will be inserted verbatim in the preamble of the output document. This option can be used repeatedly: all the strings will be inserted in the order they are declared. See also the Preamble option if you need to insert more than one string in the preamble.
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
specify the file extension used in the navigation bar links.
NavNext
specify the name of the Next link in the navigation bar.
NavPrev
specify the name of the Prev link in the navigation bar.
NavTop
specify the name of the Top link in the navigation bar.
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"
Similarly, the following header declaration 
:DestDir:html:        ../htdocs
is equivalent to the following Tcl instruction 
namespace eval html {
set aida_head(DestDir)    "../htdocs"
}
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.
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))

Hyperlinks

There are 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))
The syntax of the ((a a))tags can take two forms (since version 1.4.3): 
((a label a))
((a [label] text a))
For example: 
((lk [http://www.free-soft.org/] Free Software Foundation lk))
((a plug a))
((rf [plug] see the Plugins section rf))
((a [pluglist] Plugins List a))
((rf [pluglist] go to the plugins list 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. This means that no callback is invoked to handle the chunk of text enclosed in the ((q q)) tags.
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))

Comments

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

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
=========
((s1     s1))        Chapter header
((s2     s2))        Section header
((s3     s3))        Subsection header
((s4     s4))        Subsubsection header
((s5     s5))        Paragraph header
((s6     s6))        Subparagraph header
((nl))               New line
((hr))               Horizontal rule
((toc))              Insert a table of contents
((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)

Links
=====
((x         x))      Index entry
((img     img))      Insert an image
((a  label  a))      Named anchor (label)
((a [label] txt a))  Named anchor (label and text)
((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 <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:

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.
-eval
an instruction to evaluate in the embedded Tcl interpreter. There can be several options -eval on the command line.
-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:
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:
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 ?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.
license
print the license of Aida.
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.
-eval
an instruction to evaluate in the embedded Tcl interpreter. There can be several options -eval on the command line.
-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 : Each one of these directories can contain some of the following files:
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]
set aida_head(DefaultTarget)    "latex"

Environment variables

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

The startup sequence

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

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.
Note that the input encoding specified by a -from option does not apply to Tcl code files read via a -prefix option or via a :Source: header parameter (see the Tcl code section).

Default encodings

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

Setting encodings programmatically

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

Encoding environment variables

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

Extending Aida

This section contains information about

Aida's internal structure

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

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_cwdthe current working directory
aida_librarythe location of the library directory
aida_mappinga logical value to control chars mapping
aida_namethe name of the input file (if any)
aida_outputthe value of the -output option (if any)
aida_paththe list of all the directories visited to find targets
aida_targetthe current target
aida_tempthe temporary directory
aida_unwrapa logical value to control text wrapping
aida_verbositythe current level of verbosity
aida_versionthe 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.
Some of these variables are set by the core before the default.tcl files in the configuration directories are sourced, so their values can be overriden there.

Precedence

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

Writing dynamic contents

The pair of tags ((e e)) can evaluate any valid Tcl code during the conversion process. This is very useful for generating contents on the fly, i-e when a file is processed. The result of the Tcl code is inserted in the document in place of the ((e e)) tags and is passed to the Aida parser.
Combining this possibility with the :Source: or :TclCmd: header parameters, or with the -prefix command line option provides with a very flexible system to generate dynamic contents.
Let us start with a simple example. The following piece of text will display the name of the currently logged user: 
This is the session of user ((e exec whoami e)).
As a result, the converted file will display: This is the session of user bernardo. Indeed exec is a Tcl command used to execute a Unix command and whoami is the Unix command reporting the name of the user of the current session.
The same Tcl interpreter is used by Aida to evaluate any piece of code so one can, for instance, define a global variable somewhere and reuse it later. Let us see a simple example making use of the :TclCmd: header parameter. The next header instruction creates a global variable called 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.
Inside a pair of ((e e)) tags, the aida parser replaces end of lines by spaces. This has two important consequences:
Very often a pair of ((e e)) tags will just 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 printAlbumsCount {} {
    set musicDir [file normalize ~/Music];
    if {[file exists $musicDir]} {
        set albums [glob -dir $musicDir/iTunes -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 printAlbumsCount e)).
which results in something like: The Music dir contains 3 albums.
This works only if the printAlbumsCount proc is found by the Tcl interpreter. There are several methods to achieve this:
The solution of storing the proc in a separate file is the most convenient because it allows you to define an entire library of Tcl procs and maintain them in a single location. The same Tcl file could also be used in other Aida documents.
Here is a last example demonstrating the generation of more complex Aida code. The proc printRandomTable 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 printRandomTable {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 using the following instruction: 
((e printRandomTable 3 4 e))
The Tcl proc will generate something looking like the following code (but with different values since they are random!): 
((table border=1 align=center
((tr 0.4596	0.2595	0.1205	0.6766 tr))
((tr 0.8762	0.4004	0.7333	0.6897 tr))
((tr 0.5948	0.5263	0.5366	0.3490 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 in the output:
0.45960.25950.12050.6766
0.87620.40040.73330.6897
0.59480.52630.53660.3490

Writing a custom preamble

Some target formats have preambles: in the case of an Html document, for instance, it is the section enclosed between the <HEAD> and </HEAD> tags. In a LaTeX document, it is the section coming before the \begin{document} macro.
By default, Aida builds a preamble invoking a preambleProc callback defined for the current target. But one may wish to insert additional contents in the preamble of the output document.
As explained in the section Reserved parameters, one can use the Preamble and AddHeader parameters. The value of the Preamble parameter is the name of a file whose contents will be inserted in the preamble of the output document. The value of the AddHeader parameter is a string to insert verbatim in the preamble of the output document. There can be several AddHeader declarations in the header, they accumulate.
These parameters are supported by all the targets. They are usually used as target-specific parameters. Here are a few examples: 
:Preamble:latex:     addpreamble.tex

:Preamble:html:      addpreamble.html
 
:AddHeader:latex:    \newcommand{\foobar}{definition here...}

:AddHeader:html:     <STYLE>body,td,p{font-family:arial,sans-serif}</STYLE>
Another method for declaring extra contents in the preamble of the output file is to define a Tcl proc called addHeader in the target's namespace. The return value of this proc should be a list of additional strings to insert in the preamble. Here is an example for the latex target: 
namespace eval latex {
    proc addHeader {} {
        return [list "\\renewcommand{\\textfraction}{0.1}"]
    }
}
This method is useful when the contents must be built dynamically: the proc can contain any valid and arbitrarily complex Tcl code. In order to be found by the Tcl interpreter, such a proc can be put in a configuration file if it is designed to be permanent, or in a file which will be sourced using the -prefix option on the command line, or in a file sourced using the :Source: header parameter.

Characters mapping

There is a mechanism for replacing single symbols by a string. For instance, the html target needs to be able to replace symbols like the ampersand & by the equivalent Html entity &amp; and, in the case of the Latex target, the same symbol has to be escaped as \&. This mechanism is installed via a Tcl array named aida_map, which defines the desired mapping. It is a correspondance array which associates single bytes with replacement strings. For instance, the html target defines 
set aida_map(&)      "&"
whereas the latex target defines 
set aida_map(&)      "\\&"
These mappings are byte-oriented: it means that they are not dependent on a particular encoding. For efficiency, the Tcl array is converted internally into a C array with 256 slots, one for each byte value. In fact, the previous example defines an association for the byte 0x26 (38 in decimal). In the case of the latex target, for instance, it could have been defined like this: 
set aida_map(\x26)   "\\&"
The aida_map array is defined in the global scope, not in a target-specific namespace.

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::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::getDirname] 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. Each time a file is included, the command reflects the directory containing this included file.
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. Note that the encoding can't be set or reset when the parsing process has already started.
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. Note that the encoding can't be set or reset when the parsing process has already started.
All the encodings returned by the Tcl command [encoding names] can be used as output encoding.

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

Writing a new target for Aida

This section is of interest only to developers who want to define a new target for the aida convert and the aida split commands.
Defining a new target amounts essentially to two tasks:
The directory for the new target can be located anywhere on the host machine provided this location is listed in the aida_path variable so that the aida command can find it.
A possible solution is to create a custom library and install the target in this library. For instance, suppose this custom library is named aidalocal in your home directory and you want to define a new target for a hypothetical format named 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 20 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
defaultExtension

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 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.
Conversely, not all targets support the attributes above.

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

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

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.

The defaultExtension callback

The syntax of the defaultExtension callback is: 
proc trgt::defaultExtension {}
This proc must return a string which defines the extension used to build the default name of the output file. If no such proc is defined, the target name is used as a default extension. The latex target, for instance, defines this proc to return .tex (otherwise the extension would be .latex which is not appropriate).

Hooks

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

Conversion hooks

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

proc html::postConvertHook {} {
	# Definition here
}
There is an example of a postConvertHook in the man target.

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
}

Target specific features

This sections contains information about extra features provided by some targets. Each target can define, via additional header parameters, some settings which are relevant only for this target.
You should usually declare them, if necessary, using the target-specific syntax for header parameter declarations. For instance, the latex target has a DocClass parameter which specifies the document class of the output file. You can set it to the desired value like this for instance: 
:DocClass:latex:    "book"
All these parameters have a default value. They are described in the sections below.
Typically the value of these parameters can be set in the header of the Aida input file or, at a higher level, in a configuration file like ~/.aidarc/default.tcl.
In order to know which settings are currently defined for the various targets, the following commands can be useful: 
aida info parameters ?target?
aida info attributes ?target?
Used with the -q option, the information is displayed in a more compact form. Here is, for instance, an instruction to display only the settings pertaining to the latex target: 
aida info -q parameters latex

Target html

The html target supports a Charset header parameter used to build a <META> tag in the header of the output document, indicating the character set used. The default value for this parameter is the output encoding. There should be no reason to change this.
Recall that the AddHeader parameter can be used to declare strings which will be inserted verbatim in the header of the Html document (see the Reserved parameters section). Here is an example: 
:AddHeader:html:   <STYLE>body,td,p{font-family:arial,sans-serif}</STYLE>
Version 1.4.2 of aida introduced a new header parameter called EscapeVerbatim to escape the opening tag symbols < inside verbatim blocks in order to prevent the tags from being interpreted by the browsers. With most browsers, any HTML tag is interpreted even if it is found inside a PRE environment. If this parameter is set to 1 (which is the default), the opening < symbols are converted to the &lt; entity with the effect that the tags are displayed verbatim instead of being interpreted. To turn this feature off, set the parameter to 0 like this: 
:EscapeVerbatim:html:     0

Target hyperref

The hyperref target supports several header parameters used to declare some characteristics of the PDF document which will be generated from the output file (which is a LaTeX file using the hyperref package).
Since the hyperref target produces a LaTeX file, it inherits the parameters supported by the latex target.
The BaseUrl header parameter is used to build the \hyperbaseurl macro. It can be left empty by default.
The following parameters let you set the Pdf document options: Here are other parameters which can be defined for the \hypersetup macro (they are all empty by default):
The MakeTitle parameter has the same signification as with the latex target.

Target latex

The latex target supports several header parameters useful to specify the preamble of the output LaTeX document. The DocOptions parameter specifies the options to declare in the \documentclass macro. Its default value is "a4paper,10pt". The DocClass parameter specifies the class of the document. Its default value is "article".
Here is an example: 
:DocClass:latex:        book
:DocOptions:latex:      legalpaper,twocolumn,11pt
This will produce the following macro: 
\documentclass[legalpaper,twocolumn,11pt]{book}

The RefText parameter is a string used to build the references produced by the ((rf rf)) pair of tags. Its default value is: 
"%s (see section~\\ref{%s} p.~\\pageref{%s})"
The Packages parameter specifies the packages to include with \usepackage macros. Its value takes the form of a list with an even number of elements: each pair of successive elements specifies the name of the package and its options (if any) respectively. The default value is 
graphicx dvips makeidx ""
With this setting, the preamble of the output document will contain the following LaTeX macros: 
\usepackage[dvips]{graphicx}
\usepackage{makeidx}
To be more precise, the value of this parameter is interpreted as a Tcl dictionary. The AddPackages parameter lets you declare additional packages. It has the same syntax as the Packages parameter.
Here is an example: 
:Packages:latex:        makeidx "" babel "french" inputenc "applemac"
:AddPackages:latex:     ifthen "" fontenc "OT1 T1"
:AddPackages:hyperref:  multicol "" fancyhdr "" fontenc "LGR T1"
This produces the following output with the latex target: 
\usepackage{makeidx}
\usepackage[french]{babel}
\usepackage[applemac]{inputenc}
\usepackage{ifthen}
\usepackage[OT1,T1]{fontenc}
\usepackage{graphicx}

These parameters might look redundant: in fact, the Packages parameter is meant to declare required packages (possibly at a configuration level) and the AddPackages parameter to declare additional packages in a particular document.
The MakeTitle parameter tells Aida to build a \maketitle macro and define the related \title, \author, \date macros based on the Title, Author and Date header parameters respectively (if they are defined). The default value is 1. If you do not want a \maketitle macro being inserted at the beginning of the document, add the following header declaration: 
:MakeTitle:latex:    0
Here is an example: 
:MakeTitle:latex:    1
:Title:latex:        Romeo and Julietta
:Author:latex:       William Shakespeare
:Date:latex:         \today
This will produce the following code in the output file: 
\title{Romeo and Julietta}
\author{William Shakespeare}
\date{\today}
\maketitle

Target man

The man target supports a few parameters regarding the section of the man page and its header and footer.
The following parameters are available:
FontStyle
a logical value (1 or 0) telling whether the styles (like italic, bold, typewriter) should be rendered via a font style (i-e, technically, using the .Bf macro) or using enclosing marks. The default value is 0, which means using enclosing marks (see the ItalMark, BoldMark, TTMark parameters to specify the marks).
ItalMark, BoldMark, TTMark
the enclosing marks to use to represent italic, bold face and typewriter type styles. The default values are respectively an apostroph, a double apostroph and a back quote. These marks are used only if the FontStyle parameter is set to 0.
ManSection
The number of the man section where this man page will be kept. The default value is 1.
ManVolume
The middle part of the manual page header (like "BSD General Commands Manual"). The default value is "".
ManSystem
The name of the operating system the man page or subject source is developed or modified for (it is printed in the bottom left and right corners of the footer of the manual page). The default value is "".
Note that the Title parameter, if defined and not empty, is used as the name of the subject of the man page. It must be defined as a target specific parameter. For example: 
:Title:man:    aida

Target markdown

The markdown target defines several header parameters concerning syntax variants.
The HorizRule parameter lets you specify the marker for horizontal rules. In markdown syntax, you can produce a horizontal rule tag by placing three or more hyphens, asterisks, or underscores on a line by themselves. If you wish, you may use spaces between the hyphens or asterisks. For instance, possible values are: 
* * *
***
*****
- - -
The default value is "----".
The EmphMark parameter lets you specify the symbol used to mark italic style. The possible values are "*" or "_". The default value is "*".
The StrongMark parameter lets you specify the symbol used to mark bold style. The possible values are "**" or "__". The default value is "**".
The CodeFence parameter lets you specify the symbol used to delimit code blocks. The possible values are "```" or "~~~". The default value is "```". Introduced in version 1.4.3.
The ExtendedSyntax parameter lets you enable or disable the extended markdown syntax for tables, code blocks, description lists, etc. The default value is 1. Introduced in version 1.4.3.
The UnderlineSection parameter lets you specify the style used to mark the sections of level 1 and 2 (section headers corresponding to the tags s1 and s2). If the parameter is set to 1, the underline-ish style is used as in 
Alt-H1
======

Alt-H2
------
Otherwise they will be marked using # and ## respectively. The default value is 1. The UnderlineSection parameter was introduced in version 1.4.2 of aida.

Target mediawiki

The mediawiki engine builds a table of contents automatically as soon as there are more than three section headers in the document. This has two shortcomings:
  1. one cannot control the depth of the table of contents.
  2. the sections are numbered (which causes duplicate numbering if NumberSections parameter is on).
If the NativeToc header parameter is set to 0, Aida builds its own table of contents instead of the automatic one. The default value of this parameter is 1.

Target pmwiki

No specific parameters are defined by the pmwiki target.

Target text

The text target defines the following header parameters:
CommentPrefix
the string to use to mark the commented lines. The default value is "> ".
ItalMark, BoldMark, TTMark
the enclosing marks to use to represent italic, bold face and typewriter type styles. The default values are respectively an apostroph, a double apostroph and a back quote.
ListWrap
a logical value (1 or 0) telling whether the list elements should be wrapped or not. The default value is 1. It can be useful when you want to preserve the text layout in a list element.
PageWidth
the page width, i-e the maximum number of characters on each line when the text is wrapped. The default value is 80.
UnderlineTitles
a logical value (1 or 0) telling whether the section titles should be underlined or not. The default value is 0. If this option is set to 1, first level sections are underlined with "=" symbols and the others with "-" symbols.

Target trac

No specific parameters are defined by the trac target.

Compiling Aida from sources

Compiling the aida command from the sources should not be a problem on 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). If Bison version 2.4 or greater is not available, then the tracing options will be disabled.
The compiling process is driven by a Makefile. It is quite standard and can be performed by the following steps:
  1. retrieve the most recent aida sources (see the Download section).
  2. go to the top directory containing the sources (i-e the directory containing the file configure.ac).
  3. generate a src/config.h.in file with the command: 
    autoheader
  4. generate the configure script with the command: 
    autoconf
  5. execute the configure script with the command: 
    ./configure
  6. compile the sources with the command: 
    make
  7. install the binary and the library with the following command (you must have administrator privileges): 
    sudo make install
By default, the binary is installed in ${prefix}/bin and the library in ${prefix}/share/aida/VERS where VERS designates the version number (currently 1.4.3). The default for ${prefix} is usually /usr/local.

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

Download aida

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

License

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

Last updated 2019-07-08 09:41:09