1 |
$Id$ |
2 |
|
3 |
This help file is for the gethelp.tcl utility itself, and explains |
4 |
the various buttons and windows it uses. |
5 |
|
6 |
All help files have the same general format. Each help section is |
7 |
named by its category and topic, and its position in the file is |
8 |
indicated with a line beginning with ".Category.Topic", where |
9 |
"Category" and "Topic" are replaced by the appropriate names. |
10 |
These names must begin with letters and may contain letters and/or |
11 |
numbers, but no special characters. They will appear on the menus |
12 |
of the help utility when that file is open. |
13 |
|
14 |
The file is unformatted, and will be filled by the help utility |
15 |
dynamically based on the current window size. The formatting code |
16 |
is very simple, placing a single space between adjacent lines, |
17 |
except when a line ends a sentence, when two spaces are used. |
18 |
Regular expression searches will not cross newline boundaries in the |
19 |
original file, so some care should be used not to break lines at |
20 |
likely search strings. (This is a pain, I know.) |
21 |
|
22 |
The first section of the file, which you are now reading, is |
23 |
generally reserved for comments such as this, and is not accessed |
24 |
directly by the user. |
25 |
|
26 |
.Help.Intro |
27 |
|
28 |
While holding down the control key, |
29 |
press and release the left mouse button on any object of curiosity, |
30 |
and if there is something to say about it, that |
31 |
something will appear in this window. |
32 |
|
33 |
Typically, a program will access multiple help files |
34 |
through this help interface. |
35 |
The particular file being viewed is indicated by the text at the |
36 |
top right of this window. |
37 |
It is not possible through this interface to switch from one help |
38 |
file to another, as the particular file being viewed is controlled by |
39 |
the calling program. |
40 |
|
41 |
The help window itself offers the ability to search through the |
42 |
available topics in the selected file via the "Category" and "Topic" menus. |
43 |
Each general category consists of an introduction (such as this |
44 |
one), followed by zero or more topics. |
45 |
Selecting a new topic starts automatically at the introduction page. |
46 |
From there, various topics within that category may be selected |
47 |
using the "Topic" menu. |
48 |
|
49 |
.Help.Category |
50 |
|
51 |
Help information is divided logically into categories, then |
52 |
into topics within each category. |
53 |
Changing categories via the "Category" menu immediately selects the |
54 |
default topic for the new category, which is always called "intro." |
55 |
|
56 |
Other topics for the new category will be listed by the (new) topic |
57 |
menu for that category. |
58 |
Some categories may have only an intro topic. |
59 |
|
60 |
The current category and topic are given as the title in the |
61 |
displayed help window. |
62 |
|
63 |
.Help.Topic |
64 |
|
65 |
The topic menu allows you to select which subtopic in this category |
66 |
you wish to display. |
67 |
|
68 |
The next logical topic is available via the "Next" button, |
69 |
unless the end of the help file has been reached. |
70 |
|
71 |
The current category and topic are given as the title in the |
72 |
displayed help window. |
73 |
|
74 |
.Navigate.Intro |
75 |
|
76 |
Besides accessing the category and topic menus, you can navigate |
77 |
forward and backward in the history list for the current help file, |
78 |
go directly to the next help topic, and search for regular |
79 |
expressions. |
80 |
|
81 |
The history list is filled in one of two ways. |
82 |
The first way is by running a search which results in multiple topic |
83 |
matches, in which case the additional matches are put in the future |
84 |
history of this file. |
85 |
|
86 |
The second way is by selecting additional topics, either explicitly |
87 |
via the "Category" and "Topic" menus, or implicitly by getting more |
88 |
help from the calling application without quitting the help window |
89 |
in between. |
90 |
|
91 |
.Navigate.Search |
92 |
|
93 |
To search for a particular pattern, type a regular expression |
94 |
in the text entry field. |
95 |
Hitting <return> causes all matches in the current topic to be |
96 |
highlighted. |
97 |
Hitting the "Grep" button causes all categories and topics to be |
98 |
searched. |
99 |
The first matching topic is displayed, and other matching topics (if |
100 |
any) may be accessed with the "Forward" button. |
101 |
|
102 |
Each time a new topic is selected, matching words will be highlighted |
103 |
in bold, whether or not <return> or the "Grep" button has been pressed. |
104 |
To prevent new matches from being highlighted, clear the search entry |
105 |
with <control-U>. |
106 |
|
107 |
Matches are insensitive to case and word boundaries. |
108 |
|
109 |
.Navigate.Forward |
110 |
|
111 |
The "Forward" button moves from the current topic to the next one in |
112 |
the history list, if any. |
113 |
In most cases, the "Forward" button will not be activated unless |
114 |
a search has been conducted with the "Grep" button or |
115 |
the "Back" button has been pressed one or more times. |
116 |
|
117 |
.Navigate.Back |
118 |
|
119 |
Use the "Back" button to go to previously accessed topics in the |
120 |
history list. |
121 |
|
122 |
If this button is disabled, it simply means that you are already at |
123 |
the beginning of the help file history. |
124 |
|
125 |
.Navigate.Next |
126 |
|
127 |
The "Next" button moves to the next sequential topic in the help file, |
128 |
which is named at the bottom of the current text. |
129 |
|
130 |
If this button is disabled, it means that the end of the help file |
131 |
has been reached. |
132 |
|
133 |
.Helpwin.Intro |
134 |
|
135 |
The help window displays the contents of the current help category and |
136 |
topic. |
137 |
The category and topic are given in bold at the top of the text in |
138 |
the window. |
139 |
The next category and topic are given at the end of the text in the |
140 |
window. |
141 |
|
142 |
Scrolling is accomplished with the scrollbar on the right. |
143 |
|
144 |
.Helpwin.Scroll |
145 |
|
146 |
Grab the bar with the mouse and drag it up and down to scroll |
147 |
the text in the help window. |
148 |
Click below or above the bar to jump a page forward or backward, |
149 |
respectively. |
150 |
Click on the little triangle at the bottom or top to move down or up |
151 |
a line at a time. |
152 |
|
153 |
.Help.Done |
154 |
|
155 |
The "Done" button simply dismisses the help window. |
156 |
(It is sometimes better to iconify the window, if frequent help is |
157 |
needed.) |