Using the Document Viewer

• Introduction
• Navigating
• Notational Conventions
• Copy & Paste
• Executable Examples
• Interactive Documents

Introduction

However, the documents also contain interactive code execution features, which requires direct communication with the running Smalltalk system. A feature which was not at all possible at times when the ST/X documentation was initially written (mid 90's, when JavaScript was not even invented). Therefore, we wrote our own implementation of an HTML renderer, which supported what was more or less state of the art at that time. As we do not plan to go into the browser business, and the documentation viewer fullfills our needs for online manual presentation, we did not and don't plan to put more effort into further development of the viewer. Therefore, it might look a bit outdated and also does not support all those fancy new features (stylesheets, for example). It also has a lot of bugs in its layout engine (tables, for example). It is still (after 25 years !) a preliminary implementation of a help viewer.

Summary: you can use another viewer for a slightly better look, but you will not get the interactive experience.

Navigating

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

Cross references within this documentation usually include the title of the referenced section or chapter enclosed in quotation marks (e.g., see "What's 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 code, constants, class names etc. are identified by a courier font, such as

... the UndefinedObject class ...

... 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 ...

... the #'foo_bar'-message does this and that ...

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

Like other code fragments, executable examples are layed out in a fixed (Courier) font but rendered in a different (darkened red) color.

    Transcript topView raise.
    Transcript showCR:'hello world'

The help viewer will catch errors occurring in those examples and show a warn box. Examples which produce such an error by purpose (to demonstrate error behavior), can also be copied into a workspace and executed there (right-click on the example's text to get a popUp-menu).
Try:

    5 / (3 - 3)

Programmed halts and breakpoints will also bring you directly into the debugger.
Try also:

    self halt

An example's text can also be copied to a workspace as follows:

• place the mouse-pointer over the example
  
• press the right (or middle-) button for a popup menu
  
• select the "Copy Example's text" item
  
• paste the text in a workspace window

alternatively, the "Open Workspace on Example's Text" menu item will open a new workspace which contains the example.

In the workspace, you may want to try variations of the example (trying different parameters, for example).

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)

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

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

Interactive Documents

or:

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 help viewer will show the underlying code in a box instead.

Read the SECURITY WARNING above

Copyright © 1995-2016 Claus Gittinger Development & Consulting, all rights reserved
Copyright © 1996-2016 eXept Software AG