tcl.help Verb: Access/TCL

tcl.help

Command tcl.help Verb: Access/TCL
Applicable release versions: AP
Category TCL (746)
Description provides an interface to the on-line copy of Advanced Pick Reference Manual version 2.0, printed version.

To fully appreciate and exploit the help system, a working knowledge of the Update processor is required.

Quick command summary:

<ctrl>+xe Exit item.
<ctrl>+n Move cursor down one line.
<ctrl>+m Move to next paragraph.
<ctrl>+b Move cursor up one line.
<ctrl>+p Move to next page.
<ctrl>+ze Move to end of document.
<ctrl>+zy Move to previous page.
<ctrl>+t Move to top of item.
<ctrl>+g Move to end of attribute (paragraph).
<ctrl>+g<ctrl>+g Zoom to related subject.
<ctrl>+f Cruise forward on indexed attribute.
<ctrl>+f Move to next sentence in a text attribute.
<ctrl>+d Cruise backward on indexed attribute.
<ctrl>+d Move to previous sentence in a text attribute.
<ctrl>+e Erase to end of line.
<ctrl>+a Search for phrase or repeat last search.

Hotkeys:

<ctrl>+x4 Preview mode.
<ctrl>+x5 Print hard copy of subject. Use this on this item.

"help" invokes the TCL command, "help.display", and displays a read-only copy of the Advanced Pick document/topic closest to the specified token. If a token is not specified, the "help" token is displayed.

Once inside the help system, the "token" (subject), "category", "type", "description", "syntax", "options", "compatibility", "see.also", "example", and "warnings" attributes are displayed.

"Cruising" through help topics:

You can "cruise" forward with <ctrl>+f or backward with <ctrl>+d on the "token", "category" and "type" attributes. All other attributes are text attributes. In an text attribute, <ctrl>+f moves to the beginning of the next sentence and <ctrl>+d moves to the previous sentence. Cruising on the "token" field is particularly useful. For instance, there are multiple "delete" tokens. If you were to type "help delete", you would arrive on the "first" reference to delete, which happens to be the Pick/BASIC delete function. Issuing a <ctrl>+f while positioned on the token field takes you to the next "delete", which is the Pick/BASIC delete statement. Another <ctrl>+f takes you to the TCL delete verb.

Changing topics:

While on the "token" field, you can change topics easily by typing a new topic over top of the existing word or words, then <ctrl>+e to erase the rest of the line, followed by <ctrl>+f to cruise to the topic. For example, suppose you are in the topic, "attribute-defining items", and you want to see the "list" verb. The screen would look like:

topic attribute-defining items

The cursor is positioned under the "a" in the word "attribute". This is where you type "list", so that the screen looks like:

topic listibute defining items

With the cursor under the second "i" in "listibute. A <ctrl>+e wipes out the rest of the "junk" on the line, so it looks like:

topic list

BEFORE you hit <return>, type <ctrl>+f. This will cruise forward to the first "list" subject found. If you hit <return> BEFORE hitting <ctrl>+f, you can still recover, but you have to re-position the cursor to the end of the token attribute (<ctrl>+b to move up, then <ctrl>+g).

"Zooming" to related files and subjects:

The "category", "type", and "see.also" attributes allow "zooming" to supporting files and subjects. "Zooming" is accomplished with two <ctrl>+g's. The first <ctrl>+g moves to the end of the attribute. The second <ctrl>+g "zooms" to the related file or subject. This is most useful on the "see.also" attribute, which is like a hypertext jump to a related subject in the same file.

To practice "zooming", see the topic "cursor movement" in the "see.also" field. To get to the topic, press <return> until the cursor is on the "cursor movement" topic, then "zoom" to the related topic. When you are done with the topic, <ctrl>+xe returns to the previous topic.

Exiting help:

<ctrl>+xe returns control to TCL, unless you have "zoomed" to one or more related help items through the "see.also" field, in which case, each <ctrl>+xe returns to the previous subject.

"help" invokes the "look-only" mode of the Update processor, which prevents the ability to file any items. This means that you can't hurt anything, in case you accidentally erase or type over part of a help item.

Printing a help item:

Once inside a help item, you can print the item using "hotkey" 5. This is accomplished by pressing <ctrl>+x5. The "hard copy" output is exactly the same as the "preview" mode output.

"Previewing" a help item:

To help distinguish the elements of a help item, we have built a special processing language that affects the syntax. The "preview" mode is activated by "hotkey" 4, (<ctrl>+x4).

The required elements in the syntax are shown in boldface characters. All "fill-in-the-blank" (parameters) of the syntax are underlined in "display" mode and italicized on hard copy. Every element listed in the syntax is either discussed in the "description" attribute, or is listed in the "see.also" attribute. See the topic "documentation conventions" for more explanation on the use of special characters in the syntax.

The "preview" mode uses Access with a number of Pick/BASIC subroutine calls. While in preview mode, pressing any output-producing key on the keyboard advances to the next page. <ctrl>+x returns to the Update processor mode. You can not cruise or zoom while in "preview" mode.

On releases of AP prior to 5.2, there may be a small problem when returning from preview mode. This has to do with the program attempting to store the "zp" (refresh screen) command into the Update processor using the "access(21)" function. This feature was added in 5.2 and doesn't work on earlier versions. Another thing to watch out for is when it DOES work. It has the side effect of loading "zp" into "prestore 0", so that when a <ctrl>+p is issued, it refreshes the screen, rather than advancing to the next page. Use <ctrl>+zn to page down in the item, or redefine prestore 0 to be "zn" using the "zl" command.

Finding an item when you're not sure what you're looking for:

The help system is especially helpful if you know the topic you are searching for, such as the "locate" instruction in Pick/BASIC. Our intent is to help you find your topic within a few hits. For instance, "locate" is one of the "see.also" fields listed under the topic of "statements and functions" in Pick/BASIC. From this topic, you can "zoom" to "locate".

As a last resort, you can use the "search" or "find" commands to search through every help subject for a particular word or phrase. For instance, if you knew that there was a command that produced output in a four-column format, you could use the "search" command on the "ap.doc" file, looking for the string "four-column". (As an exercise, see if you can find at least one subject with the string, "four-column"). For more information on "search" and "find", "zoom" to them through the "see.also" field.

Searching for a word or phrase in a particular item:

In some of the documentation items, the "see.also" field can span many screens. To get to a specific point in the item, the UP search command can be used. For example, in the token "attribute-defining items", a "see.also" is provided to "hotkey9". To get to it in a hurry, use <ctrl>+a. When prompted for the search string, enter "hotkey9" (without the quotes), then press <return>. This searches for the NEXT occurrence of "hotkey9", which it finds in the text. Press <ctrl>+a again and it finds the next occurrence, which is the "see.also" to "hotkey9".
Syntax help {token}
Options
Example
help  

This brings up this help item.

help locate

This looks for the token, "locate", and starts from that point in the 
token's b-tree index.

help fred

This looks for the subject closest to "fred". Since "fred" 
does not exist this should arrive in the topic, "free".
Purpose
Related tcl.help.display
ap.doc.macro.?
up.cursor.movement
tcl.find
tcl.search
ap.doc.function.install.help
installation