This tutorial assumes that you are running cadiz in a mode that permits browsing.
All of the information inferred by the typechecker is available for inspection using the mouse. This includes the structure of formulae, the syntactic categories to which they belong, the bindings of names to declarations, the types of expressions, and the environment of declarations in scope at a formula. Browsing is permitted in the -x, -P and -b modes, where both the specification and the reports are displayed in windows.
The following example specification will be used in explaining browsing. cadiz draws boxes around the inferred contexts of reports, so we can immediately see that there will be two reports in the other window. The reports are revealed in the separate page on correcting errors in a Z specification. This example should be somewhere within the cadiz directories; if you can find it, you can try cadiz -x on it while reading the following, though you might have to do some shuffling of overlapping windows.
Interaction with cadiz involves first selecting a formula to which you want to apply a command, and then choosing the command from a menu.
A formula is selected by pointing with the mouse and clicking button 1. This part is the same as you would do when browsing a web page. In response, cadiz selects the formula using inverse video. Unlike a web page, cadiz doesn't immediately jump off and do something in response to the selection. All it does for the moment is display the syntactic category of the selected formula in the window's title bar. (The font and justification of this text is determined by your window manager.)
Suppose we want to select the equality predicate that is the first constraint in the schema paragraph. cadiz selected the smallest formula around where the mouse was pointing. To select the next larger formula, click button 1 again anywhere within the existing selection.
A further four clicks of button 1 would select the entire schema paragraph.
This is as large as the selection can get. Another click now and cadiz would behave as if there was no existing selection: it would select the smallest formula around where the mouse is then pointing. When selecting formulae that involve lots of sub-formulae, the number of mouse clicks can be minimized by pointing at a part of the formula that involves fewest sub-formulae. In the case of the whole schema paragraph above, two clicks on the schema name is a much less frustrating method than six clicks on the name from which we started.
Returning to the original selection of the reference to Cycle above, press and hold down the mouse's button 2. While this button is held down, a menu of command names appears.
A command is chosen from this menu by moving the mouse to point at the name of the desired command, and then releasing button 2. If the declaration command is chosen, the name of the declaration becomes selected.
Visually, it is as if the selection moves quickly from the reference to the declaration. The process of pressing and holding down button 2 we call inspecting the formula to see what commands are applicable to it. We can now apply a command to the selected declaration, without having to make the selection ourselves. If we choose the first use command, the selection moves back to the previously selected reference. From there, we could choose the next use command, resulting in the following selection.
These commands allow us to trace through all typeset uses of declarations. Some uses are not typeset, such as those implicit in theta expressions and schemas used as predicates. Although implicit uses cannot be selected, cadiz will let you know if any are being skipped over.
The other information that the typechecker infers is of course the types of expressions. Whenever an expression is selected, the menu of applicable commands includes one named type. Choosing the type command causes the type of the inspected expression to be displayed in the other window. For example, the type of the schema in the example is displayed like this, where the components are listed in alphabetical order.
There are many more commands that you will be offered in the button 2 menu, far more than is appropriate to describe here. Details of each command may be found under Z-related commands in the reference manual. Some more that are perhaps worth mentioning here are source text and save source and why not. The source text command generates notation that could have been used to mark-up the inspected formula, and displays it in the left window. The save source command appends that displayed notation onto the end of a text file, making it accessible to your editor. If you are not sure how to mark-up something, using these commands on something similar might help. The why not command may be useful when a command that you expected to appear in the button 2 menu hasn't appeared.
The commands that were described in the previous section were the earliest ones to be offered by cadiz in its development. They established a style of user interface that has remained largely unchanged as many new commands have been introduced. One extension that you will need to know how to use, if you progress to doing proofs of conjectures, is the mechanism for selecting multiple formulae.
Having selected a single formula, hit the x key on the keyboard. This will cause cadiz to draw a cross through the selection.
Now another selection can be made.
This process can be repeated, allowing an arbitrary number of selections to be made, all but the last of which is crossed. These multiple selections are used by non-unary commands. They are also used by many unary commands, where the unary command is applied to each of the selected formulae. Other unary commands, such as the browsing commands discussed above, ignore any crossed selections.
If you decide that a crossed formula should not have been crossed, hit the c key. It clears the crosses in the reverse order that they were made by the x key. The C key clears all crosses at once.
The windows used for browsing by cadiz are instances of a previewer for typeset documents, extended with mechanisms for selections, menus, etc. Like most document previewers, it has commands for requesting the display of a different page, or a different document, searching for occurrences of a textual pattern, magnifying the display, printing the document, and quitting the tool. These commands are in a menu that appears when button 3 is pressed and held down. Using the quit command in any window causes all the windows and cadiz to quit.
When you want to see the declaration that a name refers to, it is generally better to use the declaration command than to search through pages yourself. The page on which the declaration appears will be displayed, with the declaration's name selected. Sometimes that page will be in a different document, for example when declaration is applied to a reference to an operator in the toolkit. This is especially valuable when there are multiple declarations of the same name in the specification (hopefully in distinct scopes), as cadiz will select the right one. Returning to the page where the original reference appears is equally easy: the revert command does that.
As you use cadiz, you will notice that the cursor - the arrow that moves around on the screen as you move the mouse - varies between the following images.
The arrow indicates that at the present time you can make selections, and the question mark indicates that you can get menus.
The spectacles indicate that the page being displayed in this window is incomplete - some more text could yet be added to this page. The arrow and question mark are as above.
The clock indicates that cadiz is busy responding to your previous command.
The hourglass indicates that cadiz is garbage collecting - sifting memory to find some that can be reused. This is often done after a command, while you are thinking about what to do next, but may have to be done several times during a command that requires much computation.
The hand appears if you press button 2 when there is no formula selected. It grips the document that you are viewing through the window, and lets you move the document about. This is useful when more of the page has been used than can be seen through the window. It can also be used to move some pop-ups, as described next.
You will occasionally be presented with other pop-ups besides the menus discussed above.
A dialogue box offers a textual prompt, and you are expected to type in a response. If you make a typing mistake, you can move the cursor back to the error by clicking button 1 (or by using the left and right cursor keys), and then delete erroneous text using the delete key and/or insert new text. Several characters can be deleted at once by sweeping out a selection using button 1 and then hitting delete or typing replacement text. When the response is complete, hit return (or enter on some keyboards). Alternatively, the dialogue can be cancelled by clicking button 2 or 3. A response that fills the dialogue box can continue on additional pages. A selection can be extended to a neighbouring page using the arrow keys.
A switch appears when the mouse is moved off the right-hand end of the scale command in the button 3 menu, and the cursor changes to a hand that moves the switch. The switch can be fixed in a new position by releasing button 3. Alternatively, the switch can be made to go away by moving the mouse off the left-hand edge of the pop-up.
A sub-menu appears when the mouse is moved off the right-hand end of either the file name or printer commands in the button 3 menu. A choice from that menu can be made by releasing button 3 when the mouse is pointing at the chosen item. Alternatively, the sub-menu can be made to go away by moving the mouse off the left-hand edge of the pop-up.