Using Built-In Help


One of a series of tutorials about Scheme in general
and the Wraith Scheme interpreter in particular.

Copyright © 2011 Jay Reynolds Freeman, all rights reserved.
Personal Web Site: http://JayReynoldsFreeman.com
EMail: Jay_Reynolds_Freeman@mac.com.


Wraith Scheme has a good deal of help available from within the program itself. The purpose of this tutorial is to describe the various kinds of built-in help -- where they are, what they do, and how to get at them.


Let's start with the obvious: There are these tutorials themselves. Obviously you have found at least one of them. They are accessible from the Tutorials Menu in Wraith Scheme. Using any menu item there should open a tutorial in Safari, where you can browse through it in one window while you try things out in Wraith Scheme. The simpler tutorials tend to be nearer the top of the list of menu items; the more complicated ones are nearer the bottom.

The tutorials are intended to be short, focused discussions of particular aspects of either the Scheme programming language or the Wraith Scheme program. I hope they will be particularly useful to people who do not know much about Scheme, or who have not had previous experience with a programming language interpreter like Wraith Scheme.


Several other built-in files can be found via the Wraith Scheme Help Menu. They all open in Safari, like the tutorials.

Help Menu

The Help Menu, full size.


First among them is the Wraith Scheme Help File, which is both a manual for the program itself and a description of how the Wraith Scheme implementation of Scheme differs from the "R5" standard. It also contains an historical overview of the history and development of Wraith Scheme, a modest list of references for further reading, and a little bit of whimsy. The Wraith Scheme Help File has a substantial table of contents, uses plenty of hyperlinks, and is set up as one big file rather than many small ones, so that you can easily use the Safari "search" window to find all instances of any term of interest. It is where you should turn for more detailed information about the operation of the Wraith Scheme program than is provided in these tutorials, and for a systematically organized discussion of any of the many enhancements above and beyond the R5 standard, that Wraith Scheme provides.


The next item in the Wraith Scheme Help Menu is the Wraith Scheme Dictionary. It provides a description of every one of the publicly documented macros and procedures in Wraith Scheme, including all of the ones from R5 and all of the enhancements. Each entry describes what arguments, if any, the procedure or macro requires, describes the result it returns and any side effects it may have, and provides a few simple examples of how to use it. Furthermore, for the enhancements, the entry provides a brief indication of why I thought the enhancement was desirable. The Wraith Scheme Dictionary also includes a glossary of many of the specialized terms used in Scheme, in Lisp-class programming languages, and in the Wraith Scheme program.

A note about terminology: Where the R5 report uses the term "macro", I generally use the term "special form", which is well established in the Lisp and Scheme community and means essentially the same thing. The reason for that is that one of Wraith Scheme's enhancements is an older macro system that is different from the one described in the R5 report, but which is much like the macro systems used in earlier Lisp and Scheme implementations.

If you have no idea what macros and special forms are at the moment, don't worry. I will go into more detail about them in subsequent tutorials.

The Wraith Scheme Dictionary is organized alphabetically, with hyperlinks, and is set up as one big document so that it is easy to search. Incidentally, the waffle-wording about "publicly documented ..." refers to the fact that Wraith Scheme does contain a number of procedures and special forms that I have not documented. Typically they are auxiliaries for some major subsystem of Wraith Scheme, such as the compiler. They are certainly not secret -- after all, Wraith Scheme is open-source -- but they are of little use beyond their specific domain, and are likely to change substantially from time to time, as I rewrite things. Therefore I do not document them.

Well, actually Wraith Scheme does have a few whimsical procedures of more general interest built in, for the adventurous to search for. There is nothing that will bite you, but a few things that are fun. Enjoy ...


The third item in the Wraith Scheme Help Menu is the Wraith Scheme Internals document. This is a rather technical manual describing how Wraith Scheme works. It is likely to be of interest only to Lisp and Scheme fanatics, to people who want to work with or modify the open-source source code of Wraith Scheme, and to the terminally curious. I myself find it handy, when I have forgotten how something in Wraith Scheme is supposed to work. This document also has a good table of contents, hyperlinks, and a single-file layout.


The Wraith Scheme Help Menu contains a submenu, Source Code Examples. Its menu items open various files of Scheme and C++ source code that are stored within the program. These flies mostly demonstrate particular features of Wraith Scheme. Each file contains considerable internal documentation about its use and purpose, and some also refer to specific passages in the Wraith Scheme Help File.


The last item in the Wraith Scheme Help Menu opens the version of the README File that applies to that particular release of Wraith Scheme. Its content will vary from version to version, but it will in general provide information about requirements and properties of the release in question.


Several forms of help are available while you are typing in the Input Panel. The first is command name completion, which is similar in operation to the spelling-completion mechanisms that many word processors provide. Suppose you are typing in the input panel, and have started to type the name of a Wraith Scheme procedure or special form. Suppose you cannot remember how it is spelled, or don't want to bother with typing the whole thing. Press the "escape" key (which has the text "esc" on it on most keyboards): If what you have thus far typed is correctly spelled, then Wraith Scheme will either complete the typing for you, if there is only one possibility, or will present a drop-down menu of choices if there is more than one way to complete the name.

For example, if you type "eq" and then press escape, you will get a drop-down menu containing "eq?", "equal?" and "eqv?", for you to choose from. On the other hand, if you type "call-with-c" and then press escape, there is only one possible completion, and Wraith Scheme will finish typing "call-with-current-continuation".

The next two images show what happens when you are typing "call-with-current-continuation", and press the "escape" key at various times in the process.

Typing some text, with completions.

Typing some text, with just one completion.


Wraith Scheme provides command syntax information for all its procedures and special forms, by a variant on the mechanism used for command name completion: If you are typing one of their names and press "option-escape", you will again get either a drop-down list or a typed completion, but it will be longer and will show what arguments, if any, are expected.

Thus if you type "eq" and then press option-escaped, you will again get a three-item drop-down menu, but the entries in it will be "eq? <object> <object>", "equal? <object> <object>", and "eqv? <object> <object>". If you type "call-with-c" and press option-escape, the text will complete to "call-with-current-continuation <procedure of one argument>"

The next two images show what happens when you get command syntax information for "vector-set!".

Typing some text, for syntax information.

Typing some text for syntax information, with completion.


There is also detailed information about documented procedures and special forms available from the Input Panel. When you have typed the full name of one -- no completion here, you must have the entire name correctly typed out -- select the whole name by one of the usual Macintosh methods and press command-option-F. Safari will then open the Wraith Scheme Dictionary to the entry for the selected text. Command-option-F is the keyboard equivalent of the "Find in Wraith Scheme Dictionary" menu item of the "Find" submenu of the Wraith Scheme Edit menu. Note that you can select text in the Main Display Panel, so this feature will work there as well as in the Input Panel.

For example, in the next image, someone -- possibly me -- has forgotten what the syntax is for Scheme's "dynamic-wind" procedure, and has selected its name in the Main Display Panel.

A procedure name selected in the Main Display Panel.

Then, on pressing command-option-F, the Wraith Scheme Dictionary opens up in Safari at the entry for "dynamic-wind".

Dynamic Wind in the Wraith Scheme Dictionary.


Wraith Scheme has tooltips for just about everything. Move the cursor over something you are curious about, and see if one pops up. Most of them are not quite as coy as the example shown in the image below.

A tooltip.


Finally, there is a way to get information that might be a little advanced and confusing for newcomers to Scheme, but I will mention it here anyway, in case you have previous Scheme experience but are new to Wraith Scheme itself. One of Wraith Scheme's enhancements, above and beyond the R5 Scheme standard, is the procedure "e::inspect" ("e for enhancement"), which prints out a low-level description of its single argument, and then returns that argument. You can wrap a call of "e::inspect" around any Scheme object or procedure to learn something about it, and since the procedure returns its argument, you can do that in the middle of a section of code without changing how it operates. Here is a simple example of using "e::inspect" all by itself, in the Wraith Scheme interpreter, to inspect the number forty-two.

The long line of text output is what "e::inspect" printed. It tells you a good deal about "42", possibly more than you wanted to know, and you will have to read a good deal more Wraith Scheme documentation to find out what it all means, but at least it is there. The "42" in the last line of the example is the return value from "e::inspect", printed out by the Wraith Scheme interpreter itself.


Come to think of it, there is one more built-in mechanism for getting help. My EMail address appears in many places in the Wraith Scheme documentation: If you have a question you cannot answer otherwise, you can always write and ask me about it.


-- Jay Reynolds Freeman (Jay_Reynolds_Freeman@mac.com)


Wraith Face