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
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(" |
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.
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.
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:
%seqretReads 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”.)
The permissible application keywords that may be given after the keywords: attribute are defined in the file:
keywords.standard |
which is installed in the same directory as the ACD files, e.g.:
.../emboss/emboss/emboss/acd |
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.
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 4.2.4.1, “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
plot"
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" ]
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:
groups.standard |
which is installed in the same directory as the ACD files, e.g.:
.../emboss/emboss/emboss/acd |
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:
Display
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 ([email protected]).
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.