src/util/help.hlp

        $Id$

This help file is for the gethelp.tcl utility itself, and explains
the various buttons and windows it uses.

All help files have the same general format.  Each help section is
named by its category and topic, and its position in the file is
indicated with a line beginning with ".Category.Topic", where
"Category" and "Topic" are replaced by the appropriate names.
These names must begin with letters and may contain letters and/or
numbers, but no special characters.  They will appear on the menus
of the help utility when that file is open.

The file is unformatted, and will be filled by the help utility
dynamically based on the current window size.  The formatting code
is very simple, placing a single space between adjacent lines,
except when a line ends a sentence, when two spaces are used.
Regular expression searches will not cross newline boundaries in the
original file, so some care should be used not to break lines at
likely search strings.  (This is a pain, I know.)

The first section of the file, which you are now reading, is
generally reserved for comments such as this, and is not accessed
directly by the user.

.Help.Intro

While holding down the control key,
press and release the left mouse button on any object of curiosity,
and if there is something to say about it, that
something will appear in this window.

Typically, a program will access multiple help files
through this help interface.
The particular file being viewed is indicated by the text at the
top right of this window.
It is not possible through this interface to switch from one help
file to another, as the particular file being viewed is controlled by
the calling program.

The help window itself offers the ability to search through the
available topics in the selected file via the "Category" and "Topic" menus.
Each general category consists of an introduction (such as this
one), followed by zero or more topics.
Selecting a new topic starts automatically at the introduction page.
From there, various topics within that category may be selected
using the "Topic" menu.

.Help.Category

Help information is divided logically into categories, then
into topics within each category.
Changing categories via the "Category" menu immediately selects the
default topic for the new category, which is always called "intro."

Other topics for the new category will be listed by the (new) topic
menu for that category.
Some categories may have only an intro topic.

The current category and topic are given as the title in the
displayed help window.

.Help.Topic

The topic menu allows you to select which subtopic in this category
you wish to display.

The next logical topic is available via the "Next" button,
unless the end of the help file has been reached.

The current category and topic are given as the title in the
displayed help window.

.Navigate.Intro

Besides accessing the category and topic menus, you can navigate
forward and backward in the history list for the current help file,
go directly to the next help topic, and search for regular
expressions.

The history list is filled in one of two ways.
The first way is by running a search which results in multiple topic
matches, in which case the additional matches are put in the future
history of this file.

The second way is by selecting additional topics, either explicitly
via the "Category" and "Topic" menus, or implicitly by getting more
help from the calling application without quitting the help window
in between.

.Navigate.Search

To search for a particular pattern, type a regular expression
in the text entry field.
Hitting <return> causes all matches in the current topic to be
highlighted.
Hitting the "Grep" button causes all categories and topics to be
searched.
The first matching topic is displayed, and other matching topics (if
any) may be accessed with the "Forward" button.

Each time a new topic is selected, matching words will be highlighted
in bold, whether or not <return> or the "Grep" button has been pressed.
To prevent new matches from being highlighted, clear the search entry
with <control-U>.

Matches are insensitive to case and word boundaries.

.Navigate.Forward

The "Forward" button moves from the current topic to the next one in
the history list, if any.
In most cases, the "Forward" button will not be activated unless
a search has been conducted with the "Grep" button or
the "Back" button has been pressed one or more times.

.Navigate.Back

Use the "Back" button to go to previously accessed topics in the
history list.

If this button is disabled, it simply means that you are already at
the beginning of the help file history.

.Navigate.Next

The "Next" button moves to the next sequential topic in the help file,
which is named at the bottom of the current text.

If this button is disabled, it means that the end of the help file
has been reached.

.Helpwin.Intro

The help window displays the contents of the current help category and
topic.
The category and topic are given in bold at the top of the text in
the window.
The next category and topic are given at the end of the text in the
window.

Scrolling is accomplished with the scrollbar on the right.

.Helpwin.Scroll

Grab the bar with the mouse and drag it up and down to scroll
the text in the help window.
Click below or above the bar to jump a page forward or backward,
respectively.
Click on the little triangle at the bottom or top to move down or up
a line at a time.

.Help.Done

The "Done" button simply dismisses the help window.
(It is sometimes better to iconify the window, if frequent help is
needed.)
Revision:	2.1
Committed:	Thu Oct 27 15:56:03 1994 UTC (29 years, 6 months ago) by greg
Branch:	MAIN
Log Message:	Initial revision
#	User	Rev	Content
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.)