AIDAMAN(1)

NAME

SYNOPSIS
        	aida <subcommand> [options]
        	aida (-h|-v)

The available subcommands are: 'convert, help, info, split'.

DESCRIPTION
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 <http://sourceforge.net/projects/tcl> 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.

OPTIONS
The command has a set of global options available for all the subcommands:
•   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.
Each subcommand has its own set of options described below.

  The convert subcommand
[1] 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:
•   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:
'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.

  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.

  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.

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

AUTHOR

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

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

SEE ALSO
aidamarkup(1)