Documenting Mesquite for users
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:
- 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.
- Whatever manuals might belong to the individual modules. These can be found
via the Modules Loaded menu item in the Help menu of Mesquite.
- 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.
- The documentation that Mesquite composes automatically.
- 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.
- 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.
- 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.
- 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:
- 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.
- The log window, available by selecting Mesquite Log in the Window
menu. This text is also saved automatically to a file called "Mesquite
- 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.
© W. Maddison & D. Maddison 2001-2005