4.2. Application Definition

4.2.1. Application Definition Format

The first definition in an ACD file must be the application definition. This consists of the application: token, the application name with which this ACD file is associated, and a block of application attributes in square brackets. Each attribute is a name: value pair:

application: ApplicationName 
   ApplicationAttribute1Name: "ApplicationAttribute1Value"
   ApplicationAttribute2Name: "ApplicationAttribute2Value"

For example, the wossname application definition has two attributes (documentation: and groups:):

application: wossname 
    documentation: "Finds programs by keywords"
    groups: "Display"

The application name (ApplicationName) is arbitrary but is typically the same as that used for the ACD file name. During program initialisation (see Section 6.3, “Handling ACD Files”) the embInit function is called to associate the C source code with an ACD file and invoke ACD file processing. embInit is passed the name of the ACD file to parse (ApplicationName.acd), e.g.:

embInit("ApplicationName", argc, argv)

This allows multiple ACD files (and therefore command line interfaces) to be developed for a single file of application C source code. embInit does not compare ApplicationName to the string given after the application: token in the application definition.

4.2.2. Application Attributes

The application attributes are used for metadata describing the application itself. They let you set such things as documentation text and the group to which the application belongs. See the complete list and description of the available application attributes (Section A.3, “Application Attributes”.)

The documentation:, keywords: and groups: attributes are worthy of special mention. Their string values are searched by the wossname program which, given a keyword, will return all the applications containing that keyword in the groups:, keywords: or documentation: text.

The groups: string is also used by the seealso application which takes the name of an EMBOSS program and returns a list of the programs which share some functionality with it.

4.2.3. Application Documentation

The documentation: attribute text is a succinct description of application function, printed to the screen when the program is run or when help is displayed (when the program is run with the -help qualifier). Here's the application definition for seqret:

application: seqret 
    documentation: "Reads and writes (returns) a sequence"
    groups: "Edit"

The ACD file above would give the following behaviour at the command line:

% seqret
Reads and writes (returns) a sequence
Input sequence :

If the documentation: attribute is missing then a warning will be issued when you run the program. The string value must conform to certain conventions (Section A.3, “Application Attributes”.) Application Keywords File (keywords.standard)

The permissible application keywords that may be given after the keywords: attribute are defined in the file:


which is installed in the same directory as the ACD files, e.g.:


The file is shown below:

# Application keywords
# Keywords are additional search terms to locate applications
# Valid group and subgroup names are not allowed. Keyword searches are
# expected to include the groups. Keywords defined here and in the
# application keywords: attribute are a few terms to be used where the
# short documentation string is not sufficient to identify an
# application by function.

You will see that no keywords are currently defined. If you add any, one keyword should be given per line following the comment block.

4.2.4. Application Groups

The groups: attribute places the application into groups or subgroups based on its functionality. Programs in the same sub-group generally do similar things whereas programs in the same group but different sub-groups do different things but in the same general area. See the short descriptions of the application groups in the CVS (developers) release (Section, “Application Group Names File (groups.standard)”). The string value of the groups: attribute must obey certain conventions (Section A.3, “Application Attributes”).

The general format is as follows:

application: ApplicationName 
    groups: "GroupName1, GroupName2, ... : SubgroupName1, SubgroupName2, ... "

For example:

application: syco 
  documentation: "Synonymous codon usage Gribskov statistic
  groups: "Nucleic:Codon usage, Nucleic:Gene finding"

Typically just a single group and sub-group is specified. For example, the following ACD file indicates that the application pscan is in the group Protein and sub-group Motifs:

application: pscan 
  documentation: "Scans proteins using PRINTS"
  groups: "Protein:Motifs"

A single group is also commonly sufficient, for example:

application: trimest 
  documentation: "Trim poly-A tails off EST sequences"
  groups: "Edit"
] Application Group Names File (groups.standard)

The application groups have become widely used elsewhere so EMBOSS now uses a standard set of group names which all group names in an ACD file are validated against. The standard is defined in the file:


which is installed in the same directory as the ACD files, e.g.:


groups.standard contains one line for each group string (a valid entry after the group: attribute). Group and sub-group (if specified) are delimited with a ':' (colon) character, and spaces in group or sub-group names are replaced by an underline character ('_'). Each group string also has a short description of what might be expected to be placed in the group. An excerpt from the file is shown below:

# Application groups
Acd ACD file utilities
Alignment:Consensus Merging sequences to make a consensus
Alignment:Differences Finding differences between sequences
Alignment:Dot_plots Dot plot sequence comparisons
Alignment:Global Global sequence alignment
Alignment:Local Local sequence alignment
Alignment:Multiple Multiple sequence alignment
Display Publication-quality display
Edit Sequence editing
Enzyme_Kinetics Enzyme kinetics calculations
Feature_tables Manipulation and display of sequence annotation

If a group and sub-group are specified, for example:

Alignment : Consensus

then the group and sub-group names must not be given singly after the groups: attribute. For example, this is valid:

groups: "Alignment : Consensus"

but this is not:

groups: "Alignment"

If the group string has one level only, i.e. a top-level group, for example:


then please don't add subgroups to it. This, for example, is not valid:

Display : Features

You are strongly encouraged to use the groups structure defined in groups.standard. The EMBOSS developers have found that most things will fit into one or more of these groups. When, however, a completely new category of program is written, please discuss the creation of the new group name in the developers' mailing list (emboss-dev@emboss.open-bio.org).

The group names in groups.standard are reported by the EMBOSS programs wossname and seealso and are checked by acdvalid to make sure the groups specified in an ACD file are defined.