1 |
greg |
2.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.) |