The HELP Facility

# The HELP Facility

In this chapter, we're going to look at Alice's HELP Facility. This can provide a great deal of information about both Alice and Pascal. Indeed, once you understand how to use the HELP facility, you shouldn't really need any more instruction -- HELP should be able to tell you everything you want to know.

To get help, all you have to do is press `[F9]`. If you are doing normal editing, this will summon the Help Menu, a list of areas in which help can be provided. If you are doing something more specialized, pressing `[F9]` will probably give you specific help on what you are doing.

## The HELP Menu

Start up Alice and load the old `squares` program we have been using in our examples. If you press `[F9]` once the program has been loaded, Alice will display the HELP Menu:

Screen Shot helpmen not available

The selections on this menu offer help on various aspects of programming with Alice. For example, choose

>     How to quit Alice

from this menu, and you will get an explanation of how to quit Alice. This explanation will remain on your screen as long as you want. To get rid of it, press the space bar. Alice will go back to the program, with everything the way it was before you pressed `[F9]`.

## Which Key is Which

Press `[F9]` and choose the selection

>     Quick Summary of Keys

This will give you a list of commands and what keys or key sequences execute those commands. This list is enormously useful if you ever forget what you have to press to achieve a certain effect. Of course, you can also find all the commands on menus too.

As before, pressing the space bar will get rid of the help on the screen and return you to normal editing.

## Help on ALICE Commands

If you want more information about a particular command, you can get it if you know what menu holds the command. All the commands of Alice can be found on one or more menus. For example, the SAVE command is found on the Files Menu, as we have mentioned before.

We've already shown how a menu can be used to issue a command. Here's how to use it to get help about a command. Press `[F8]` to get the Files Menu and highlight the `Save` line. Now, press `[F9]`. If you pressed any other key, you would execute the SAVE command, but pressing `[F9]` gives you an explanation of what SAVE does.

Screen Shot savehelp not available

The ``Command line name'' is the name of the command. Later on, we'll describe how you can use this name to execute the command if you don't want to use menus or special key sequences. The ``Associated with Key'' line tells the key or key sequence you can press to issue the command. The ``Found on'' line tells you the name of one or more command menus where the command can be found. Of course, we already know that the SAVE command is on the Files Menu.

You'll notice that the SAVE command comes with a menu that offers help on related topics. You can choose one of these related topics for more information, or choose `Do nothing`. The `Do nothing` selection takes you back to the Files Menu. We don't really want to save anything at the moment, so choose `Do nothing` and you'll get back to normal Alice operation.

By the way, some of HELP's command descriptions do not have a menu the way that SAVE does. If the description does not have a menu, it will just stay on the screen to let you read what is there. When you're finished, press the space bar and the description will go away.

Try this process again. Press `[F8]` to get the Files Menu. This time highlight the selection

>     DOS Command

This is one of the few selections on the Files Menu that we haven't talked about yet. If you press `[F9]` now, you will get an explanation of what the command does.

You can get a description of all the other Alice commands in the same sort of way: calling up a menu on which they appear, highlighting them on the menu, and pressing `[F9]`. We'll talk about the various command menus in the next chapter.

## General Information

Go back to your program for a moment, then press `[F9]` again and choose the selection

>     Getting Started with Alice

from the HELP Menu. You will get the same ``introductory chat'' that you got when you chose

>     What is Alice all about?

from the Starting Menu. Work through this chat now -- you will have seen most of the material before, but it's good practice and a good reminder.

When you have come to the end of the chat, press `[F9]` again and this time choose

>     Features of Alice

from the Help Menu. The selections on this menu offer descriptions of common editing operations. For practice, choose the topic

>     Loading a Program that has been Saved

by highlighting this line, then pressing any key. This explanation will explain how to load a program that has already been saved.

It will pay to wander through all this introductory material when you have the time. You may not understand it all yet, but it should help sooner or later.

## Information about Pascal

Go back to your program and move the cursor to the instruction

>     writeln(i,i*i);

in the `squares` program. In fact, move the cursor right on top of the second `i` in `i*i`. Now, press `[F9]` and choose the selection

>     Information about Pascal

from the Help Menu.

What you will get is the line

>     Pascal Help

followed by a list of everything that the cursor is on or within, starting at the smallest and going to the biggest. In this case, the cursor is on a variable name in a multiplication expression in an output argument in a `writeln` instruction in a for loop in a Pascal program, so you will get the list

Screen Shot squares6 not available

You can highlight any of these selections, then press any key to ask for help on that particular thing. for practice, highlight the `for loop` and press any key. You will get an explanation of for including examples of its use.

Screen Shot forhelp not available

This explanation also contains a menu of other topics on which help can be offered. In this way, you can get help on any aspect of Pascal in your program. Choose the `Do nothing` selection on this menu, and you will return to your normal program.

Now move the cursor to the word `integer` in the declaration

>     var
>         i : integer;  {A counter}

Press `[F9]` and choose the

>     Information about Pascal

from the Help Menu again. This time you get a completely new selection of topics:

Screen Shot squares7 not available

Once again you see that you are given a list of everything that contains the position of the cursor, from smallest to largest. You can do this anywhere in your program. For example, if you move to a `writeln` instruction and ask for `Information about Pascal`, one of the help items on the menu will be `writeln`. If you choose this item from the menu, you will get a quick explanation of how the `writeln` routine works.

We expect that most people will use this ``Pascal help'' feature a great deal. For this reason, we have provided a quick way of getting the information -- just position the cursor and press `[ALT-P]`. This saves you the trouble of calling up the Help Menu and choosing the appropriate selection. If you press `[ALT-P]` now, you will see how it works.

Most people will use this Pascal Help feature often, since it means you don't have to look things up in a normal Pascal reference manual. You should take time now to move the cursor to various positions in the sample program and see what kind of help is provided in each case.

## Errors

Go back to your program and push `[F9]` again. The next selection we'll look at is

>     What does my error message mean?

Before you can see how this works, you have to make an error, so let's do this.

Select `Do nothing` to return to your program. You should now have the `squares` program on your screen. This includes the for loop that starts

>     for i := 1 to 10 do begin

Move the cursor to the variable `i` in this line and change the `i` to a `j`. (Highlight `i`; press `[CTRL-P]`; enter a `j`.) Since there is no variable `j` defined in your program, you will receive the error message

>     Symbol 'j' has not been declared

and the `j` will be highlighted.

Now we can see what that entry in the Help Menu means. Press `[F9]` and choose the

>     What does my error message mean?

selection from the Help Menu. When you do this, Alice gives an expanded description of why the error occurred and also gives a few suggestions on how to fix it.

Let's leave `j` highlighted and wrong for a few moments and make another mistake in the program. Create a new `Statement` placeholder after the existing `writeln` instruction and enter the instruction

>     writeln(2+);

You can do this simply by pressing TAB when you have typed `2+`. As soon as you do this, Alice will issue the message

>     Expression Syntax Error

for obvious reasons. Again, the erroneous material will be highlighted so it's easier to see on the screen.

Call up the Help Menu again by pressing `[F9]` and choose the `What does my error message mean?` selection. This time, naturally, you will get a fuller description of syntax errors.

If you now move the cursor back to the first mistake we made, the undeclared variable `j`, and choose the `What does my error message mean?` selection again, Alice gives you help on the older error instead of the new one. In this way, you can remind yourself of what went wrong earlier.

You will notice that the error message you receive when you first get an error disappears from the screen fairly quickly. If you want to see the error message again, you can choose

>     What was the last error?

from the Help Menu and Alice will repeat the message.

Before you go on, you should correct the two mistakes that are in your program. Just delete the extra `writeln` instruction we added, and change the variable name `j` back to an `i`.

## What Can I Type Here?

There is only one selection left on the Help Menu that we haven't looked at:

>     What can I type here?

Before we see what kind of help that gives, you should create an empty `Statement` placeholder somewhere in your program. Try making it before the for loop -- remember that you do this by moving the cursor to the keyword for then pressing `[INS]`.

Once the cursor is on the `Statement` placeholder, press `[F9]` and choose the `What can I type` selection. Alice will print out a menu of all the things that can legally be entered in a `Statement` placeholder. This includes a lot of keywords like for, if, or while. It also includes a few more general entries; for example, it has an entry `A Symbol`, indicating that statements can begin with a name (i.e. assignment statements or procedure calls).

If you highlight one of these items and press any key, Alice will fill the `Statement` placeholder with the choice you selected. Let's try that. Highlight the for line and press any key. You will see that Alice fills the `Statement` placeholder with the template of a for loop.

Let's try it again. Move to the first empty placeholder in the new for loop, namely the `Variable` placeholder. Press `[F9]` and choose the `What can I type` selection from the Help Menu. Again, you will get a list of all the things you could legally type for this placeholder. For example, near the top of the list you'll see `A Symbol`. If you choose this selection, you'll get a list of symbols that are defined in the program. Select the variable `i` from this list, and Alice will fill the `variable` placeholder with the variable name `i`.

As you can see, this is a very convenient feature. In fact, you could use this feature to do most of your programming without ever touching the main part of the keyboard. If you're the sort of person who doesn't like typing, you can create almost all of your program just by choosing things from menus.

Of course, it takes some time to call up the Help Menu and choose the `What can I Type` selection over and over again. To shorten this process, you can just press `[ALT-T]` (the ``T'' stands for ``token'' or ``typing'').For example, move the cursor to the empty `Statement` placeholder inside the new for loop and press `[ALT-T]`. Again you will receive the list of all things that can be used to fill an empty `Statement` placeholder.

Now instead of selecting something from this list by pressing an arbitrary key, let's highlight something like the keyword if and press `[F9]`. As you could likely guess, you get a brief description of the selection. In this way, you can find out more about each item listed on the list.

The lists printed by pressing `[ALT-T]` or by choosing the correct selection from the Help Menu are called Input Menus because they indicate what things you can input. As always, you should experiment with the way that Input Menus work so you feel comfortable with them later on.

## Symbol Lists

Symbol lists are closely related to Input Menus. If you position the cursor on a place where a symbol could be entered and then press `[END]` (on the keypad), you will receive a list of all appropriate symbols that could be entered in that location. These are chosen from all the symbols that are defined in the current scope of your program, including named constants, named types, and names of variables, functions, and procedures.

The ``current scope'' refers to the position of the cursor. For example, if the cursor is inside a subprogram, the Symbol List will include symbols that are local to the subprogram. If you move the cursor outside the subprogram, the Symbol List will not include such symbols because they aren't officially defined outside the subprogram.

Calling up a Symbol List is useful if you aren't sure of the exact name you used for a particular value or variable. As with Input Menus, you can select things from a symbol list and use them to fill empty placeholders just by highlighting the selection and pressing any key.

## Name Completion

Actually, symbol lists are a special case of a very useful feature called name completion. Let's go back to our `squares` program. Create a new variable declaration (by going to an existing declaration and pressing `[ENTER]`), then go to the `Type` placeholder. Type the letter `i`

Screen Shot 4 7 complete not available

and then press `[END]`.

Screen Shot 4 7 compl2 not available

You will see that Alice changes the `i` to `integer`!

What has happened? When you pressed `[END]`, Alice checked its symbol lists for any type that began with the letter `i`. There is only one in the `squares` program: the standard `integer` type. Therefore, Alice doesn't bother to show you a symbol list when you press `[END]` -- it just completes or Ends the symbol you've already started to type.

What would happen if you had another named type that began with `i`? Alice would show you a limited symbol list. This is a symbol list that only shows the symbols that start with the thing you've typed. You can then choose the name you want from this list, just the way that you choose a name from a full symbol list.

You can type more than the first letter if you want, before you press `[END]`. The more letters you type, the easier it is for Alice to complete the name you're typing.

Of course, you never need to use `[END]` to complete a name, if you want to type everything out in full. But isn't it nice that Alice can save you typing time and errors whenever you want it to?

## Long Menus

Some of the menus produced by the HELP facility are too long to fit on the screen all at once. In these cases, Alice will begin by showing only part of the menu. At the bottom of the menu, it will show the highlighted word ``MORE'' to indicate that there is more to the list than can be shown on the screen.

If you move beyond the end of what is shown on the screen, Alice will show you more of the possible selections. Think of the menu as a list of selections written on a scroll. You can only see some of the selections to begin with, but if you keep moving down the list, Alice will unroll the scroll at the bottom (and roll it up at the top) to show you more selections.

On the IBM PC, a few special keys can be used to highlight selections quickly. The `[END]` key highlights the last selection on the menu, even if that selection isn't shown at the moment. Similarly, the `[Home]` key highlights the first selection. Pressing `[PgDn]` jumps down several selections, and pressing `[PgUp]` jumps up several selections.

## Chapter Summary

In this chapter, we talked about

1. Pressing `[F9]` to summon the Help Menu.
2. Choosing the `Quick Summary of Keys` selection to get a list of commands that can be executed by pressing a key or key sequence.
3. Choosing the `Features of ALICE` selection to get descriptions of common editing operations.
4. Getting help on a command by highlighting the command on a menu and pressing `[F9]`.
5. Choosing the `Getting Started with ALICE` selection from the Help Menu to obtain an introductory talk about Alice.
6. Choosing the `Information about Pascal` selection from the Help Menu. Alice offers help on everything Pascal construct that contains the cursor, going from smallest to largest. You can also get this list by pressing `[ALT-P]`.
7. Choosing the `What does my error message mean?` selection from the Help Menu gives you an explanation of your most recent error message.
8. Choosing the `What can I type here?` selection from the Help Menu. Alice prints a list of all the things you can type with the cursor positioned where it is. This list is called an Input Menu. Input Menus can also be obtained by pressing `[ALT-T]`. If you highlight something on an Input Menu and press `[F10]`, it has the same effect you'd get if you actually typed that input. If you highlight something on an Input Menu and press `[F9]`, Alice provides a brief description of the highlighted selection.
9. Pressing `[END]` provides a Symbol List, containing the names of all the symbols that are defined in the current scope of the program.
10. Pressing `[END]` will complete a name you've started to type, or give you a list of possible names that begin with those letters.