General Modularity Example Module Projects & Files Commands & Scripting Windows Menus Charts Tables Buttons & tools Trees and Taxa Characters & Models Documentation General Utilities Documentation for users Automatic documentation system Command explanations Menu and control explanations class CommandChecker

Automatic documentation system

(August 2005)

Because Mesquite is modular and which modules are installed will vary, there can't be a single fixed set of documentation or the system. Additionally, because the user interface (e.g. menu items, buttons) will vary depending upon just what modules are currently participating in a calculation, it would be difficult to write a manual even for a fixed set of modules.

The CommandChecker class is responsible for constructing the auto-documentation.

To help the user under such difficult circumstances, Mesquite has systems to generate documentation automatically to characterize the current set of modules installed and the current user interface. The programmer of modules can support this by:

1. overriding the getExplanation, getAuthors, getCitation and other methods of MesquiteModule, as appropriate, to provide information about the module
2. using the standard approach to checking command names within doCommand methods, employing the CommandChecker passed, and entering informative explanation strings and parameter strings in the call to CommandChecker.compare. The example module shows this.

How the autodocumentation summarizes commands

The auto-documentation makes summaries of various sorts, but one its major duties is to summarize the commands (see commands) understood by Commandable objects. It does this by taking advantage of the doCommand method's double duty as both the method that executes commands, and the method that provides documentation on the commands. The doCommand method does this by using the CommandChecker object passed that can, when properly arranged, go through the doCommand method harvesting information about the commands understood. This is explained in CommandChecker, and an example module shows how the doCommand method needs to be designed to accommodate this.

Pages summarizing modules and commands

A series of pages summarizing installed modules and their basic commands are composed by Mesquite once for each time the system is run, when one of the menu items taking you to a web page is chosen (this composition happens when the "One Moment Please" window is displayed). These pages are placed within a directory ".Mesquite_Support_Files" which may be placed in your home directory or where your preferenes and settings are stored. The reason they are composed once for each time the system is run is to ensure that the web page contains the latest list of installed modules (yes, it would be better for the system to keep a record of modules installed the last time the web pages were composed, and recompose the pages only if there has been a change).

The menu items that will take you to web pages are:

• Mesquite manual (Help menu): The web page that appears is not auto-composed; it is merely the home page of the manual of the Mesquite system. However, by selecting this menu item (if it's the first menu item taking you to a web page) the other auto-composed web pages will be constructed.
• Modules Installed (Help menu): The web page that appears is the auto-composed list of modules currently installed in the system.
• Scripting Commands (Help menu): The web page that appears is auto-composed and contains links summarizing the commands (see commands) understood by the modules and other important objects (such as the windows), as well as the universal scripting commands.
• Menu and Control Explanations (Windows menu): The web page that appears is composed each time the menu item is selected. It is described below.

Pages explaining menus, buttons and other controls

The "Menu and Control Explanations" menu item in the Windows menu will cause Mesquite to compose a web page listing the current menus and menu items that belong to the foremost window, with each listing the explanation for the menu item. These explanations are obtained by calling the doCommand method of the Commandable object of the MesquiteCommand that is attached to the menu item, and passing it a CommandChecker that finds the explanation string tied to the relevant command string.

This web page also shows the images and explanations tied to any user-interface buttons, etc. in the window. These are found by parsing through all Containers and Components of the window and seeing which ones satisfy the Documentable interface (which has a getExplanation method) and ImageOwner interface (which has a getImagePath method).