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

Documenting Mesquite for users

(August 2005)

To document Mesquite for users and programmers is difficult because of its size and modularity. The former means the documentation is incomplete; the latter means that the documentation can be difficult to find. See the page from the user's manual introducing documentation and explanations. Basically there are four main sources of documention as to what users could do:

1. The central user's and developer's manuals. The user's manual accompanies Mesquite, in Mesquite_Folder/docs/mesquite/manual.html. The developer's manual begins here.
2. Whatever manuals might belong to the individual modules. These can be found via the Modules Loaded menu item in the Help menu of Mesquite.
3. The documentation pages for installed packages. These can be found by touching on the banners in the Mesquite startup window, and by the list of packages in the Help menu.
4. The documentation that Mesquite composes automatically.
   1. Information pages for the modules and scripting commands. These pages are composed by Mesquite, based on information it finds in the modules themselves, once each time it runs when a menu item is selected that would take you to a web page. They include a basic explanation of what the module does, explanations of menu items belonging to the module, and its scripting commands. These pages are available via the Modules Loaded menu item in the Help menu, and by touching on the name of the module in the Employee tree view of windows.
   2. Menu and button explanation pages. The Menu & Control Explanations menu item of the Window menu of Mesquite cause Mesquite to compose a web page summarizing the menu items or buttons for the current window, and to show it to you.
   3. Explanation area of windows. At the bottom of most windows are two text areas. The top one is white and shows footnotes and other annotations for the data, taxa, trees, and so on. The bottom one is yellowish and shows explanations for tools and menus and explanations generated automatically by Mesquite describing objects like trees and data matrices. Mesquite will show an explanation for a menu item in this explanation area if you select the menu item while holding the option or ALT key.
   4. Keyword search. The Keyword search item in the Help menu provides a currently-primitive facility to search among the names and explanations of all of the installed modules to find a keyword. You could, for instance, search for "simulat" to find all of the modules that might have to do with simulations.

A second issue is for users to know what they have done. There are three facilities to help here:

1. Information bar of windows. The information bar has various tabs that control alternative views of a window's contents. Some of these give information about the current calculations, the parameters in use, and details about the modules in use by the window.
2. The log window, available by selecting Mesquite Log in the Window menu. This text is also saved automatically to a file called "Mesquite log".
3. Auto-scripting for file saving. When Mesquite saves NEXUS files, it automatically constructs a script that attempts to return an analysis to its current state. This not only allows a user to save a snapshot of an analysis, but the script itself can also be inspected to determine current parameters (in case that's not evident otherwise). Snapshot scripts can also be seen for individual windows, by selecting the appropriate item in the Scripting submenu of the Windows menu.