DRAMA Documentation

We have attempted to provide a good set of documentation with DRAMA, but we admit to sometimes having trouble keeping it up to date. To help in this, we generate a large amount automatically from source code comments. Documentation generated this way provides most of the routine and program descriptions available.

Most of the printed documentation is generated from Latex sources through recent documentation is either HTML or MS Word/Power Point. Later documentation is using tools like doxygen for HTML pages (e.g. C++ sources)

Automatically generated documentation is generated using one of three tools

wflman (William Lupton's Manual generation utility): This tool was generated at the AAO around about 1989 and later developed further at the Keck Observatory. It generates documentation from file and function headers into Latex, Man, and HTML formats. wflman is well suited for documenting C routines but it no longer being developed.
Javadoc: JAVA's documentation tool - the standard way of generating documentation for JAVA software. Due to its relationship with JAVA, this seems a good way of getting high quaility JAVA documentation. Note that DRAMA's JAVA documentation is NOT generated until the DJAVA library is built (due to the string relationship with JAVA).
Doxygen: This is a public domain documentation tool which works in a similar way to javadoc. We find it particularly suitable for C++ documentation, which is its main use at this point. The AAO will probably move from wflman to doxygen for all new code.

If you have not already been there, the full set of on line documentation can be found here. This includes the current page, C API, C++ API, JAVA API, Utility Program and TCL command descriptions.

The full DRAMA release includes this set of Web pages, a set of pages for use with the unix man command and the Latex sources of the full documentation set.

There are two overview documents on DRAMA. The larger more complete version (2015) and a handout version (2019).

There is a draft of a book on DRAMA. This is available in PDF format. This document is NOT under active development and many parts have not yet been completed, but it is a good start to programming in DRAMA. The examples have not yet been sorted out on line, but the examples from the course mentioned in the following paragraph are similar.

There is a document on DRAMA2. The more modem C++ interface. This is available in PDF format.

The AAO can give a course on DRAMA. Please contact us if you want one.

The following Postscript documentation is available for components of DRAMA.

DRAMA Software Organization: This document introduces the Organization of the DRAMA software and management of software Versions.
Guide to Writing Drama Tasks: This document is an in depth guide to how to write programs using DRAMA.
The Error Reporting System: The DRAMA Error Reporting System provides techniques for reporting errors in a consistent manner. It is independent of any user interface or message technique.
The Dits Specification: Dits is the software package which implements the basic tasking structure, allowing distributed tasks to communicate in a reliable and efficient way.
The Message Code System: Implements a portable Message/Error code system allowing distributed tasks to pass integer error codes between machines and relate those codes to appropriate text. It is compatible with the VAX/VMS message code system.
The Self Defining Data System: SDS is used by DITS to move data between machines of various architectures, making allowances for the various machine specific ways of storing numbers and characters. The user may use SDS directly or via the ARG package supplied as part of SDS. SDS is capable of being using Standalone for storage and transfer of data between machines of different architecture.
The Interprocess Message Passing System: IMP is the underlining message system used by DITS. It provides the fastest possible techniques for sending messages between processes on the one machine while also providing an almost transparent interface for sending messages to tasks on other machines across a network. IMP is not normally used directly by DRAMA task authors.
The Generic Instrumentation Task Specification: This document describes the requirements imposed on AAO instrumentation tasks and the package used to implement such requirements. It shows how inheritance techniques can be used in DRAMA. In addition, several utility routines are specified.
Guide to Creating Makefiles for Drama programs: DRAMA uses an imake based scheme (similar to that used by X11) to create Makefiles. The technique allows, for example, the one Make configuration file to be used for Unix, VMS and VxWorks based systems. It also allows Make configuration files to be independent of the location of DRAMA
DTCL - DRAMA Interface to TCL: This document describes the DRAMA Interface to TCL and TK (See the book Tcl and the Tk Toolkit by John K. Ousterhout (Addison-Wesley 1994)). DTCL provides a way to quickly write high quality user interfaces to distributed instrumentation systems and to prototype DRAMA programs.
DRAMA Utilities Library: This document describes a number of utility programs and routines which may be used by DRAMA programs.
Older DRAMA C++ interface: This document described the DRAMA C++ interface. (don't use for net work, instead use DRAMA2)

Click here for the DRAMA home page and here for the AAO home page.
For more information, contact tony.farrell@mq.edu.au