Warning

The current version of the ST/X helpview is a preliminary one. It is unfinished and is known to contain bugs.


Using the document viewer

Navigating

In the text, you will find highlighted items which contain references to other parts of the documentation.

A single click on such an item will locate and show the corresponding part of the documentation.

The help viewer keeps a history of vistited documents; the "back" button returns to the previous document(s).
The "home" button returns you to the top introduction document.

Most documents contain extra navigation buttons located at the beginning of the document. The "prev" (left arrow) and "next" (right arrow) buttons lead you to the previous/next chapter in the same hierarchy level of the documentation.
The "up" (up arrow) button leads you back to the next higher level.

Notational conventions

The documentation uses different font styles to distinguish plain text from variables, code fragments, examples etc. The layout may vary with different HTML viewers and their configuration settings. The documents may also look slightly different in printed form.

Cross references within this documentation usually include the title of the referenced section or chapter enclosed in quotation marks (e.g., see ``Whats new in the documentation'').

Lowercase italic type represents a variable, a placeholder for the text you actually enter. A variable can consist of different characters each time you make the entry. A typical example would be: "someArray at:index".

Italic type is also used when some term is defined in the text, as in:
"an executable example is a code fragment that is executed when clicked upon".

Smalltalk constants, class names etc. are identified by a courier font, such as

... the UndefinedObject class ...
or
... the #at:put: selector ...

This is also true for code fragments or example expressions such as:

	Transcript showCR:'hello world'

To distinguish symbols and message selectors from regular strings or variable names, these are typically prefixed by a "#" character, as in:

... the #new message creates a new instance ...

Filenames are also shown in a monospaced font, but have additional quotes around them, as in "/usr/lib/smalltalk/smalltalk.rc".

Keys that are labeled on your keyboard with more than one character, such as the "RETURN" key, are identified by all uppercase letters in a bold courier font. Keys that you are to press simultaneously or in succession are linked with a hyphen (e.g., press "SHIFT-ALT-d").
If multiple keys are to be pressed in sequence, no hyphen is shown (e.g., as in "COMPOSE a *").

Executable examples

In some sections you will find executable example code. You can execute those examples (right out of the helpViewer) by clicking on them.

Like other code fragments, executable examples are layed out in a fixed font but highlighted with a different color.

    Transcript topView raise.
    Transcript showCR:'hello world'
The help viewer will catch errors occurring in those examples and show a warnBox instead. Examples which produce such an error by purpose (to demonstrate error behavior), should be copied into a workspace and executed there.
Try:
    self halt
Executable examples are a special feature of the ST/X help viewer. Clicking on them will have no effect if you use Mosaic, Netscape or any other HTML reader.

An examples text can be copied to a workspace as follows:

SECURITY WARNING:

Be careful with documents provided by untrusted people:
Since the examples are executed by your running smalltalk system, a bad guy can place example code into a document, which could be harmful to your (smalltalk-) system.

Always read and understand what is going on the code example, before executing it.

In the help viewer, you can disable example execution, to avoid executing any code by unintended clicks.

In non-Smalltalk HTML readers, command execution is not possible and there is no danger whatsoever with examples.

Dynamic links (executed hrefs)

A link may be defined to execute some smalltalk action; from a technical point of view, they are much like executable examples, but the dusplayed text is different from the executed code.

Click here to open a browser.
Or click here to ask for a class and open a browser there.
Click here here, to browse the ApplicationModel class.

The above security warning also applies to this type of code execution.

Interactive documents

In some sections, you will find interactive elements, such as buttons or input fields. These fields can be filled out and actions are performed when the button is pressed.
For example:
Enter the name of a class here: To browse, press: .

or:

Enter the name of a class: and selector: press: .

For these fillout forms, the same security dangers are to be considered as for executable examples (even more, since you do not see the underlying code). Therefore, these can also be disabled in the help viewer when reading untrusted documents. If disabled, the helpviewer will show the underlying code in a box instead.

Read the SECURITY WARNING above
The ST/X documents as provided here were of course written with great care to avoid doing any harm to your smalltalk environment - however, even these documents could have been modified by someone else at the time you read them ....
Doc $Revision: 1.10 $ $Date: 2000/02/22 10:44:56 $