Getting help: Documentation & explanations
(February 2001)
It is difficult to present simple standard documentation for Mesquite for two reasons: the system is large, and its features change depending on what is installed and in use. This, we anticipate, will cause at least occasional confusion for users. It is the cost of the system's flexibility. In an attempt to counterbalance Mesquite's complexity and mutable interface, we have built a diversity of information sources to help you understand what calculations are available and how to implement them.
We encourage you to explore the example files provided. By opening them with Mesquite, you will see by example what Mesquite can do.
Web pages and explanation areas
Mesquite's documentation is mostly in the form of HTML (web browser) pages, either stable pages, or pages composed by Mesquite while it is running. The stable HTML pages are mostly in the docs subdirectory of the Mesquite_Folder directory. The Mesquite-composed HTML pages are in a directory called ".Mesquite_Prefs" , which may reside in different places depending on your operating system. If you can find these pages, you might want to store a bookmark, or alias, or shortcut to one of them so that you can find them again without going through Mesquite.
Mesquite also provides on-the-fly documentation in the form of explanations temporarily appearing in the explanation area at the bottom of windows. These explanations may concern menu items, tools, or other objects.
How to discover what you could do and how to do it?
This page and those linked to it serve as the general manual for the Mesquite system, but it won't tell you about the details of particular calculations.
When Mesquite is running, it presents in the Help menu various choices to see HTML pages. In the Help menu are the following menu items.
- Mesquite Manual. This links to the home page of the manual, introducing you to the basic operation of the Mesquite system.
- Modules Installed. This takes you to some information pages for all of the modules currently installed. These pages are composed by Mesquite when it runs, based on information it finds in the modules themselves. 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 also by touching on the name of the module in the Module tree view of windows (available by touching on the Modules tab of the window's information bar).
- Keyword Search...This 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.
- Scripting Commands... This takes you to a page summarizing available scripting commands, in general and for the individual modules.
- Documentation pages for installed packages. A series of items in the Help menu (e.g., "Basic Mesquite Package") take you to documentation for installed packages. A package is a group of modules that are distributed or function as a unit. You can also get to these pages by touching on the package banners in the Mesquite startup window.
- Modules view. The "Modules" tab of the window information bar shows the set of modules currently active in the analysis and or graphics shown in the window. This is shown as a tree of modules employing other modules (a bureaucratic hierarchy!). If you pass the cursor over a module name, an explanation for it appears in the explanation area at the bottom of the window. If you touch on the name of a module, a menu will appear with choices to show more information (if available). If there is a special manual for the module, an extra label will appear that will link you to the manual.
- Explanation areas
- The explanation area at the bottom of most windows shows explanations for tools and other objects as you use them. If you hold down the Shift key as you select a menu item, an explanation for it will (usually) appear in the explanation area of the frontmost window.
- Menu & Control Explanations pages
- The Menu & Control Explanations menu item of the Window menu of Mesquite causes Mesquite to compose a HTML page summarizing the menu items or buttons for the current window, and to show it to you.
The HTML pages that are composed by Mesquite as it runs are not linked from this central manual because we cannot know in advance where your operating system will place these files.
Thus, if you want to learn about:
- Modules:
- Use the menu items in the Help menu to go to the appropriate HTML pages for modules or packages. You can also get to the HTML pages of packages by touching the banners in the Mesquite startup window (the window named "About Mesquite").
- Use the Keyword search facility in the Help menu
- Open the Modules view of the window of concern (using the tab in the information toolbar) and move the cursor over the names of the modules to see explanations in the explanation area, or touch on their names to go to their information pages composed by Mesquite.
- Menu items
- Hold down Shift as you select a menu item to make an explanation for it appear in the explanation area of the frontmost window.
- Use the Menu & Control Explanations menu item of the Window menu to make a web page summaring the functioning of the menus and buttons for the foremost window.
- Buttons and tools:
- Touch on a tool in the tool palette to make an explanation for it appear in the explanation area of the frontmost window.
- Use the Menu & Control Explanations menu item of the Window menu to make a web page summaring the functioning of the menus and buttons for the foremost window
How to remember or document what you have already done?
With an interactive program with as many options as Mesquite, it can be difficult to remember what options are currently in effect. Three facilities help you keep track of what you've done.
- 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 Windows menu, records commands given and messages relayed to the user.. This text is also saved automatically to a file called "Mesquite Log".
- 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
