An application ACD file (see Chapter 5, C Programming) is a self-contained description of the application parameters and definition of the command line interface. It does not require explicit documentation but in some cases, however, it is helpful to add comments to the ACD file. Comment lines begin with # and continue to the end of the line (see Section 4.1, “Introduction to ACD File Development”).

An ACD file includes an application definition describing the application itself, and one or more data definitions describing the parameters. Definitions have attributes which describe the application or parameter in detail. Data definitions are organised into sections in the file such as "Input", "Output" and so on. The ACD file is parsed when generating the application documentation. The components used include:

Therefore you should ensure that the application ACD file is valid and properly formatted. Various utilities (Section 4.6, “ACD Utilities”) are provided for testing, validating and reformatting ACD files.

Sections in the application documentation are described in the table (Table 8.1, “Sections in Application Documentation”).

The process for generating the application documentation combines manually written components with parts that are generated automatically (mostly from parsing the ACD file and from the QA tests). The process is largely automated and involves running the autodoc.pl script which generates a part-completed "application template" which you complete by hand.

The application name and index terms is written directly to the application template. However, most of the automatically generated content is kept in "include files" that are generated from template XML include files.

autodoc.pl is included in the EMBOSS distribution under the scripts directory, e.g.

To document a new program, first ensure you have an up-to-date set of programs compiled, and that any programs you've written but which are not part of the main EMBOSS package have had their executable deleted. Otherwise references to them might occur in the automatically-generated "See Also" sections (see above). The ACD file should be complete and validated and QA tests for the application should have been run.

To generate the documentation, autodoc.pl is run on each application you wish to document in turn.

For EMBOSS applications:

For EMBASSY applications:

You should replace PackageName and ApplicationName with something sensible.

The following example assumes you are working in the EMBASSY package myemboss and are writing a program called myprogram. To document the application:

The script will run wossname to check that myprogram really exists, then generate the application template documentation file (for you to fill in) with include directives, plus include files for the following sections:

The include files for the following parts are generated from running the QA test which is why (typically) the QA test should be written before documenting your application:

The application name and index terms in the application template are also set correctly. When all is done the HTML application template is created in:

To complete the application template myprogram.html you add documentation text as follows:

The template is commented enough for you to see how to fill it out.

autodoc.pl also generates documentation in plain text format (with all the text from the include files) that is used for manual pages and is displayed when running:

Once you complete the template and save it, the documentation (in HTML and plain text formats, plus include files) is ready for submission to the EMBOSS authors for publication online. Other online files that reference the new documentation, such as indices of applications (http://emboss.open-bio.org/rel/dev/apps/), will be updated automatically.

The sections in the EMBASSY package documentation are described in the table (Table 8.2, “Sections in Package Documentation”).

The process for generating the EMBASSY package documentation is similar to that for applications. Manually written components are combined with automatically generated text. The process again involves running the autodoc.pl script which generates a part-completed package template which you complete by hand.

To document a new package, first ensure you have an up-to-date set of programs compiled. To generate the documentation run autodoc.pl on the package:

The following example assumes you have created a new EMBASSY package called mypackage. To document the package:

The script will generate a template documentation file (for you to fill in) with include directives, plus include files for the following sections:

The EMBASSY package name and index terms in the template are also set correctly. The HTML application template is created in:

To complete the template mypackage.html add text in the places indicated:

Again, the template is commented so it is clear where to add the text.

autodoc.pl also generates documentation in plain text format (with all included text) that is included in the README file for the package.

Once you complete the template and save it, the documentation (in HTML and plain text formats, plus include files) is ready for submission to the EMBOSS authors for publication online. Other files that reference the new package, such as the master table of EMBASSY packages http://emboss.open-bio.org/rel/dev/apps/EMBASSYPackagesTable.html, will be updated automatically.