|
0
|
1 \input texinfo
|
|
|
2 @c
|
|
24
|
3 @c FILE: hyperbole.texi
|
|
|
4 @c SUMMARY: The Hyperbole User Manual for V4
|
|
|
5 @c USAGE: Hardcopy man from TeX; Info man from `texinfo-format-buffer'.
|
|
0
|
6 @c
|
|
|
7 @c AUTHOR: Bob Weiner
|
|
24
|
8 @c
|
|
|
9 @c ORG: InfoDock Associates. We sell corporate support and
|
|
|
10 @c development contracts for InfoDock, Emacs and XEmacs.
|
|
|
11 @c E-mail: <info@infodock.com> Web: http://www.infodock.com
|
|
|
12 @c Tel: +1 408-243-3300
|
|
0
|
13 @c
|
|
|
14 @c ORIG-DATE: 6-Nov-91 at 11:18:03
|
|
24
|
15 @c LAST-MOD: 20-Feb-97 at 12:36:16 by Bob Weiner
|
|
0
|
16
|
|
|
17 @c %**start of header (This is for running Texinfo on a region.)
|
|
|
18 @setfilename ../info/hyperbole.info
|
|
|
19 @settitle Hyperbole User Manual
|
|
|
20 @c %**end of header (This is for running Texinfo on a region.)
|
|
|
21 @synindex vr fn
|
|
|
22
|
|
|
23 @iftex
|
|
|
24 @finalout
|
|
|
25 @end iftex
|
|
|
26
|
|
|
27 @titlepage
|
|
|
28 @sp 4
|
|
|
29 @center @titlefont{Hyperbole Manual}
|
|
|
30 @sp 1
|
|
|
31 @center Everyday Information Management
|
|
|
32 @sp 5
|
|
|
33 @center Bob Weiner
|
|
24
|
34 @center InfoDock Associates
|
|
0
|
35 @sp 1
|
|
24
|
36 @center E-mail: <hyperbole@@infodock.com> (This is a mailing list.)
|
|
0
|
37 @sp 2
|
|
24
|
38 @center Edition 4.02
|
|
0
|
39 @sp 2
|
|
24
|
40 @center February 19, 1997
|
|
0
|
41
|
|
|
42 @page
|
|
|
43 @vskip 0pt plus 1filll
|
|
24
|
44 Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation, Inc.
|
|
0
|
45
|
|
|
46 All trademarks referenced herein are trademarks of their respective
|
|
|
47 holders.
|
|
24
|
48
|
|
|
49 InfoDock Associates, the developer of Hyperbole and InfoDock (an industrial
|
|
|
50 quality turn-key version of XEmacs), donates its work on Hyperbole to the
|
|
|
51 Free Software Foundation and makes it freely available for worldwide
|
|
|
52 distribution.
|
|
|
53
|
|
|
54 InfoDock Associates is a commercial firm dedicated to radical productivity
|
|
|
55 improvement in technical environments, whether in software development or
|
|
|
56 other knowledge intensive disciplines. Our initial offerings include high
|
|
|
57 quality commercial support, training, books and custom package development
|
|
|
58 for InfoDock, XEmacs or GNU Emacs on a variety of platforms.
|
|
|
59
|
|
|
60 @example
|
|
|
61 E-mail: <info@@infodock.com>
|
|
|
62 Web: http://www.infodock.com
|
|
|
63 Tel: +1 408-243-3300
|
|
|
64 @end example
|
|
|
65
|
|
0
|
66 @setchapternewpage odd
|
|
|
67 @end titlepage
|
|
|
68 @page
|
|
|
69
|
|
|
70 @node Top, Introduction, (dir), (dir)
|
|
|
71 @c node-name, next, previous, up
|
|
|
72 @unnumbered Preface
|
|
|
73
|
|
|
74 @ifinfo
|
|
|
75 @noindent
|
|
24
|
76 Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation, Inc.
|
|
0
|
77
|
|
|
78 All trademarks referenced herein are trademarks of their respective holders.
|
|
|
79
|
|
24
|
80 InfoDock Associates, the developer of Hyperbole and InfoDock (an industrial
|
|
|
81 quality turn-key version of XEmacs), donates its work on Hyperbole to the
|
|
|
82 Free Software Foundation and makes it freely available for worldwide
|
|
|
83 distribution.
|
|
|
84
|
|
|
85 InfoDock Associates is a commercial firm dedicated to radical productivity
|
|
|
86 improvement in technical environments, whether in software development or
|
|
|
87 other knowledge intensive disciplines. Our initial offerings include high
|
|
|
88 quality commercial support, training, books and custom package development
|
|
|
89 for InfoDock, XEmacs or GNU Emacs on a variety of platforms.
|
|
|
90
|
|
|
91 @example
|
|
|
92 E-mail: <info@@infodock.com>
|
|
|
93 Web: http://www.infodock.com
|
|
|
94 Tel: +1 408-243-3300
|
|
|
95 @end example
|
|
|
96
|
|
0
|
97 @end ifinfo
|
|
|
98 This edition of the Hyperbole User Manual is for use with any version
|
|
24
|
99 4.02 or greater of Hyperbole.
|
|
0
|
100
|
|
|
101 Hyperbole is free software; you can use it, redistribute it and/or modify it
|
|
|
102 without fee under the terms of the GNU General Public License as published by
|
|
|
103 the Free Software Foundation; either version 2, or (at your option) any later
|
|
|
104 version.
|
|
|
105
|
|
|
106 Hyperbole is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
|
107 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
|
|
|
108 A PARTICULAR PURPOSE. See the GNU General Public License for more details.
|
|
|
109
|
|
|
110 You should have received a copy of the GNU General Public License
|
|
|
111 along with GNU Emacs or XEmacs; see the file COPYING. If not, write to
|
|
|
112 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
113
|
|
|
114 @cindex credits
|
|
|
115 @cindex InfoDock, obtaining
|
|
|
116 @cindex Hyperbole, obtaining
|
|
|
117 @cindex anonymous ftp
|
|
24
|
118 Hyperbole was designed and written by Bob Weiner of InfoDock Associates.
|
|
|
119 Motorola, Inc@. helped fund early work. For information on how to
|
|
|
120 obtain Hyperbole, @ref{Obtaining}.
|
|
0
|
121
|
|
|
122 This manual explains user operation and summarizes basic developer
|
|
|
123 facilities of Hyperbole. This major release of Hyperbole concentrates
|
|
|
124 on providing convenient access to information and control over its
|
|
|
125 display. The Hyperbole outliner emphasizes flexible views and structure
|
|
|
126 manipulation within bodies of information.
|
|
|
127
|
|
|
128 @cindex Hyperbole
|
|
|
129 @cindex hypertext
|
|
|
130 @cindex Emacs Lisp
|
|
|
131 @cindex Emacs 19
|
|
|
132 @cindex Epoch
|
|
|
133 @cindex XEmacs
|
|
24
|
134 Hyperbole (pronounced Hi-per-bo-lee) is an open, efficient, programmable
|
|
|
135 information management and hypertext system. It is intended for
|
|
|
136 everyday work on any UNIX platform supported by GNU Emacs. It works
|
|
|
137 well with the versions of Emacs that support multiple X or NEXTSTEP
|
|
|
138 windows: Emacs 19, XEmacs and Epoch. Hyperbole allows hypertext buttons
|
|
|
139 to be embedded within unstructured and structured files, mail messages
|
|
|
140 and news articles. It offers intuitive mouse-based control of
|
|
|
141 information display within multiple windows. It also provides
|
|
|
142 point-and-click access to Info manuals, ftp archives, Wide-Area
|
|
|
143 Information Servers (WAIS), and the World-Wide Web (WWW) hypertext
|
|
|
144 system through encapsulations of software that support these protocols.
|
|
0
|
145
|
|
|
146 @noindent
|
|
|
147 Hyperbole consists of four parts:
|
|
|
148
|
|
|
149 @table @bullet
|
|
|
150 @item Info Management
|
|
|
151 an interactive information management interface, including a powerful
|
|
|
152 rolodex, which anyone can use. It is easy to pick up and use since it
|
|
|
153 introduces only a few new mechanisms and provides user-level facilities
|
|
|
154 through a menu interface, which you control from the keyboard or the
|
|
|
155 mouse;
|
|
|
156
|
|
|
157 @item Hypertext Outliner
|
|
|
158 an outliner with multi-level autonumbering and permanent ids attached to
|
|
|
159 each outline node for use as hypertext link anchors, plus flexible view
|
|
|
160 specifications that can be embedded within links or used interactively;
|
|
|
161
|
|
|
162 @item Button Types
|
|
|
163 a set of hyper-button types that provides core hypertext and other
|
|
|
164 behaviors. Users can make simple changes to button types and those
|
|
|
165 familiar with Emacs Lisp can quickly prototype and deliver new types;
|
|
|
166
|
|
|
167 @item Programming Library
|
|
|
168 a set of programming library classes for system developers who want to
|
|
|
169 integrate Hyperbole with another user interface or as a back-end to a
|
|
|
170 distinct system. (All of Hyperbole is written in Emacs Lisp for ease of
|
|
|
171 modification. Although Hyperbole was initially designed as a prototype,
|
|
|
172 it has been engineered for real-world usage and is well structured.)
|
|
|
173 @end table
|
|
|
174
|
|
|
175 @cindex GNU Emacs
|
|
|
176 @kindex C-h t
|
|
|
177 @vindex file, DEMO
|
|
|
178 @cindex demonstration
|
|
|
179 @cindex button demo
|
|
|
180 Hyperbole may be used simply for browsing through documents
|
|
|
181 pre-configured with Hyperbole buttons, in which case, one can safely
|
|
|
182 ignore most of the information in this manual. The @file{DEMO} file
|
|
|
183 included in the Hyperbole distribution demonstrates many of Hyperbole's
|
|
|
184 standard facilities. It offers a much less technical introduction for
|
|
|
185 Hyperbole users by providing good examples of how buttons may be
|
|
|
186 used and an introduction to the outliner.
|
|
|
187
|
|
|
188 So if this manual is too detailed for your taste, you can skip it
|
|
|
189 entirely and just jump right into the demonstration, normally by typing
|
|
|
190 @{@kbd{C-h h d d}@}, assuming Hyperbole has already been installed at
|
|
|
191 your site. Otherwise, @ref{Installation}, for Hyperbole installation
|
|
|
192 and configuration information.
|
|
|
193
|
|
|
194 Many users, however, will want to do more than browse with Hyperbole,
|
|
|
195 e.g@. create their own buttons. The standard Hyperbole button editing
|
|
|
196 user interface is GNU Emacs-based, so a basic familiarity with the Emacs
|
|
|
197 editing model is useful. The material covered in the GNU Emacs
|
|
|
198 tutorial, normally bound to @{@kbd{C-h t}@} within Emacs, is more than
|
|
|
199 sufficient as background. If some GNU Emacs terms are unfamiliar to
|
|
|
200 you, @ref{Glossary, Emacs Glossary,, emacs, the GNU Emacs Manual}.
|
|
|
201
|
|
|
202 Before we delve into Hyperbole, a number of acknowledgments are in
|
|
|
203 order. Peter Wegner has encouraged the growth in this work. Morris
|
|
|
204 Moore has helped me pursue my own research visions and kept me striving
|
|
|
205 for excellence. Doug Engelbart has shown me the bigger picture and
|
|
|
206 continues to be an inspiration. His work provides a model from which I
|
|
|
207 am beginning to draw. Kellie Clark and I jointly designed the Hyperbole
|
|
|
208 outliner while sharing a life together. Chris Nuzum, as a user of
|
|
|
209 Hyperbole, has helped demonstrate its power since its inception; he
|
|
|
210 knows how to work with Hyperbole far better than I.
|
|
|
211
|
|
|
212 @menu
|
|
|
213 * Introduction::
|
|
|
214 * Installation::
|
|
|
215 * Buttons::
|
|
|
216 * Smart Keys::
|
|
|
217 * Menus::
|
|
|
218 * Entering Arguments::
|
|
|
219 * Outliner::
|
|
|
220 * Rolodex::
|
|
|
221 * Window Configurations::
|
|
|
222 * Developing with Hyperbole::
|
|
|
223 * Glossary::
|
|
|
224 * Smart Key Reference::
|
|
|
225 * Outliner Keys::
|
|
|
226 * Suggestion or Bug Reporting::
|
|
|
227 * Questions and Answers::
|
|
|
228 * Future Work::
|
|
|
229 * References::
|
|
|
230 * Key Binding Index::
|
|
|
231 * Code and File Index::
|
|
|
232 * Concept Index::
|
|
|
233
|
|
|
234 --- The Detailed Node Listing ---
|
|
|
235
|
|
|
236 Introduction
|
|
|
237
|
|
|
238 * Hyperbole Overview::
|
|
|
239 * Mail Lists::
|
|
|
240 * Manual Overview::
|
|
|
241
|
|
|
242 Installation
|
|
|
243
|
|
|
244 * Obtaining::
|
|
|
245 * Building::
|
|
|
246 * Installing::
|
|
|
247 * Configuring::
|
|
|
248
|
|
|
249 Configuring
|
|
|
250
|
|
|
251 * Internal Viewers::
|
|
|
252 * External Viewers::
|
|
|
253 * Link Variable Substitution::
|
|
|
254 * Button Colors::
|
|
|
255
|
|
|
256 Buttons
|
|
|
257
|
|
|
258 * Explicit Buttons::
|
|
|
259 * Global Buttons::
|
|
|
260 * Implicit Buttons::
|
|
|
261 * Action Types::
|
|
|
262 * Button Type Precedence::
|
|
|
263 * Button Files::
|
|
|
264 * Utilizing Explicit Buttons::
|
|
|
265
|
|
|
266 Utilizing Explicit Buttons
|
|
|
267
|
|
|
268 * Creation::
|
|
|
269 * Renaming::
|
|
|
270 * Deletion::
|
|
|
271 * Modification::
|
|
|
272 * Location::
|
|
|
273 * Buttons in Mail::
|
|
|
274 * Buttons in News::
|
|
|
275
|
|
|
276 Creation
|
|
|
277
|
|
|
278 * By Dragging:: Creation Via Action Key Drags
|
|
|
279 * By Menu:: Creation Via Menus
|
|
|
280
|
|
|
281 Outliner
|
|
|
282
|
|
|
283 * Menu Commands::
|
|
|
284 * Creating Outlines::
|
|
|
285 * Autonumbering::
|
|
|
286 * Idstamps::
|
|
|
287 * Editing::
|
|
|
288 * Viewing::
|
|
|
289 * Links::
|
|
|
290 * Cell Attributes::
|
|
|
291 * Outliner History::
|
|
|
292
|
|
|
293 Editing
|
|
|
294
|
|
|
295 * Adding and Killing::
|
|
|
296 * Moving Around::
|
|
|
297 * Relocating and Copying::
|
|
|
298 * Filling::
|
|
|
299 * Transposing::
|
|
|
300 * Splitting and Appending::
|
|
|
301 * Inserting and Importing::
|
|
|
302
|
|
|
303 Viewing
|
|
|
304
|
|
|
305 * Hiding and Showing::
|
|
|
306 * View Specs::
|
|
|
307
|
|
|
308 Rolodex
|
|
|
309
|
|
|
310 * Rolo Concepts::
|
|
|
311 * Rolo Menu::
|
|
|
312 * Rolo Keys::
|
|
|
313 * Rolo Settings::
|
|
|
314
|
|
|
315 Developing with Hyperbole
|
|
|
316
|
|
|
317 * Hook Variables::
|
|
|
318 * Creating Types::
|
|
|
319 * Explicit Button Technicalities::
|
|
|
320 * Encapsulating Systems::
|
|
|
321 * Embedding Hyperbole::
|
|
|
322
|
|
|
323 Creating Types
|
|
|
324
|
|
|
325 * Action Type Creation::
|
|
|
326 * Implicit Button Types::
|
|
|
327
|
|
|
328 Explicit Button Technicalities
|
|
|
329
|
|
|
330 * Button Label Normalization::
|
|
|
331 * Operational and Storage Formats::
|
|
|
332 * Programmatic Button Creation::
|
|
|
333
|
|
|
334 Smart Key Reference
|
|
|
335
|
|
|
336 * Smart Mouse Keys::
|
|
|
337 * Smart Keyboard Keys::
|
|
|
338 @end menu
|
|
|
339
|
|
|
340 @node Introduction, Installation, Top, Top
|
|
|
341 @chapter Introduction
|
|
|
342
|
|
|
343 This chapter describes what Hyperbole is, lists some of its potential
|
|
|
344 applications, explains how to subscribe to its mail lists, and then
|
|
|
345 summarizes the structure of the rest of the manual.
|
|
|
346
|
|
|
347 @menu
|
|
|
348 * Hyperbole Overview::
|
|
|
349 * Mail Lists::
|
|
|
350 * Manual Overview::
|
|
|
351 @end menu
|
|
|
352
|
|
|
353 @node Hyperbole Overview, Mail Lists, Introduction, Introduction
|
|
|
354 @section Hyperbole Overview
|
|
|
355 @cindex button
|
|
|
356 A Hyperbole user works with @emph{buttons} embedded within textual
|
|
|
357 documents; he may create, modify, move or delete buttons. Each button
|
|
|
358 performs a specific action, such as linking to a file or executing a
|
|
|
359 shell command.
|
|
|
360
|
|
|
361 @cindex button, explicit
|
|
|
362 @cindex button, global
|
|
|
363 @cindex button, implicit
|
|
|
364 @cindex button category
|
|
|
365 @cindex explicit button
|
|
|
366 @cindex global button
|
|
|
367 @cindex implicit button
|
|
|
368 There are three categories of Hyperbole buttons:
|
|
|
369 @table @dfn
|
|
|
370 @item explicit buttons
|
|
|
371 created by Hyperbole, accessible from within a single document;
|
|
|
372
|
|
|
373 @item global buttons
|
|
|
374 created by Hyperbole, accessible anywhere within a user's network of
|
|
|
375 documents;
|
|
|
376
|
|
|
377 @item implicit buttons
|
|
|
378 created and managed by other programs or embedded within the structure
|
|
|
379 of a document, accessible from within a single document. Hyperbole
|
|
|
380 recognizes implicit buttons by contextual patterns given in their type
|
|
|
381 specifications (explained later).
|
|
|
382 @end table
|
|
|
383
|
|
|
384 Explicit Hyperbole buttons may be embedded within any type of text file.
|
|
|
385 Implicit buttons may be recognized anywhere within a text file,
|
|
|
386 depending on the implicit button types that are available. All global
|
|
|
387 buttons are stored in a single location and activated by entering their
|
|
|
388 names, rather than by direct selection, the means used to activate
|
|
|
389 explicit and implicit buttons.
|
|
|
390
|
|
|
391 @noindent
|
|
|
392 To summarize:
|
|
|
393
|
|
|
394 @example
|
|
|
395 Button Category Active Within Activation Means Managed By
|
|
|
396 ========================================================================
|
|
|
397 Explicit a single document direct selection Hyperbole
|
|
|
398 Global any document specifying its name Hyperbole
|
|
|
399 Implicit a matching context direct selection other tools
|
|
|
400 ========================================================================
|
|
|
401 @end example
|
|
|
402
|
|
|
403 @cindex terminal use
|
|
|
404 Hyperbole buttons may be clicked upon with a mouse to activate them or
|
|
|
405 to describe their actions. Thus, a user can always check how a button
|
|
|
406 will act before activating it. Buttons may also be activated from a
|
|
|
407 keyboard. (In fact, virtually all Hyperbole operations, including menu
|
|
|
408 usage, may be performed from any standard character terminal interface,
|
|
|
409 so one need not be anchored to a workstation all day). @xref{Smart
|
|
|
410 Keys}.
|
|
|
411
|
|
|
412 @cindex Hyperbole features
|
|
|
413 Hyperbole does not enforce any particular hypertext or information
|
|
|
414 management model, but instead allows you to organize your information in
|
|
|
415 large or small chunks as you see fit. The Hyperbole outliner organizes
|
|
|
416 information hierarchies which may also contain links to external
|
|
|
417 information sources.
|
|
|
418
|
|
|
419 @noindent
|
|
|
420 Some of Hyperbole's most important features include:
|
|
|
421
|
|
|
422 @itemize @bullet
|
|
|
423 @item
|
|
|
424 Buttons may link to information or may execute procedures, such as
|
|
|
425 starting or communicating with external programs;
|
|
|
426
|
|
|
427 @item
|
|
|
428 One simply drags between a button source location and a link destination
|
|
|
429 to create or to modify a link button. The same result can be achieved
|
|
|
430 from the keyboard.
|
|
|
431
|
|
|
432 @item
|
|
|
433 Buttons may be embedded within electronic mail messages;
|
|
|
434
|
|
|
435 @item
|
|
|
436 Outlines allow rapid browsing, editing and movement of chunks of
|
|
|
437 information organized into trees (hierarchies);
|
|
|
438
|
|
|
439 @item
|
|
|
440 Other hypertext and information retrieval systems may be encapsulated
|
|
|
441 under a Hyperbole user interface (a number of samples are provided).
|
|
|
442 @end itemize
|
|
|
443
|
|
|
444 @cindex Hyperbole applications
|
|
|
445 @noindent
|
|
|
446 Typical Hyperbole applications include:
|
|
|
447
|
|
|
448 @table @strong
|
|
|
449 @item personal information management
|
|
|
450 Overlapping link paths provide a variety of views into an information space.
|
|
|
451 A search facility locates buttons in context and permits quick selection.
|
|
|
452
|
|
|
453 @item documentation and code browsing
|
|
|
454 Cross-references may be embedded within documentation. One can add a
|
|
|
455 point-and-click interface to existing documentation, link code with
|
|
|
456 associated design documents, or jump to the definition of an identifier
|
|
|
457 by selecting its name within code or documentation.
|
|
|
458
|
|
|
459 @item brainstorming
|
|
|
460 The Hyperbole outliner, @xref{Outliner}, is an
|
|
|
461 effective tool for capturing ideas and then quickly reorganizing them in
|
|
|
462 a meaningful way. Links to related ideas are easy to create,
|
|
|
463 eliminating the need to copy and paste information into a single place.
|
|
|
464
|
|
|
465 @item help/training systems
|
|
|
466 Tutorials containing buttons can show students how things work while
|
|
|
467 explaining the concepts, e.g@. an introduction to local commands. This
|
|
|
468 technique can be much more effective than written documentation alone.
|
|
|
469
|
|
|
470 @item archive managers
|
|
|
471 Programs that manage archives from incoming information streams may be
|
|
|
472 supplemented by having them add topic-based buttons that link to the
|
|
|
473 archive holdings. Users can then search and create their own links to
|
|
|
474 archive entries.
|
|
|
475 @end table
|
|
|
476
|
|
|
477 @node Mail Lists, Manual Overview, Hyperbole Overview, Introduction
|
|
|
478 @section Mail Lists
|
|
|
479
|
|
|
480 If you maintain or use Hyperbole, you should consider joining one of the
|
|
24
|
481 two Hyperbole mailing lists. @xref{Menus}, and the description
|
|
|
482 of the the Msg/ menu item, for a convenient means of joining and mailing
|
|
0
|
483 to these lists.
|
|
|
484
|
|
|
485 @cindex mail lists
|
|
|
486 @cindex e-mail
|
|
|
487 There are several Hyperbole-related mail addresses. Learn what each is
|
|
|
488 for before you mail to any of them.
|
|
|
489
|
|
|
490 @cindex mail list requests
|
|
|
491 @cindex joining a mail list
|
|
|
492 @cindex subscribing to a mail list
|
|
|
493 @cindex unsubscribing from a mail list
|
|
|
494 @format
|
|
24
|
495 <hyperbole-request@@infodock.com>
|
|
|
496 <hyperbole-announce-request@@infodock.com>
|
|
0
|
497 @end format
|
|
|
498
|
|
|
499 @display
|
|
|
500 @strong{All} mail concerning administration of the Hyperbole mailing
|
|
|
501 lists should be sent to the appropriate one of these addresses. That
|
|
|
502 includes addition, change, or deletion requests. Don't consider sending
|
|
|
503 such a request to a Hyperbole mail list or people will wonder why you
|
|
|
504 don't know that all Internet mail lists have a -request address for
|
|
|
505 administrative requests.@refill
|
|
|
506
|
|
24
|
507 Use the following formats in the @emph{body} of your message to execute requests,
|
|
|
508 where you substitute your own values for the <> delimited items and items
|
|
|
509 enclosed in [] are optional.
|
|
|
510
|
|
|
511 subscribe <mail-list-name> [<your-email-address>]
|
|
|
512 or
|
|
|
513 unsubscribe <mail-list-name> [<your-email-address>]
|
|
0
|
514
|
|
|
515 For example:
|
|
|
516
|
|
24
|
517 To: hyperbole-request@@infodock.com
|
|
|
518 Subject: Used if a human happens to read your mail.
|
|
|
519
|
|
|
520 subscribe hyperbole joe@@nowhere.gov
|
|
|
521
|
|
|
522 To change your address, you must unsubscribe your old address with
|
|
|
523 once command and subscribe your new address with another command, though
|
|
|
524 you can embed multiple commands on separate lines within a single message.
|
|
0
|
525 @end display
|
|
|
526
|
|
|
527 @noindent
|
|
|
528 There are two Hyperbole-related mail lists. Subscribe to one or the other,
|
|
|
529 not to both.
|
|
|
530
|
|
|
531 @cindex hyperbole mail list
|
|
|
532 @format
|
|
24
|
533 <hyperbole@@infodock.com>
|
|
0
|
534 @end format
|
|
|
535
|
|
|
536 @display
|
|
|
537 Mail list for discussion of all Hyperbole issues. Bug reports and
|
|
|
538 suggestions may also be sent here.@refill
|
|
|
539
|
|
|
540 @cindex e-mail, effective communication
|
|
|
541 @cindex effective communication
|
|
|
542 Always use your Subject and/or Summary: lines to state the position that
|
|
|
543 your message takes on the topic that it addresses.
|
|
|
544
|
|
|
545 For example, send:
|
|
|
546
|
|
|
547 Subject: Basic bug in top-level minibuffer menu.
|
|
|
548
|
|
|
549 rather than:
|
|
|
550
|
|
|
551 Subject: Hyperbole bug.
|
|
|
552
|
|
|
553 Statements end with periods, questions with question marks (typically),
|
|
|
554 and high energy, high impact declarations with exclamation points. This
|
|
|
555 simple rule makes all e-mail communication much easier for recipients to
|
|
|
556 handle appropriately.@refill
|
|
|
557
|
|
|
558 @cindex Hyperbole version
|
|
|
559 @cindex Emacs version
|
|
|
560 @vindex emacs-version
|
|
|
561 If you ask a question, your subject line should end with a ?,
|
|
|
562 e.g@. "Subject: How can man page SEE ALSOs be made implicit buttons?" A
|
|
|
563 "Subject: Re: How can ..." then indicates an answer to the question.
|
|
|
564 Question messages should normally include your Hyperbole and Emacs
|
|
|
565 version numbers and clearly explain your problem and surrounding issues.
|
|
|
566 Otherwise, you will simply waste the time of those who may want to help
|
|
|
567 you. (Your top-level Hyperbole menu shows its version number and @{@kbd{M-x
|
|
|
568 emacs-version @key{RET}}@} gives the other.)@refill
|
|
|
569
|
|
|
570 If you ask questions, you should consider adding to the discussion by
|
|
|
571 telling people the kinds of work you are doing or contemplating doing
|
|
|
572 with Hyperbole. In this way, the list will not be overwhelmed by
|
|
|
573 messages that ask for, but provide no information.@refill
|
|
|
574 @end display
|
|
|
575
|
|
|
576 @cindex hyperbole-announce mail list
|
|
|
577 @format
|
|
24
|
578 <hyperbole-announce@@infodock.com>
|
|
0
|
579 @end format
|
|
|
580
|
|
|
581 @display
|
|
|
582 Those who don't want to participate in the discussion but want to hear
|
|
|
583 about bug fixes and new releases of Hyperbole should subscribe to this
|
|
|
584 list. Anyone on the `hyperbole' list is automatically on this one too,
|
|
|
585 so there is no need to subscribe to this one in that case. This list is
|
|
|
586 for official fixes and announcements so don't send your own fixes here.
|
|
|
587 Send them to `hyperbole' instead.
|
|
|
588 @end display
|
|
|
589
|
|
|
590
|
|
|
591 @node Manual Overview, , Mail Lists, Introduction
|
|
|
592 @section Manual Overview
|
|
|
593
|
|
|
594 Remember that the @file{DEMO} file included in the Hyperbole
|
|
|
595 distribution demonstrates many of Hyperbole's standard facilities,
|
|
|
596 (@pxref{Top, Preface}) for more details.
|
|
|
597
|
|
|
598 @xref{Glossary}, for definitions of Hyperbole terms for quick
|
|
|
599 reference, so in some cases terms are not precisely defined within the
|
|
|
600 text. Be sure to reference the glossary if a term is unclear to you.
|
|
|
601 Although you need not have a keen understanding of all of these terms, a
|
|
|
602 quick scan of the Glossary should help throughout Hyperbole use.
|
|
|
603
|
|
|
604 If you have a question, feature suggestion or bug report on Hyperbole,
|
|
|
605 follow the instructions given in @ref{Suggestion or Bug Reporting}. A few
|
|
|
606 commonly asked questions are answered in the manual, @ref{Questions and
|
|
|
607 Answers}. If you are interested in classic articles on hypertext,
|
|
|
608 @ref{References}.
|
|
|
609
|
|
|
610 @xref{Installation}, for explanations of how to obtain, install, configure
|
|
|
611 and load Hyperbole for use.
|
|
|
612
|
|
|
613 @xref{Buttons}, for an overview of Hyperbole buttons and how to use them.
|
|
|
614
|
|
|
615 @xref{Smart Keys}, for an explanation of the innovative,
|
|
|
616 context-sensitive mouse and keyboard Action and Assist Keys offered by
|
|
|
617 Hyperbole. @xref{Smart Key Reference}, for a complete reference on what
|
|
|
618 the Action and Assist Keys do in each particular context that they
|
|
|
619 recognize.
|
|
|
620
|
|
|
621 (Keep in mind as you read about how to use Hyperbole that in many cases,
|
|
|
622 it provides a number of overlapping interaction methods are provided to
|
|
|
623 support different work styles and hardware limitations. You need learn
|
|
|
624 only one with which you can become comfortable, in such instances.)
|
|
|
625
|
|
|
626 @xref{Menus}, for summaries of Hyperbole menu commands and how to use
|
|
|
627 the minibuffer-based menus that work on dumb terminals.
|
|
|
628
|
|
|
629 @xref{Entering Arguments}, for special support that Hyperbole provides for
|
|
|
630 entering arguments when prompted for them.
|
|
|
631
|
|
|
632 @xref{Outliner}, for concept and usage information on the
|
|
|
633 autonumbered, hypertextual outliner. A full summary of the outliner
|
|
|
634 commands that are bound to keys may be found in @ref{Outliner Keys}.
|
|
|
635
|
|
|
636 @xref{Rolodex}, for concept and usage information on the
|
|
|
637 rapid lookup, hierarchical, free text record management system included
|
|
|
638 with Hyperbole.
|
|
|
639
|
|
|
640 @xref{Window Configurations}, for instructions on how to save and restore
|
|
|
641 the set of buffers and windows that appear with a frame. This feature
|
|
|
642 lets you switch among working contexts easily, even on a dumb terminal.
|
|
|
643 Such configurations only last throughout your current editor session.
|
|
|
644
|
|
|
645 Developers comfortable with Emacs Lisp will want to continue on through
|
|
|
646 to, @ref{Developing with Hyperbole}.
|
|
|
647
|
|
|
648 @xref{Future Work}, for future directions in Hyperbole's evolution.
|
|
|
649
|
|
|
650
|
|
|
651 @node Installation, Buttons, Introduction, Top
|
|
|
652 @chapter Installation
|
|
|
653
|
|
|
654 @cindex installation
|
|
|
655 Hyperbole must be installed at your site before you can use it. The
|
|
|
656 following sections explain how to obtain, install and configure
|
|
|
657 Hyperbole for use.
|
|
|
658
|
|
|
659 @vindex file, hsite.el
|
|
|
660 @cindex customization, init
|
|
|
661 If you want to customize the basic Hyperbole initialization sequence for
|
|
|
662 yourself rather than the users at your site, you should make a personal
|
|
|
663 copy of the @file{hsite.el} file, modify it the way you want, and then
|
|
|
664 load it. (If you are familiar with Emacs Lisp, @ref{Hook Variables}.)
|
|
|
665
|
|
|
666 @menu
|
|
|
667 * Obtaining::
|
|
|
668 * Building::
|
|
|
669 * Installing::
|
|
|
670 * Configuring::
|
|
|
671 @end menu
|
|
|
672
|
|
|
673 @node Obtaining, Building, Installation, Installation
|
|
|
674 @section Obtaining
|
|
|
675
|
|
|
676 @cindex ftp
|
|
|
677 @cindex anonymous ftp
|
|
24
|
678 Hyperbole can be obtained via anonymous ftp on the Internet from:
|
|
0
|
679
|
|
|
680 @file{ftp://ftp.xemacs.org/pub/infodock}.
|
|
|
681
|
|
|
682 @cindex downloading Hyperbole
|
|
|
683 @cindex obtaining Hyperbole
|
|
|
684 @cindex Hyperbole, obtaining
|
|
|
685 @noindent
|
|
|
686 Here are detailed instructions for downloading and unpacking Hyperbole.
|
|
|
687
|
|
|
688 Move to a directory below which you want the @file{hyperbole} directory to
|
|
|
689 be created. Unpacking the Hyperbole archive will create the
|
|
|
690 @file{hyperbole} directory and will place all of the files below it.
|
|
|
691
|
|
|
692 @example
|
|
|
693 cd <LOCAL-EMACS-LISP-DIR>
|
|
|
694 @end example
|
|
|
695
|
|
|
696 @noindent
|
|
|
697 Ftp to ftp.xemacs.org (Internet Host ID = 128.174.252.16):
|
|
|
698
|
|
|
699 @example
|
|
24
|
700 prompt> ftp ftp.xemacs.org (If this doesn't work, try `ftp xemacs.org'.)
|
|
0
|
701 @end example
|
|
|
702
|
|
|
703 @noindent
|
|
|
704 Login as @emph{anonymous} with your own @emph{<user-id>@@<site-name>} as
|
|
|
705 a password.
|
|
|
706
|
|
|
707 @example
|
|
|
708 Name (ftp.xemacs.org): anonymous
|
|
|
709 331 Guest login ok, send EMAIL address (e.g@. user@@host.domain)
|
|
|
710 as password.
|
|
|
711 Password:
|
|
|
712 230 Guest login ok, access restrictions apply.
|
|
|
713 @end example
|
|
|
714
|
|
|
715 @noindent
|
|
|
716 Move to the Hyperbole directory:
|
|
|
717
|
|
|
718 @example
|
|
24
|
719 ftp> cd pub/xemacs/infodock
|
|
0
|
720 @end example
|
|
|
721
|
|
|
722 @noindent
|
|
|
723 Set your transfer mode to binary:
|
|
|
724
|
|
|
725 @example
|
|
|
726 ftp> bin
|
|
|
727 200 Type set to I.
|
|
|
728 @end example
|
|
|
729
|
|
|
730 @noindent
|
|
|
731 Turn off prompting:
|
|
|
732
|
|
|
733 @example
|
|
|
734 ftp> prompt
|
|
|
735 Interactive mode off.
|
|
|
736 @end example
|
|
|
737
|
|
|
738 @noindent
|
|
|
739 Retrieve just the Hyperbole archive and any diff-based patches (there may not
|
|
|
740 be any patches):
|
|
|
741
|
|
|
742 @example
|
|
|
743 ftp> mget hyperbole*
|
|
|
744 ftp> mget hdiff*
|
|
|
745 @end example
|
|
|
746
|
|
|
747 @noindent
|
|
|
748 Close the ftp connection:
|
|
|
749
|
|
|
750 @example
|
|
|
751 ftp> quit
|
|
|
752 221 Goodbye.
|
|
|
753 @end example
|
|
|
754
|
|
|
755 @cindex gzcat
|
|
|
756 @cindex zcat
|
|
|
757 @cindex gunzip
|
|
|
758 @cindex tar archive
|
|
|
759 @cindex uncompressing archives
|
|
|
760 @cindex unpacking archives
|
|
|
761 @noindent
|
|
|
762 Unpack the tar archive using the GNU version of the @code{zcat} program,
|
|
|
763 sometimes called @code{gzcat} or the @code{gunzip} program:
|
|
|
764
|
|
|
765 @example
|
|
|
766 zcat hyperbole*tar.gz | tar xvf -
|
|
|
767 or
|
|
|
768 gunzip hyperbole*tar.gz; tar xvf hyperbole*tar
|
|
|
769 @end example
|
|
|
770
|
|
|
771 @noindent
|
|
|
772 Apply any patches you retrieved:
|
|
|
773
|
|
|
774 @example
|
|
|
775 cd hyperbole; patch < <patch-file>
|
|
|
776 @end example
|
|
|
777
|
|
|
778
|
|
|
779 @node Building, Installing, Obtaining, Installation
|
|
|
780 @section Building
|
|
|
781
|
|
|
782 @vindex file, Makefile
|
|
|
783 @vindex file, hsite.el
|
|
|
784 @cindex Hyperbole, building
|
|
|
785 @cindex building Hyperbole
|
|
|
786 The following explains how to Use the Hyperbole @file{Makefile} to
|
|
|
787 compile any needed code, to generate the @file{hsite.el} file used for
|
|
|
788 site-specific Hyperbole customization, and to produce printable
|
|
|
789 documentation.
|
|
|
790
|
|
|
791 @vindex EMACS, environment variable
|
|
|
792 @cindex compiling Lisp
|
|
|
793 @cindex Lisp compilation
|
|
|
794 Edit the line near the top of @file{Makefile} that represents the emacs
|
|
|
795 version that you use, so that it corresponds to the emacs executable
|
|
|
796 name used on your system. Then immediatly below there, set the
|
|
|
797 @var{EMACS} variable to the variable name for the emacs that you will
|
|
|
798 use to compile the Hyperbole Lisp files.
|
|
|
799
|
|
|
800 @vindex SITE-PRELOADS, environment variable
|
|
|
801 You may also have to set the @var{SITE-PRELOADS} variable defined further down
|
|
|
802 in the file; follow the instructions that precede the @var{SITE-PRELOADS =}
|
|
|
803 line. Make these changes now and save the @file{Makefile}.
|
|
|
804
|
|
|
805 @cindex HYPERBOLE-DIR
|
|
|
806 The following instructions use the term @file{<HYPERBOLE-DIR>/} to refer
|
|
|
807 to your @file{hyperbole/} directory, so substitute your own value.
|
|
|
808
|
|
|
809 @noindent
|
|
|
810 To install Hyperbole for use with InfoDock, XEmacs, GNU Emacs or Epoch, from
|
|
|
811 a shell:
|
|
|
812
|
|
|
813 @example
|
|
|
814 cd <HYPERBOLE-DIR>; make
|
|
|
815 @end example
|
|
|
816
|
|
|
817 @noindent
|
|
|
818 All of the .elc compiled Lisp files are already built for XEmacs and V19, so
|
|
|
819 this build will finish very quickly. If you really want to rebuild all of
|
|
|
820 the .elc files, use:
|
|
|
821
|
|
|
822 @example
|
|
|
823 cd <HYPERBOLE-DIR>; make all-elc
|
|
|
824 @end example
|
|
|
825
|
|
|
826 @cindex Postscript
|
|
|
827 @cindex manual, generating Postscript
|
|
|
828 @vindex file, man/hyperbole.ps
|
|
|
829 @noindent
|
|
|
830 To produce the Postscript version of the Hyperbole manual, you must have
|
|
|
831 the TeX formatter on your system:
|
|
|
832
|
|
|
833 @example
|
|
|
834 cd <HYPERBOLE-DIR>; make ps
|
|
|
835 @end example
|
|
|
836
|
|
|
837 @noindent
|
|
|
838 To install Hyperbole for use with GNU Emacs V18 or Epoch:
|
|
|
839
|
|
|
840 @example
|
|
|
841 cd <HYPERBOLE-DIR>; make all-elc-v18
|
|
|
842 @end example
|
|
|
843
|
|
|
844 @noindent
|
|
|
845 This will produce a complete set of Emacs V18 .elc files.
|
|
|
846
|
|
|
847
|
|
|
848 @node Installing, Configuring, Building, Installation
|
|
|
849 @section Installing
|
|
|
850
|
|
|
851 @cindex configuration
|
|
|
852 You may want to explore the Hyperbole configuration options before
|
|
|
853 installing it. @xref{Configuring}. If you just want to get up and
|
|
|
854 running quickly, however, there is no need to configure anything, just
|
|
|
855 follow these instructions to install Hyperbole.
|
|
|
856
|
|
|
857 @cindex Hyperbole, initializing
|
|
|
858 @cindex initializing Hyperbole
|
|
|
859 @cindex installation
|
|
|
860 @cindex site initialization
|
|
|
861 @vindex file, hsite.el
|
|
|
862 @vindex file, ~/.emacs
|
|
|
863 Add the following lines to a site initialization file such as
|
|
|
864 @file{site-start.el} to set up so that all users have Hyperbole
|
|
|
865 loaded for them when they run Emacs. Otherwise, each user will have to
|
|
|
866 add these lines to his own @file{~/.emacs} initialization file.
|
|
|
867
|
|
|
868 @cindex autoloading Hyperbole
|
|
|
869 @cindex Hyperbole, autoloading
|
|
|
870 @noindent
|
|
|
871 To autoload Hyperbole so that it loads only when needed:
|
|
|
872
|
|
|
873 @vindex hyperb:dir
|
|
|
874 @vindex file, hversion.el
|
|
|
875 @vindex file, hyperbole.el
|
|
|
876 @lisp
|
|
|
877 (defvar hyperb:dir "<HYPERBOLE-DIR>/")
|
|
|
878 "Directory where the Hyperbole executable code is kept.
|
|
|
879 It must end with a directory separator character.")
|
|
|
880
|
|
|
881 (load (expand-file-name "hversion" hyperb:dir))
|
|
|
882 (load (expand-file-name "hyperbole" hyperb:dir))
|
|
|
883 @end lisp
|
|
|
884
|
|
|
885 @cindex loading Hyperbole
|
|
|
886 @cindex Hyperbole, loading
|
|
|
887 This establishes a few key bindings and sets up Hyperbole to
|
|
|
888 automatically load whenever you activate its menu. If you would rather
|
|
|
889 have the whole Hyperbole system loaded when you start up so that you can
|
|
|
890 always use the Smart Keys and other facilities, add the additional line:
|
|
|
891
|
|
|
892 @lisp
|
|
|
893 (require 'hsite)
|
|
|
894 @end lisp
|
|
|
895
|
|
|
896 If you use mouse keys, be sure to add the above lines after any setup of
|
|
|
897 mouse key bindings, to ensure that Hyperbole's mouse keys are properly
|
|
|
898 initialized. @xref{Smart Keys}, for further details. If you use any
|
|
|
899 Hyperbole mail or news support, @ref{Buttons in Mail}, be certain to
|
|
|
900 perform all of your personal mail/news initializations before the point
|
|
|
901 at which you load Hyperbole. Otherwise, the mail/news support may not
|
|
|
902 be configured properly. For example, if you use the Emacs add-on
|
|
|
903 Supercite package, its setup should come before Hyperbole initialization.
|
|
|
904
|
|
|
905 @cindex Hyperbole manual
|
|
|
906 @noindent
|
|
|
907 The Hyperbole Manual is included in the distribution in two forms:
|
|
|
908
|
|
|
909 @cindex Info manual
|
|
|
910 @cindex Texinfo manual
|
|
|
911 @vindex file, man/hyperbole.info
|
|
|
912 @vindex file, man/hyperbole.texi
|
|
|
913 @example
|
|
|
914 @file{man/hyperbole.info} - online version
|
|
|
915 @file{man/hyperbole.texi} - source form
|
|
|
916 @end example
|
|
|
917
|
|
|
918 @vindex Info-directory-list
|
|
|
919 @noindent
|
|
|
920 To add pointers to the Info version of the Hyperbole manual within your
|
|
|
921 Info directory, follow these instructions. If @var{Info-directory-list}
|
|
|
922 is bound as a variable within your Emacs (all versions except V18 and
|
|
|
923 Epoch), then you can simply set it so that <HYPERBOLE-DIR> is an element
|
|
|
924 in the list:
|
|
|
925
|
|
|
926 @lisp
|
|
|
927 (setq Info-directory-list (cons "<HYPERBOLE-DIR>" Info-directory-list))
|
|
|
928 @end lisp
|
|
|
929
|
|
|
930 @noindent
|
|
|
931 Otherwise, from a shell:
|
|
|
932
|
|
|
933 @vindex Info-directory
|
|
|
934 @example
|
|
|
935 cd to the directory given by your @var{Info-directory} variable
|
|
|
936 rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .
|
|
|
937 @end example
|
|
|
938
|
|
|
939 @noindent
|
|
|
940 For all versions of Emacs, add an Info menu entry for the Hyperbole
|
|
|
941 manual in your Info @file{dir} file (the `*' should be placed in the
|
|
|
942 first column of the file):
|
|
|
943
|
|
|
944 @example
|
|
|
945 * Hyperbole:: GNU Emacs-based everyday information management system.
|
|
|
946 Use @{C-h h d d@} for a demonstration. Includes context-sensitive
|
|
|
947 mouse and keyboard support, a powerful rolodex, an autonumbered
|
|
|
948 outliner with hyperlink anchors for each outline cell, and extensible
|
|
|
949 hypertext facilities including hyper-links in mail and news messages.
|
|
|
950 @end example
|
|
|
951
|
|
|
952 @cindex invoking Hyperbole
|
|
|
953 @cindex starting Hyperbole
|
|
|
954 @cindex Hyperbole, starting
|
|
|
955 @cindex Hyperbole main menu
|
|
|
956 @kindex C-h h
|
|
|
957 @findex hyperbole
|
|
|
958 That's all there is to the installation. Once Hyperbole has been
|
|
|
959 installed for use at your site, you can invoke it with @{@kbd{C-h h}@}
|
|
|
960 or @{@kbd{M-x hyperbole @key{RET}}@} to bring up the Hyperbole main menu
|
|
|
961 in the minibuffer window.
|
|
|
962
|
|
|
963
|
|
|
964 @node Configuring, , Installing, Installation
|
|
|
965 @section Configuring
|
|
|
966
|
|
24
|
967 @cindex menu, Cust
|
|
|
968 @cindex customization
|
|
|
969 Major Hyperbole user options can be set from the window-system-based
|
|
|
970 Customization submenu below the Hyperbole menu. Alternatively, the
|
|
|
971 minibuffer-based menu, Cust/ may be used.
|
|
|
972
|
|
0
|
973 @cindex configuration
|
|
|
974 @vindex file, hyperbole.el
|
|
|
975 @vindex file, hsite.el
|
|
24
|
976 There are many additional Hyperbole configuration options that may be
|
|
|
977 changed by editing the @file{hyperbole.el} and @file{hsite.el} files in
|
|
|
978 the @file{hyperbole/} directory. The following sections discuss the
|
|
0
|
979 configuration options most likely to be of interest to users.
|
|
|
980
|
|
|
981 @menu
|
|
|
982 * Internal Viewers::
|
|
|
983 * External Viewers::
|
|
|
984 * Link Variable Substitution::
|
|
|
985 * Button Colors::
|
|
|
986 @end menu
|
|
|
987
|
|
|
988
|
|
|
989 @node Internal Viewers, External Viewers, Configuring, Configuring
|
|
|
990 @subsection Internal Viewers
|
|
|
991 @vindex hpath:display-alist
|
|
|
992 @vindex file, hsite.el
|
|
|
993 @cindex file display function
|
|
|
994 @cindex display function
|
|
|
995 @cindex internal viewer
|
|
|
996 @cindex link, display function
|
|
|
997 When given a file name, Hyperbole will by default display the file for
|
|
|
998 editing within an Emacs buffer. The @var{hpath:display-alist} variable
|
|
|
999 can be used to specify file name patterns, such as matching suffixes,
|
|
|
1000 which will invoke a special Emacs Lisp function to display any matching
|
|
|
1001 files within Emacs. This can be used to format raw data files for
|
|
|
1002 convenient display.
|
|
|
1003
|
|
|
1004 Configure the @var{hpath:display-alist} variable in @file{hsite.el}.
|
|
|
1005 Its value is an association list whose elements are
|
|
|
1006 (<file-name-regular-expression> . <function-of-one-arg>) pairs. Any
|
|
|
1007 path whose name matches a <file-name-regular-expression> will be
|
|
|
1008 displayed by calling the associated <function-of-one-arg> with the file
|
|
|
1009 name as the argument.@refill
|
|
|
1010
|
|
|
1011 @xref{External Viewers}, for instructions on associating file names with
|
|
|
1012 external, window-system specific viewers.
|
|
|
1013
|
|
|
1014 @node External Viewers, Link Variable Substitution, Internal Viewers, Configuring
|
|
|
1015 @subsection External Viewers
|
|
|
1016 @vindex hpath:find-alist
|
|
|
1017 @vindex file, hsite.el
|
|
|
1018 @cindex window system
|
|
|
1019 @cindex external program
|
|
|
1020 @cindex external viewer
|
|
|
1021 @cindex link, viewer program
|
|
|
1022 If you will be using Hyperbole under a window system, you may want to
|
|
|
1023 configure the @var{hpath:find-alist} variable in @file{hsite.el} to
|
|
|
1024 support hyperlinks which open files using non-Emacs tools, e.g@. a
|
|
|
1025 fax reader or a bitmap viewer.
|
|
|
1026
|
|
|
1027 The value of @var{hpath:find-alist} is determined when Hyperbole is
|
|
|
1028 initialized based upon the current window system and the version of
|
|
|
1029 Emacs in use. The value is an association list whose elements are
|
|
|
1030 (<file-name-regular-expression> . <viewer-program>) pairs. Any path
|
|
|
1031 whose name matches a <file-name-regular-expression> will be
|
|
|
1032 displayed using the corresponding viewer-program. If a <viewer-program>
|
|
|
1033 entry contains a @code{%s} string, the filename to display will be
|
|
|
1034 substituted at that point within the string. Otherwise, the filename
|
|
|
1035 will be appended to the <viewer-program> entry. See the "x-suffixes"
|
|
|
1036 and "nextstep-suffixes" settings within the definition of
|
|
|
1037 @var{hpath:find-alist} as examples.@refill
|
|
|
1038
|
|
|
1039 @node Link Variable Substitution, Button Colors, External Viewers, Configuring
|
|
|
1040 @subsection Link Variable Substitution
|
|
|
1041 @vindex hpath:variables
|
|
|
1042 @cindex environment variables
|
|
|
1043 @cindex Emacs Lisp variables
|
|
|
1044 @cindex Lisp variables
|
|
|
1045 Another variable to consider modifying in the @file{hsite.el} file is
|
|
|
1046 @var{hpath:variables}. This variable consists of a list of Emacs Lisp
|
|
|
1047 variable names, each of which may have a pathname or a list of pathnames
|
|
|
1048 as a value. Whenever a Hyperbole file or directory link button is
|
|
|
1049 created, its pathname is compared against the values in
|
|
|
1050 @var{hpath:variables}. The first match found, if any, is selected and
|
|
|
1051 its associated variable name is substituted into the link pathname, in
|
|
|
1052 place of its literal value. When the link is resolved (the button is
|
|
|
1053 activated), Hyperbole replaces each variable with the first matching
|
|
|
1054 value from this list. (Environment variables are also replaced whenever
|
|
|
1055 link paths are resolved.
|
|
|
1056
|
|
|
1057 This permits sharing of links over wide areas, where the variable values
|
|
|
1058 may differ between link creator and link activator. The entire process
|
|
|
1059 is wholly transparent to the user; it is explained here simply to help
|
|
|
1060 you in deciding whether or not to modify the value of
|
|
|
1061 @var{hpath:variables}.
|
|
|
1062
|
|
|
1063 @node Button Colors, , Link Variable Substitution, Configuring
|
|
|
1064 @subsection Configuring Button Colors
|
|
|
1065 @cindex XEmacs support
|
|
|
1066 @cindex Emacs 19 support
|
|
|
1067 @cindex Epoch support
|
|
|
1068 @cindex button highlighting
|
|
|
1069 @cindex button flashing
|
|
|
1070 @vindex file, hui-ep*.el
|
|
|
1071 @findex hproperty:cycle-but-color
|
|
|
1072 When Hyperbole is run under a window system together with Emacs 19,
|
|
|
1073 XEmacs or Epoch, it automatically highlights any explicit buttons in
|
|
|
1074 a buffer and makes them flash when selected. The main setting
|
|
|
1075 you may want change is the selection of a color (or style) for button
|
|
|
1076 highlighting and button flashing. See the @file{hui-*-b*.el} files for
|
|
|
1077 lists of potential colors and the code which supports this behavior. A
|
|
|
1078 call to @code{(hproperty:cycle-but-color)} within a Hyperbole
|
|
|
1079 initialization sequence in the @file{hsite.el} file changes the color
|
|
|
1080 used to highlight and flash explicit buttons.
|
|
|
1081
|
|
|
1082 @cindex button emphasis
|
|
|
1083 @vindex hproperty:but-emphasize-p
|
|
|
1084 @vindex file, hsite.el
|
|
|
1085 Additionally, under XEmacs and Emacs 19, if @var{hproperty:but-emphasize-p}
|
|
|
1086 is set to @code{t} in @file{hsite.el}, then whenever the mouse pointer
|
|
|
1087 moves over an explicit button, it will be emphasized in a different
|
|
|
1088 color or style. This emphasis is in addition to any non-mouse-sensitive
|
|
|
1089 button highlighting.
|
|
|
1090
|
|
|
1091 @cindex button highlighting, forcing
|
|
|
1092 @findex hproperty:but-create
|
|
|
1093 If you read in a file with explicit buttons before you load Hyperbole,
|
|
|
1094 these buttons won't be highlighted. Load Hyperbole and then use
|
|
|
1095 @code{M-x hproperty:but-create @key{RET}} to highlight the buttons in
|
|
|
1096 the current buffer.
|
|
|
1097
|
|
|
1098
|
|
|
1099 @node Buttons, Smart Keys, Installation, Top
|
|
|
1100 @chapter Buttons
|
|
|
1101
|
|
|
1102 This chapter explains the user-level notion of Hyperbole buttons.
|
|
|
1103 Hyperbole buttons that are stored in files persist across Emacs
|
|
|
1104 sessions, so they provide a convenient means of linking from one
|
|
|
1105 information source to another.
|
|
|
1106
|
|
|
1107 @menu
|
|
|
1108 * Explicit Buttons::
|
|
|
1109 * Global Buttons::
|
|
|
1110 * Implicit Buttons::
|
|
|
1111 * Action Types::
|
|
|
1112 * Button Type Precedence::
|
|
|
1113 * Button Files::
|
|
|
1114 * Utilizing Explicit Buttons::
|
|
|
1115 @end menu
|
|
|
1116
|
|
|
1117 @node Explicit Buttons, Global Buttons, Buttons, Buttons
|
|
|
1118 @section Explicit Buttons
|
|
|
1119
|
|
|
1120 @cindex explicit button
|
|
|
1121 @cindex button, explicit
|
|
|
1122 @cindex button label
|
|
|
1123 Hyperbole creates and manages @emph{explicit buttons} which look like
|
|
|
1124 this @code{<(fake button)>} to a Hyperbole user. They are quickly
|
|
|
1125 recognizable, yet relatively non-distracting as one scans the text in
|
|
|
1126 which they are embedded. The text between the @code{<(} and
|
|
|
1127 @code{)>} delimiters is called the @dfn{button label}. Spacing between
|
|
|
1128 words within a button label is irrelevant to Hyperbole, so button labels
|
|
|
1129 may wrap across several lines without causing a problem.
|
|
|
1130
|
|
|
1131 @cindex button data
|
|
|
1132 @cindex button attribute
|
|
|
1133 @vindex file, .hypb
|
|
|
1134 Hyperbole stores the @dfn{button data} that gives an explicit button its
|
|
|
1135 behavior, separately from the button label, in a file named @file{.hypb}
|
|
|
1136 within the same directory as the file in which the button is created.
|
|
|
1137 Thus, all files in the same directory share a common button data file.
|
|
|
1138 Button data is comprised of individual @dfn{button attribute} values. A
|
|
|
1139 user never sees this data in its raw form but may see a formatted
|
|
|
1140 version by asking for help on a button.
|
|
|
1141
|
|
|
1142 @cindex button, moving
|
|
|
1143 @cindex moving buttons
|
|
|
1144 Explicit buttons may be freely moved about within the buffer in which
|
|
|
1145 they are created. (No present support exists for moving buttons between
|
|
|
1146 buffers). A single button may also appear multiple times within the
|
|
|
1147 same buffer; one simply copies the button label with its delimiters
|
|
|
1148 to a new location in such cases.
|
|
|
1149
|
|
|
1150 Each explicit button is assigned an action type which determines the
|
|
|
1151 actions that it performs. @dfn{Link action types} connect buttons to
|
|
|
1152 particular types of referents. @dfn{Activation} of such buttons then
|
|
|
1153 displays the referents.
|
|
|
1154
|
|
|
1155 @cindex linking, in-place
|
|
|
1156 @cindex Hyperbole data model
|
|
|
1157 Hyperbole does not manage referent data; this is left to the
|
|
|
1158 applications that generate the data. This means that Hyperbole
|
|
|
1159 provides in-place linking and does not require reformatting of data to
|
|
|
1160 integrate it with a Hyperbole framework.
|
|
|
1161
|
|
|
1162 @node Global Buttons, Implicit Buttons, Explicit Buttons, Buttons
|
|
|
1163 @section Global Buttons
|
|
|
1164
|
|
|
1165 @cindex global button
|
|
|
1166 @cindex button, global
|
|
|
1167 @cindex button label
|
|
|
1168 Access to explicit buttons depends upon the information on your screen
|
|
|
1169 since they are embedded within particular buffers. Sometimes it is
|
|
|
1170 useful to activate buttons without regard to the information with which
|
|
|
1171 you are presently working. In such instances, you use @dfn{global
|
|
|
1172 buttons}, which are simply explicit buttons which may be activated or
|
|
|
1173 otherwise operated upon by entering their labels when they are prompted
|
|
|
1174 for, rather than selecting the buttons within a buffer.
|
|
|
1175
|
|
|
1176 If you want a permanent link to a file section that you can follow at
|
|
|
1177 any time, you can use a global button. Or what about an Emacs keyboard
|
|
|
1178 macro that you use frequently? Create an @code{exec-kbd-macro} button
|
|
|
1179 with an easy to type name and then you can easily activate it whenever
|
|
|
1180 the need arises.
|
|
|
1181
|
|
|
1182 @node Implicit Buttons, Action Types, Global Buttons, Buttons
|
|
|
1183 @section Implicit Buttons
|
|
|
1184
|
|
|
1185 @cindex button, implicit
|
|
|
1186 @cindex implicit button
|
|
|
1187 Implicit buttons are those defined by the natural structure of a
|
|
|
1188 document. They are identified by contextual patterns which limit the
|
|
|
1189 locations or states in which they can appear. Their behavior is
|
|
|
1190 determined by one or more actions which they trigger when activated. An
|
|
|
1191 action is derived from either a Hyperbole action type specification,
|
|
|
1192 @ref{Action Types}, or an Emacs Lisp function. Implicit
|
|
|
1193 button types may use the same action types that explicit buttons do.
|
|
|
1194
|
|
|
1195 @vindex file, hibtypes.el
|
|
|
1196 @cindex context
|
|
|
1197 Implicit buttons never have any button data associated with them. They
|
|
|
1198 are recognized in context based on predicate matches defined within
|
|
|
1199 implicit button types. For example, Hyperbole recognizes file names
|
|
|
1200 enclosed in double quotes and can quickly display their associated files
|
|
|
1201 in response to simple mouse clicks.
|
|
|
1202
|
|
|
1203 @cindex ibtypes, list of
|
|
|
1204 @noindent
|
|
|
1205 See @file{hibtypes.el} for complete examples. Standard implicit button
|
|
24
|
1206 types are listed below in the order in which Hyperbole tries to match
|
|
|
1207 to the types when looking for an implicit button.
|
|
0
|
1208
|
|
|
1209 @table @code
|
|
|
1210
|
|
|
1211 @item doc-id
|
|
|
1212 @findex ibtypes::doc-id
|
|
|
1213 @cindex online library
|
|
|
1214 @cindex document identifier
|
|
|
1215 Displays an index entry for a site-specific document given its id. Ids
|
|
24
|
1216 must be delimited by `doc-id-start' and `doc-id-end' and must match the
|
|
|
1217 function given by `doc-id-p'. This permits creation of catalogued
|
|
0
|
1218 online libraries. See @file{$@{hyperb:dir@}/hib-doc-id.el} for more
|
|
|
1219 information.@refill
|
|
|
1220
|
|
24
|
1221 @item completion
|
|
|
1222 @findex ibtypes::completion
|
|
|
1223 @cindex completion
|
|
|
1224 Inserts completion at point into minibuffer or other window.
|
|
|
1225
|
|
|
1226 @item Info-node
|
|
|
1227 @findex ibtypes::Info-node
|
|
|
1228 @cindex Info node
|
|
|
1229 Makes "(file)node" buttons display the associated Info node.
|
|
|
1230
|
|
|
1231 @item mail-address
|
|
|
1232 @findex ibtypes::mail-address
|
|
|
1233 @cindex e-mail address
|
|
|
1234 @cindex rolodex address
|
|
|
1235 @cindex address
|
|
|
1236 If on an e-mail address in a specific buffer type, mail to that address
|
|
|
1237 in another window. Applies to the rolodex match buffer, any buffer
|
|
|
1238 attached to a file in @var{rolo-file-list}, or any buffer with @file{mail}
|
|
|
1239 or @file{rolo} (case-insensitive) within its name.
|
|
|
1240
|
|
|
1241 @item patch-msg
|
|
|
1242 @findex ibtypes::patch-msg
|
|
|
1243 @cindex patch output
|
|
|
1244 Jumps to source code associated with output from the @code{patch}
|
|
|
1245 program. Patch applies diffs to source code.
|
|
|
1246
|
|
0
|
1247 @item elisp-compiler-msg
|
|
|
1248 @findex ibtypes::elisp-compiler-msg
|
|
|
1249 @cindex byte compiler error
|
|
|
1250 @cindex Emacs Lisp compiler error
|
|
|
1251 @cindex compiler error
|
|
|
1252 Jumps to source code for definition associated with byte-compiler error
|
|
|
1253 message. Works when activated anywhere within an error line.
|
|
|
1254
|
|
24
|
1255 @item grep-msg
|
|
|
1256 @findex ibtypes::grep-msg
|
|
|
1257 @cindex grep
|
|
|
1258 @cindex compiler error
|
|
|
1259 Jumps to line associated with grep or compilation error msgs.
|
|
|
1260 Messages are recognized in any buffer.
|
|
|
1261
|
|
0
|
1262 @item debugger-source
|
|
|
1263 @findex ibtypes::debugger-source
|
|
|
1264 @cindex gdb
|
|
|
1265 @cindex dbx
|
|
|
1266 @cindex xdb
|
|
|
1267 @cindex stack frame
|
|
|
1268 @cindex breakpoint
|
|
|
1269 @cindex source line
|
|
|
1270 Jumps to source line associated with debugger stack frame or breakpoint lines.
|
|
|
1271 This works with gdb, dbx, and xdb. Such lines are recognized in any buffer.
|
|
|
1272
|
|
|
1273 @item pathname
|
|
|
1274 @findex ibtypes::pathname
|
|
|
1275 @findex hpath:at-p
|
|
|
1276 @findex hpath:find
|
|
|
1277 @vindex hpath:suffixes
|
|
|
1278 @cindex ange-ftp
|
|
|
1279 @cindex efs
|
|
|
1280 @cindex pathname
|
|
|
1281 @cindex remote path
|
|
|
1282 @cindex filename
|
|
|
1283 @cindex link, pathname
|
|
|
1284 Makes a delimited, valid pathname display the path entry.
|
|
|
1285 Also works for delimited and non-delimited ange-ftp and efs pathnames.
|
|
24
|
1286 Also works for delimited and non-delimited ange-ftp and efs pathnames.
|
|
|
1287 Emacs Lisp library files (filenames that end in .el and .elc) are looked up
|
|
|
1288 using the load-path directory list.
|
|
|
1289
|
|
|
1290 @noindent
|
|
0
|
1291 See @code{hpath:at-p} function documentation for possible delimiters.
|
|
|
1292 See @var{hpath:suffixes} variable documentation for suffixes that are
|
|
|
1293 added to or removed from pathname when searching for a valid match.
|
|
24
|
1294 See @code{hpath:find} function documentation for special file
|
|
|
1295 display options.
|
|
|
1296
|
|
|
1297 @item klink
|
|
|
1298 @findex ibtypes::klink
|
|
|
1299 @cindex klink
|
|
|
1300 @cindex koutline link
|
|
|
1301 @cindex kcell link
|
|
|
1302 Follows a link delimited by <> to a koutline cell.
|
|
|
1303 See documentation for @code{actypes::link-to-kotl} for valid link
|
|
|
1304 specifiers.
|
|
|
1305
|
|
|
1306 @item man-apropos
|
|
|
1307 @findex ibtypes::man-apropos
|
|
|
1308 @item UNIX manual
|
|
|
1309 @item man pages
|
|
|
1310 @item man apropos
|
|
|
1311 Makes man apropos entries display associated man pages when selected.
|
|
|
1312
|
|
|
1313 @item hyp-source
|
|
|
1314 @findex ibtypes::hyp-source
|
|
|
1315 @cindex Hyperbole report
|
|
|
1316 Turns source location entries in Hyperbole reports into buttons that jump to the associated location.
|
|
|
1317
|
|
|
1318 @item hyp-address
|
|
|
1319 @findex ibtypes::hyp-address
|
|
|
1320 @cindex Hyperbole mail list
|
|
|
1321 Turns a Hyperbole e-mail list address into an implicit button which
|
|
|
1322 inserts Hyperbole environment information.
|
|
|
1323 Useful when sending mail to a Hyperbole mail list. See also the
|
|
|
1324 documentation for @code{actypes::hyp-config}.
|
|
0
|
1325
|
|
|
1326 @item rfc
|
|
|
1327 @findex ibtypes::rfc
|
|
|
1328 @cindex Internet RFC
|
|
|
1329 @cindex Request For Comment
|
|
|
1330 @cindex RFC
|
|
|
1331 @cindex ange-ftp
|
|
|
1332 @cindex efs
|
|
|
1333 Retrieves and displays an Internet rfc referenced at point.
|
|
|
1334 Requires ange-ftp or efs when needed for remote retrievals. The
|
|
|
1335 following formats are recognized: RFC822, rfc-822, and RFC 822. The
|
|
|
1336 @var{hpath:rfc} variable specifies the location from which to retrieve
|
|
|
1337 RFCs."
|
|
|
1338
|
|
24
|
1339 @item kbd-key
|
|
|
1340 @findex ibtypes::kbd-key
|
|
|
1341 @cindex key sequence
|
|
|
1342 Executes a key sequence delimited by curly braces.
|
|
|
1343 Key sequences should be in human readable form, e.g@. @{@kbd{C-b}@}.
|
|
|
1344 Forms such as @{@}, @{@}, and @{^b@} will not be recognized.
|
|
|
1345
|
|
|
1346 @item dir-summary
|
|
|
1347 @findex ibtypes::dir-summary
|
|
|
1348 @vindex file, MANIFEST
|
|
|
1349 @vindex file, DIR
|
|
|
1350 Detects filename buttons in files named "MANIFEST" or "DIR".
|
|
|
1351 Displays selected files.
|
|
|
1352 Each file name must be at the beginning of the line and must be followed
|
|
|
1353 by one or more spaces and then another non-space, non-parenthesis, non-brace
|
|
|
1354 character.
|
|
0
|
1355
|
|
|
1356 @item text-toc
|
|
|
1357 @findex ibtypes::text-toc
|
|
|
1358 @cindex table of contents
|
|
|
1359 @cindex toc implicit button type
|
|
|
1360 Jumps to the text file section referenced by a table of contents entry
|
|
|
1361 at point. File name must contain @file{README} and there must be a
|
|
|
1362 `Table of Contents' or `Contents' label on a line by itself (it may
|
|
|
1363 begin with an asterisk), preceding the table of contents. Each toc
|
|
|
1364 entry must begin with some whitespace followed by one or more asterisk
|
|
|
1365 characters. Each file section name line must start with one or more
|
|
|
1366 asterisk characters at the very beginning of the line.
|
|
|
1367
|
|
24
|
1368 @item cscope
|
|
|
1369 @findex ibtypes::cscope
|
|
|
1370 @cindex C/C++ call trees
|
|
|
1371 @cindex C/C++ cross-reference
|
|
|
1372 @cindex Cscope
|
|
|
1373 Jumps to C/C++ source line associated with Cscope C analyzer output line.
|
|
|
1374 Requires pre-loading of the cscope.el Lisp library available from the Emacs
|
|
|
1375 Lisp archives and the commercial cscope program available from UNIX System
|
|
|
1376 Laboratories. Otherwise, does nothing.
|
|
|
1377
|
|
|
1378 @item rfc-toc
|
|
|
1379 @findex ibtypes::rfc-toc
|
|
|
1380 @cindex Internet RFC
|
|
|
1381 @cindex Request For Comment
|
|
|
1382 @cindex RFC
|
|
|
1383 @cindex table of contents
|
|
|
1384 Summarizes contents of an Internet rfc from anywhere within rfc buffer.
|
|
|
1385 Each line in summary may be selected to jump to section.
|
|
|
1386
|
|
|
1387 @item annot-bib
|
|
|
1388 @findex ibtypes::annot-bib
|
|
|
1389 @cindex bibliography
|
|
|
1390 @cindex reference
|
|
|
1391 Displays annotated bibliography entries referenced internally, delimeters = [].
|
|
|
1392 References must be delimited by square brackets, must begin with a
|
|
|
1393 word constituent character, and must not be in buffers whose
|
|
|
1394 names begin with a ` ' or `*' character.
|
|
|
1395
|
|
0
|
1396 @item www-url
|
|
|
1397 @findex ibtypes::www-url
|
|
|
1398 @cindex URL
|
|
|
1399 @cindex World-wide Web
|
|
|
1400 @cindex WWW
|
|
|
1401 @cindex Action Key, web browsing
|
|
|
1402 @kindex Action Key, web browsing
|
|
|
1403 @vindex action-key-url-function
|
|
|
1404 When not in a w3 browser buffer, follow any non-ftp url (link) at point.
|
|
|
1405 The variable, @var{action-key-url-function}, can be used to customize
|
|
|
1406 the url browser that is used.
|
|
24
|
1407
|
|
|
1408 @item function-in-buffer
|
|
|
1409 @findex ibtypes::function-in-buffer
|
|
|
1410 @cindex functions
|
|
|
1411 @cindex func-menu
|
|
|
1412 Return function name defined within this buffer that point is within or
|
|
|
1413 after, else nil. This triggers only when the func-menu.el package has
|
|
|
1414 been loaded and the current major mode is one handled by func-menu.
|
|
|
1415
|
|
0
|
1416 @end table
|
|
|
1417
|
|
|
1418 The Hyperbole Smart Keys offer extensive additional context-sensitive
|
|
|
1419 point-and-click type behavior beyond these standard implicit button
|
|
|
1420 types. @xref{Smart Keys}.
|
|
|
1421
|
|
|
1422
|
|
|
1423 @node Action Types, Button Type Precedence, Implicit Buttons, Buttons
|
|
|
1424 @section Action Types
|
|
|
1425
|
|
|
1426 @cindex action type
|
|
|
1427 @cindex argument, use
|
|
|
1428 @cindex action
|
|
|
1429 @dfn{Action types} provide action procedures that specify button behavior.
|
|
|
1430 The arguments needed by an action type are prompted for at button creation
|
|
|
1431 time. When a button is activated, the stored arguments are fed to the
|
|
|
1432 action type's @dfn{action} body to achieve the desired result. Hyperbole
|
|
|
1433 handles all of this transparently.
|
|
|
1434
|
|
|
1435 @cindex actypes, list of
|
|
|
1436 @noindent
|
|
|
1437 Standard action types in alphabetical order include:
|
|
|
1438
|
|
|
1439 @table @code
|
|
|
1440 @item annot-bib
|
|
|
1441 @findex actypes::annot-bib
|
|
|
1442 Follows internal ref KEY within an annotated bibliography, delimiters=[].
|
|
|
1443
|
|
|
1444 @item completion
|
|
|
1445 @findex actypes::completion
|
|
|
1446 Inserts completion at point into minibuffer or other window.
|
|
|
1447 Unless at end of buffer or if completion has already been inserted, then
|
|
|
1448 deletes completions window.
|
|
|
1449
|
|
|
1450 @item eval-elisp
|
|
|
1451 @findex actypes::eval-elisp
|
|
|
1452 Evaluates a Lisp expression LISP-EXPR.
|
|
|
1453
|
|
|
1454 @item exec-kbd-macro
|
|
|
1455 @findex actypes::exec-kbd-macro
|
|
|
1456 Executes KBD-MACRO REPEAT-COUNT times.
|
|
|
1457 KBD-MACRO may be a string of editor command characters or a function symbol.
|
|
|
1458 Optional REPEAT-COUNT nil means execute once, zero means repeat until
|
|
|
1459 error.
|
|
|
1460
|
|
|
1461 @item exec-shell-cmd
|
|
|
1462 @findex actypes::exec-shell-cmd
|
|
|
1463 Executes a SHELL-CMD string asynchronously.
|
|
|
1464 Optional non-nil second argument INTERNAL-CMD means do not display the shell
|
|
|
1465 command line executed. Optional non-nil third argument KILL-PREV means
|
|
|
1466 kill last output to shell buffer before executing SHELL-CMD.
|
|
|
1467
|
|
|
1468 @item exec-window-cmd
|
|
|
1469 @findex actypes::exec-window-cmd
|
|
|
1470 Executes an external window-based SHELL-CMD string asynchronously.
|
|
|
1471
|
|
|
1472 @item hyp-config
|
|
|
1473 @findex actypes::hyp-config
|
|
24
|
1474 Inserts Hyperbole configuration info at end of current buffer or optional OUT-BUF.
|
|
0
|
1475
|
|
|
1476 @item hyp-request
|
|
|
1477 @findex actypes::hyp-request
|
|
24
|
1478 Inserts Hyperbole mail list request help into current buffer or optional OUT-BUF.
|
|
0
|
1479
|
|
|
1480 @item hyp-source
|
|
|
1481 @findex actypes::hyp-source
|
|
24
|
1482 Displays a buffer or file from a line beginning with `hbut:source-prefix'.
|
|
0
|
1483
|
|
|
1484 @item kbd-key
|
|
|
1485 @findex actypes::kbd-key
|
|
|
1486 Executes the function binding for KEY-SEQUENCE, delimited by @{@}.
|
|
|
1487 Returns t if a KEY-SEQUENCE has a binding, else nil.
|
|
|
1488
|
|
|
1489 @item link-to-buffer-tmp
|
|
|
1490 @findex actypes::link-to-buffer-tmp
|
|
|
1491 Displays a BUFFER in another window.
|
|
|
1492 Link is generally only good for current Emacs session.
|
|
24
|
1493 Use `link-to-file' instead for a permanent link.
|
|
0
|
1494
|
|
|
1495 @item link-to-directory
|
|
|
1496 @findex actypes::link-to-directory
|
|
|
1497 Displays a DIRECTORY in Dired mode in another window.
|
|
|
1498
|
|
|
1499 @item link-to-doc
|
|
|
1500 @findex actypes::link-to-doc
|
|
|
1501 Displays online version of a document given by DOC-ID, in other window.
|
|
|
1502 If the online version of a document is not found in
|
|
|
1503 @var{doc-id-indices}, an error is signalled.
|
|
|
1504
|
|
|
1505 @item link-to-ebut
|
|
|
1506 @findex actypes::link-to-ebut
|
|
|
1507 Performs action given by another button, specified by KEY and KEY-FILE.
|
|
|
1508
|
|
|
1509 @item link-to-elisp-doc
|
|
|
1510 @findex actypes::link-to-elisp-doc
|
|
|
1511 Displays documentation for FUNC-SYMBOL.
|
|
|
1512
|
|
|
1513 @item link-to-file
|
|
|
1514 @findex actypes::link-to-file
|
|
|
1515 Displays a PATH in another window scrolled to optional POINT.
|
|
|
1516 With POINT, buffer is displayed with POINT at the top of the window.
|
|
|
1517
|
|
|
1518 @item link-to-file-line
|
|
|
1519 @findex actypes::link-to-file-line
|
|
24
|
1520 Displays a file given by PATH scrolled to LINE-NUM.
|
|
0
|
1521
|
|
|
1522 @item link-to-kcell
|
|
|
1523 @findex actypes::link-to-kcell
|
|
24
|
1524 Displays FILE with kcell given by CELL-REF at window top.
|
|
|
1525 See documentation for `kcell:ref-to-id' for valid cell-ref formats.
|
|
|
1526
|
|
|
1527 @noindent
|
|
0
|
1528 If FILE is nil, the current buffer is used.
|
|
|
1529 If CELL-REF is nil, the first cell in the view is shown.
|
|
|
1530
|
|
|
1531 @item link-to-kotl
|
|
|
1532 @findex actypes::link-to-kotl
|
|
|
1533 Displays at the top of another window the referent pointed to by LINK.
|
|
|
1534 LINK may be of any of the following forms, with or without delimiters:
|
|
|
1535 @example
|
|
|
1536 < pathname [, cell-ref] >
|
|
|
1537 < [-!&] pathname >
|
|
|
1538 < @@ cell-ref >
|
|
|
1539 @end example
|
|
|
1540
|
|
|
1541 @noindent
|
|
|
1542 See documentation for @code{kcell:ref-to-id} for valid cell-ref formats.
|
|
|
1543
|
|
|
1544 @item link-to-Info-node
|
|
|
1545 @findex actypes::link-to-Info-node
|
|
|
1546 Displays an Info NODE in another window.
|
|
24
|
1547 NODE must be a string of the form `(file)nodename'.
|
|
0
|
1548
|
|
|
1549 @item link-to-mail
|
|
|
1550 @findex actypes::link-to-mail
|
|
|
1551 Displays mail msg with MAIL-MSG-ID from MAIL-FILE in other window.
|
|
|
1552 See documentation for the variable @var{hmail:init-function} for
|
|
|
1553 information on how to specify a mail reader to use.
|
|
|
1554
|
|
|
1555 @item link-to-regexp-match
|
|
|
1556 @findex actypes::link-to-regexp-match
|
|
|
1557 Finds REGEXP's Nth occurrence in FILE and displays location at window top.
|
|
|
1558 Returns t if found, signals an error if not.
|
|
|
1559
|
|
|
1560 @item link-to-rfc
|
|
|
1561 @findex actypes::link-to-rfc
|
|
|
1562 Retrieves and displays an Internet rfc given by RFC-NUM.
|
|
|
1563 RFC-NUM may be a string or an integer. Requires ange-ftp or efs for
|
|
|
1564 remote retrievals.
|
|
|
1565
|
|
|
1566 @item link-to-string-match
|
|
|
1567 @findex actypes::link-to-string-match
|
|
|
1568 Finds STRING's Nth occurrence in FILE and displays location at window top.
|
|
|
1569 Returns t if found, nil if not.
|
|
|
1570
|
|
|
1571 @item man-show
|
|
|
1572 @findex actypes::man-show
|
|
|
1573 Displays man page on TOPIC, which may be of the form @code{<command>(<section>}).
|
|
|
1574
|
|
|
1575 @item rfc-toc
|
|
|
1576 @findex actypes::rfc-toc
|
|
|
1577 Computes and displays summary of an Internet rfc in BUF-NAME.
|
|
|
1578 Assumes point has already been moved to start of region to summarize.
|
|
|
1579 Optional OPOINT is point to return to in BUF-NAME after displaying summary.
|
|
|
1580
|
|
|
1581 @item text-toc
|
|
|
1582 @findex actypes::text-toc
|
|
|
1583 @cindex table of contents
|
|
|
1584 @cindex toc action type
|
|
|
1585 Jumps to the text file SECTION referenced by a table of contents entry
|
|
|
1586 at point.
|
|
|
1587
|
|
|
1588 @item www-url
|
|
|
1589 @findex actypes::www-url
|
|
|
1590 @cindex URL
|
|
|
1591 @cindex World-wide Web
|
|
|
1592 @cindex WWW
|
|
|
1593 @vindex action-key-url-function
|
|
|
1594 Follows a link given by URL.
|
|
|
1595 The variable, @var{action-key-url-function}, can be used to customize
|
|
|
1596 the url browser that is used.
|
|
|
1597 @end table
|
|
|
1598
|
|
|
1599 @cindex action
|
|
|
1600 @vindex hui:ebut-prompt-for-action
|
|
|
1601 The use of action types provides a convenient way of specifying button
|
|
|
1602 behavior without the need to know how to program. Expert users who are
|
|
|
1603 familiar with Emacs Lisp, however, may find that they often want to
|
|
|
1604 tailor button actions in a variety of ways not easily captured within a
|
|
|
1605 type system. In such cases, @var{hui:ebut-prompt-for-action} should be
|
|
|
1606 set non-nil. This will cause Hyperbole to prompt for an action to
|
|
|
1607 override the button's action type at each explicit button creation. For
|
|
|
1608 those cases where the action type is sufficient, a nil value should be
|
|
|
1609 entered for the action. An action may be any Lisp form that may be
|
|
|
1610 evaluated.
|
|
|
1611
|
|
|
1612 @node Button Type Precedence, Button Files, Action Types, Buttons
|
|
|
1613 @section Button Type Precedence
|
|
|
1614
|
|
|
1615 @cindex button precedence
|
|
|
1616 @cindex button label overlap
|
|
|
1617 Explicit buttons always take precedence over implicit buttons. Thus, if
|
|
|
1618 a button selection is made which falls within both an explicit and
|
|
|
1619 implicit button, only the explicit button will be selected. Explicit
|
|
|
1620 button labels are not allowed to overlap; Hyperbole's behavior in such
|
|
|
1621 cases is undefined.
|
|
|
1622
|
|
|
1623 @cindex ibtype, evaluation order
|
|
|
1624 If there is no explicit button at point during a selection request, then
|
|
|
1625 each implicit button type predicate is tested in turn until one returns
|
|
|
1626 non-nil or all are exhausted. Since two implicit button types may have
|
|
|
1627 overlapping domains (those contexts in which their predicates are true),
|
|
|
1628 only the first matching type is used. The type predicates are tested
|
|
|
1629 in @strong{reverse} order of definition, i.e@. most recently entered
|
|
|
1630 types are tested first, so that personal types defined after standard
|
|
|
1631 system types take precedence. It is important to keep this order in
|
|
|
1632 mind when defining new implicit button types. By making their match
|
|
|
1633 predicates as specific as possible, one can minimize any overlapping of
|
|
|
1634 implicit button type domains.
|
|
|
1635
|
|
|
1636 @cindex type redefinition
|
|
|
1637 Once a type name is defined, its precedence relative to other types
|
|
|
1638 remains the same even if you redefine the body of the type, as long as
|
|
|
1639 you don't change its name. This allows incremental modifications to
|
|
|
1640 types without having to worry about shifts in type precedence.
|
|
|
1641 @xref{Creating Types}, for information on how to develop
|
|
|
1642 or modify types.
|
|
|
1643
|
|
|
1644 @node Button Files, Utilizing Explicit Buttons, Button Type Precedence, Buttons
|
|
|
1645 @section Button Files
|
|
|
1646
|
|
|
1647 @cindex button files
|
|
|
1648 It is often convenient to create lists of buttons that can be used as
|
|
|
1649 menus to provide centralized access to distributed information pools or
|
|
|
1650 for other purposes. These files can serve as useful roadmaps to help
|
|
|
1651 efficiently guide a user through both unfamiliar and highly familiar
|
|
|
1652 information spaces. Files that are created specifically for this
|
|
|
1653 purpose, we call @dfn{button files}.
|
|
|
1654
|
|
|
1655 @vindex hbmap:filename
|
|
|
1656 @cindex button file, personal
|
|
|
1657 @cindex button file, directory
|
|
|
1658 The Hyperbole menu system provides quick access to two types of these
|
|
|
1659 button files: personal and directory-specific, through the ButFile menu.
|
|
|
1660 (The variable, @var{hbmap:filename}, contains the base name of these
|
|
|
1661 standard button files. Its standard value is @file{HYPB}.)
|
|
|
1662
|
|
|
1663 @vindex dir, ~/.hyperb
|
|
|
1664 @vindex hbmap:dir-user
|
|
|
1665 @cindex global button
|
|
|
1666 A personal button file may serve as a user's own roadmap to frequently
|
|
|
1667 used resources. Selection of the ButFile/PersonalFile menu item
|
|
|
1668 displays this file for editing. The default personal button file is
|
|
|
1669 stored within the directory given by the @var{hbmap:dir-user} variable
|
|
|
1670 whose standard value is @file{~/.hyperb}. The standard Hyperbole
|
|
|
1671 configuration also appends all global buttons to the end of this file,
|
|
|
1672 one per line, as they are created. So you can edit or annotate them
|
|
|
1673 within the file.
|
|
|
1674
|
|
|
1675 A directory-specific button file may exist for each file system
|
|
|
1676 directory. Such files are useful for explaining the contents of
|
|
|
1677 directories and pointing readers to particular highlights within the
|
|
|
1678 directories. Selection of the ButFile/DirFile menu item displays the
|
|
|
1679 button file for the current directory; this provides an easy means of
|
|
|
1680 updating this file when working on a file within the same directory.
|
|
|
1681 If you want to view some other directory-specific button file, simply
|
|
|
1682 use the normal Emacs file finding commands.
|
|
|
1683
|
|
|
1684 One might suggest that menu quick access be provided for group-specific
|
|
|
1685 and site-specific button files. Instead, link buttons to such things
|
|
|
1686 should be placed at the top of your personal button file. This provides
|
|
|
1687 a more flexible means of quick access.
|
|
|
1688
|
|
|
1689 @node Utilizing Explicit Buttons, , Button Files, Buttons
|
|
|
1690 @section Utilizing Explicit Buttons
|
|
|
1691
|
|
|
1692 Explicit buttons are a fundamental building block for creating personal
|
|
|
1693 or organizational hypertext networks with Hyperbole. This section
|
|
|
1694 summarizes the user-level operations available for managing these
|
|
|
1695 buttons.
|
|
|
1696
|
|
|
1697 @menu
|
|
|
1698 * Creation::
|
|
|
1699 * Renaming::
|
|
|
1700 * Deletion::
|
|
|
1701 * Modification::
|
|
|
1702 * Location::
|
|
|
1703 * Buttons in Mail::
|
|
|
1704 * Buttons in News::
|
|
|
1705 @end menu
|
|
|
1706
|
|
|
1707 @node Creation, Renaming, Utilizing Explicit Buttons, Utilizing Explicit Buttons
|
|
|
1708 @subsection Creation
|
|
|
1709
|
|
|
1710 @menu
|
|
|
1711 * By Dragging:: Creation Via Action Key Drags
|
|
|
1712 * By Menu:: Creation Via Menus
|
|
|
1713 @end menu
|
|
|
1714
|
|
|
1715 @node By Dragging, By Menu, Creation, Creation
|
|
|
1716 @subsubsection Creation Via Action Key Drags
|
|
|
1717
|
|
|
1718 @cindex explicit button, creation
|
|
|
1719 @cindex button, creation
|
|
|
1720 @cindex link, creation
|
|
|
1721 @cindex drag
|
|
|
1722 @cindex Action Key drag
|
|
|
1723 The most efficient way to create an explicit button interactively is to
|
|
|
1724 use the mouse Action Key to drag from a button source window to a window
|
|
|
1725 showing its link referent. More specifically, you should split your
|
|
|
1726 current Emacs frame into two windows: one which contains the point at
|
|
|
1727 which you want a button to be inserted and another which shows the point
|
|
|
1728 to which you want to link. Depress the mouse Action Key at the point at
|
|
|
1729 which the button should be inserted, drag to the other window and
|
|
|
1730 release it at the point of the link referent. The process becomes quite
|
|
|
1731 simple with a little practice. (@xref{By Menu, Creation Via Menus}, for a
|
|
|
1732 more detailed explanation of the explicit button creation process.)
|
|
|
1733
|
|
|
1734 Hyperbole uses the link referent context to determine the type of link
|
|
|
1735 to make. If there are a few different types of links which are
|
|
|
1736 applicable from the context, you will be prompted with a list of the
|
|
|
1737 types. Simply use the Action Key or the first letter of the link
|
|
|
1738 type to select one of the type names and to finish the link creation.
|
|
|
1739 Hyperbole will then insert explicit button delimiters around the button
|
|
|
1740 label and will display a message in the minibuffer indicating both the
|
|
|
1741 button name and its action/link type.
|
|
|
1742
|
|
|
1743 @kindex M-o
|
|
|
1744 @kindex C-u M-o
|
|
|
1745 @kindex C-x o
|
|
|
1746 @findex hkey-operate
|
|
|
1747 If you run Emacs under a window system, you can emulate an Action Key
|
|
|
1748 drag from the keyboard by: hitting @{@kbd{M-o}@}, the
|
|
|
1749 @code{hkey-operate} command, at the button source location, moving
|
|
|
1750 to the link destination, e.g@. with @{@kbd{C-x o}@}, and then hitting
|
|
|
1751 @{@kbd{M-o}@} again. This simulates a depress and then release of the
|
|
|
1752 Action Key. @{@kbd{C-u M-o}@} emulates drags of the Assist Key.
|
|
|
1753 This will not work when Hyperbole is run from a dumb terminal Emacs
|
|
|
1754 session since drag actions are not supported without a window system.
|
|
|
1755
|
|
|
1756 @page
|
|
|
1757 @node By Menu, , By Dragging, Creation
|
|
|
1758 @subsubsection Creation Via Menus
|
|
|
1759
|
|
|
1760 You can alternatively use the Hyperbole menus to create explicit
|
|
|
1761 buttons. First, mark a short region of text in any fashion allowed by
|
|
|
1762 GNU Emacs and then select the Hyperbole menu item sequence, Ebut/Create.
|
|
|
1763 You will be prompted for the button's label with the marked region as
|
|
|
1764 the default. If you accept the default and enter the rest of the
|
|
|
1765 information you are prompted for, the button will be created within the
|
|
|
1766 current buffer and Hyperbole will surround the marked region with
|
|
|
1767 explicit button delimiters to indicate success.
|
|
|
1768
|
|
|
1769 If you do not mark a region before invoking the button create command,
|
|
|
1770 you will be prompted for both a label and a target buffer for the button
|
|
|
1771 and the delimited label text will be inserted into the target buffer
|
|
|
1772 after a successful button creation.
|
|
|
1773
|
|
|
1774 After Hyperbole has the button label and its target buffer, it will
|
|
|
1775 prompt you for an action type for the button. Use the @{@kbd{?}@}
|
|
|
1776 completion help key to see the available types. The type selected
|
|
|
1777 determines any following values for which you will be prompted.
|
|
|
1778
|
|
|
1779 @cindex button instance
|
|
|
1780 @cindex instance number
|
|
|
1781 If a previous button with the same label exists in the same buffer,
|
|
|
1782 Hyperbole will add an @dfn{instance number} to the label when it adds
|
|
|
1783 the delimiters so that the name is unique. Thus, you don't have to
|
|
|
1784 worry about accidental button name conflicts. If you want the same
|
|
|
1785 button to appear in multiple places within the buffer, just enter the
|
|
|
1786 label again and delimit it yourself. Hyperbole will interpret all
|
|
|
1787 occurrences of the same delimited label within a buffer as the same
|
|
|
1788 button.
|
|
|
1789
|
|
|
1790 @cindex link, creation
|
|
|
1791 If you create link buttons using the Hyperbole menus, the best technique
|
|
|
1792 is to place on screen both the source buffer for the button and the
|
|
|
1793 buffer to which it will link. Mark the region of text to use for your
|
|
|
1794 button label, invoke the button create command from the menu, choose an
|
|
|
1795 action type which begins with @code{link-to-} and then use the direct
|
|
|
1796 selection techniques mentioned in @ref{Entering Arguments}, to select
|
|
|
1797 the link referent.
|
|
|
1798
|
|
|
1799
|
|
|
1800 @node Renaming, Deletion, Creation, Utilizing Explicit Buttons
|
|
|
1801 @subsection Renaming
|
|
|
1802
|
|
|
1803 @cindex explicit button, renaming
|
|
|
1804 @cindex button, renaming
|
|
|
1805 Once an explicit button has been created, its label text must be
|
|
|
1806 treated specially. Any inter-word spacing within the label may be
|
|
|
1807 freely changed, as may happen when a paragraph is refilled. But a
|
|
|
1808 special command must be invoked to rename it.
|
|
|
1809
|
|
|
1810 The rename command operates in two different ways. If point is within a
|
|
|
1811 button label when it is invoked, it will tell you to edit the button
|
|
|
1812 label and then invoke the rename command again. The second invocation
|
|
|
1813 will actually rename the button. If instead the command is originally
|
|
|
1814 invoked outside of any explicit button, it will prompt for the button
|
|
|
1815 label to replace and the label to replace it with and then will perform
|
|
|
1816 the rename. All occurrences of the same button in the buffer will be
|
|
|
1817 renamed, so you need locate only one occurrence of the button.
|
|
|
1818
|
|
|
1819 @vindex file, .~/.emacs
|
|
|
1820 @vindex file, hsite.el
|
|
|
1821 @kindex C-c C-r
|
|
|
1822 The rename command may be invoked from the Hyperbole menu via
|
|
|
1823 Ebut/Rename. A faster method is to use a key bound to the
|
|
|
1824 @code{hui:ebut-rename} command. Your site installation may include such
|
|
|
1825 a key. @{@kbd{C-h w hui:ebut-rename @key{RET}}@} should show you any
|
|
|
1826 key it is on. If no key binding has been established or if you prefer
|
|
|
1827 one of your own, simply bind it within your @file{~/.emacs} file. We
|
|
|
1828 recommend the @{@kbd{C-c C-r}@} key, as in: @code{(global-set-key
|
|
|
1829 "\C-c\C-r" 'hui:ebut-rename)}.
|
|
|
1830
|
|
|
1831
|
|
|
1832 @node Deletion, Modification, Renaming, Utilizing Explicit Buttons
|
|
|
1833 @subsection Deletion
|
|
|
1834
|
|
|
1835 @cindex explicit button, deleting
|
|
|
1836 @cindex button, deleting
|
|
|
1837 Ebut/Delete works similarly to the Rename command but deletes the
|
|
|
1838 selected button. The button's delimiters are removed to confirm the
|
|
|
1839 delete. If the delete command is invoked with a prefix argument, then
|
|
|
1840 both the button label and the delimiters are removed as confirmation.
|
|
|
1841
|
|
|
1842 @vindex hui:ebut-delete-confirm-p
|
|
|
1843 Presently there is no way to recover a deleted button; it must
|
|
|
1844 be recreated. Therefore, the @var{hui:ebut-delete-confirm-p} variable
|
|
|
1845 is true by default, causing Hyperbole to require confirmation before
|
|
|
1846 interactively deleting explicit buttons. Set it to nil if you prefer no
|
|
|
1847 confirmation.
|
|
|
1848
|
|
|
1849 @node Modification, Location, Deletion, Utilizing Explicit Buttons
|
|
|
1850 @subsection Modification
|
|
|
1851
|
|
|
1852 @cindex explicit button, modifying
|
|
|
1853 @cindex button, modifying
|
|
|
1854 @cindex Smart Mouse Key drag
|
|
|
1855 Ebut/Modify prompts you with each of the elements from the button's
|
|
|
1856 data list and allows you to modify each in turn.
|
|
|
1857
|
|
|
1858 There is a quicker way to modify explicit link buttons. Simply drag with the
|
|
|
1859 mouse Action Key from within the button label to a link destination in a
|
|
|
1860 different window, just as you would when creating a new button with a mouse
|
|
|
1861 drag. Remember that drags may also be emulated from the keyboard.
|
|
|
1862 @xref{Creation}.
|
|
|
1863
|
|
|
1864 @node Location, Buttons in Mail, Modification, Utilizing Explicit Buttons
|
|
|
1865 @subsection Location
|
|
|
1866
|
|
|
1867 @cindex explicit button, summarizing
|
|
|
1868 @cindex button, summarizing
|
|
|
1869 @cindex button, help
|
|
|
1870 The Ebut/Help menu can be used to summarize a single explicit button or
|
|
|
1871 all such buttons within a single buffer. The buttons summarized may
|
|
|
1872 then be activated directly from the summary.
|
|
|
1873
|
|
|
1874 Ebut/Help/BufferButs summarizes the explicit buttons in the order in
|
|
|
1875 which they appear in the buffer. Ebut/Help/CurrentBut summarizes only
|
|
|
1876 the button at point. Ebut/Help/OrderedButs summarizes the buttons in
|
|
|
1877 alphabetical order. All of these summary commands eliminate duplicate
|
|
|
1878 instances of buttons from their help displays.
|
|
|
1879
|
|
|
1880 @cindex explicit button, searching
|
|
|
1881 @cindex button, searching
|
|
|
1882 Ebut/Search prompts for a search pattern and searches across all the
|
|
|
1883 locations in which you have previously created explicit buttons. It
|
|
|
1884 asks you whether to match to any part of a button label or only complete
|
|
|
1885 labels. It then displays a list of button matches with a single line of
|
|
|
1886 surrounding context from their sources. Any button in the match list
|
|
|
1887 may be activated as usual. An Action Key press on the surrounding context
|
|
|
1888 jumps to the associated source line or a press on the filename preceding
|
|
|
1889 the matches jumps to the file without selecting a particular line.
|
|
|
1890
|
|
|
1891 There are presently no user-level facilities for globally locating buttons
|
|
|
1892 created by others or for searching on particular button attributes.
|
|
|
1893
|
|
|
1894 @node Buttons in Mail, Buttons in News, Location, Utilizing Explicit Buttons
|
|
|
1895 @subsection Buttons in Mail
|
|
|
1896
|
|
|
1897 @kindex C-x m
|
|
|
1898 @findex mail
|
|
|
1899 Hyperbole allows the embedding of buttons within electronic mail
|
|
|
1900 messages that are composed in Emacs with the standard @code{(mail)}
|
|
|
1901 command, normally bound to @{@kbd{C-x m}@} or with other Emacs-based
|
|
|
1902 mail composing functions. An enhanced mail reader can then be used
|
|
|
1903 to activate the buttons within messages just like any other buttons.
|
|
|
1904
|
|
|
1905 @cindex button, mailing
|
|
|
1906 @cindex button, posting
|
|
|
1907 @cindex mailing buttons
|
|
|
1908 @cindex posting buttons
|
|
|
1909 @cindex mail reader
|
|
|
1910 @cindex mailer initialization
|
|
|
1911 @cindex RMAIL
|
|
|
1912 @cindex VM
|
|
|
1913 @cindex PIEmail
|
|
|
1914 @cindex MH-e
|
|
|
1915 @cindex GNUS
|
|
|
1916 @cindex USENET
|
|
|
1917 @cindex news
|
|
|
1918 @vindex file, hmail.el
|
|
|
1919 Hyperbole automatically supports the following mail readers: Rmail,
|
|
|
1920 @ref{Rmail,,,emacs, the GNU Emacs Manual}, VM, @ref{Introduction,,,vm,
|
|
|
1921 the VM Manual}, and PIEmail, and MH-e. Button inclusion and activation
|
|
|
1922 within USENET news articles is also supported in the same fashion via
|
|
|
1923 the GNUS news reader, @ref{Introduction,,,gnus, the GNUS Manual}, if
|
|
|
1924 available at your site. (The @file{hmail.el} file provides a
|
|
|
1925 generalized interface that can be used to hook in other mail or news
|
|
|
1926 readers if the necessary interface functions are written.)
|
|
|
1927
|
|
|
1928 @vindex mail-yank-original
|
|
|
1929 @kindex C-c C-y
|
|
|
1930 @cindex mail inclusion
|
|
|
1931 All explicit buttons to be mailed must be created within the outgoing
|
|
|
1932 message buffer. There is no present support for including text from
|
|
|
1933 other buffers or files which contain explicit buttons, except for the
|
|
|
1934 ability to yank the contents of a message being replied to, together
|
|
|
1935 with all of its buttons, via the @code{(mail-yank-original)} command
|
|
|
1936 bound to @{@kbd{C-c C-y}@}. From a user's perspective, buttons are
|
|
|
1937 created in precisely the same way as in any other buffer. They also
|
|
|
1938 appear just like any other buttons to both the message sender and the
|
|
|
1939 reader who uses the Hyperbole enhanced readers. Button operation may be
|
|
|
1940 tested any time before a message is sent. A person who does not use
|
|
|
1941 Hyperbole enhanced mail readers can still send messages with embedded
|
|
|
1942 buttons since mail composing is independent of any mail reader
|
|
|
1943 choice.
|
|
|
1944
|
|
|
1945 Hyperbole buttons embedded within received mail messages act just like
|
|
|
1946 any other buttons. The mail does not contain any of the action type
|
|
|
1947 definitions used by the buttons, so the receiver must have these or she
|
|
|
1948 will receive an error when she activates the buttons. Buttons which
|
|
|
1949 appear in message @emph{Subject} lines are copied to summary buffers
|
|
|
1950 whenever such summaries are generated. Thus, they may be activated from
|
|
|
1951 either the message or summary buffers.
|
|
|
1952
|
|
|
1953 Nothing bad will happen if a mail message with explicit buttons is sent
|
|
|
1954 to a non-Hyperbole user. The user will simply see the text
|
|
|
1955 of the message followed by a series of lines of button data at its end.
|
|
|
1956 Hyperbole mail users never see this data in its raw form.
|
|
|
1957
|
|
|
1958 @vindex smail:comment
|
|
|
1959 @cindex mail comment
|
|
|
1960 In order to alert readers of your mail messages that you can utilize
|
|
|
1961 Hyperbole mail buttons, the system automatically inserts a comment into
|
|
|
1962 each mail message that you compose to announce this fact. The variable,
|
|
|
1963 @var{smail:comment} controls this behavior. See its documentation for
|
|
|
1964 technical details. By default, it produces a message of the form:
|
|
|
1965
|
|
|
1966 @example
|
|
|
1967 Comments: Hyperbole mail buttons accepted, vX.XX.
|
|
|
1968 @end example
|
|
|
1969
|
|
|
1970 @vindex file, ~/.emacs
|
|
|
1971 @noindent
|
|
|
1972 where the X's indicate your Hyperbole version number. You can cut this
|
|
|
1973 out of particular messages before you send them. If you don't want any
|
|
|
1974 message at all, add the following to your @file{~/.emacs} file before
|
|
|
1975 the point at which you load Hyperbole.
|
|
|
1976
|
|
|
1977 @lisp
|
|
|
1978 (setq smail:comment nil)
|
|
|
1979 @end lisp
|
|
|
1980
|
|
|
1981 @cindex actype, link-to-mail
|
|
|
1982 A final mail-related facility provided by Hyperbole is the ability to
|
|
|
1983 save a pointer to a received mail message by creating an explicit button
|
|
|
1984 with a @code{link-to-mail} action type. When prompted for the mail
|
|
|
1985 message to link to, if you press the Action Key on an Rmail message, the
|
|
|
1986 appropriate parameter will be copied to the argument prompt, as
|
|
|
1987 described in @ref{Entering Arguments}.
|
|
|
1988
|
|
|
1989
|
|
|
1990 @node Buttons in News, , Buttons in Mail, Utilizing Explicit Buttons
|
|
|
1991 @subsection Buttons in News
|
|
|
1992
|
|
|
1993 @cindex button, posting
|
|
|
1994 @cindex news reader/poster
|
|
|
1995 @cindex posting news
|
|
|
1996 @cindex GNUS
|
|
|
1997 @cindex USENET
|
|
|
1998 @vindex file, hgnus.el
|
|
|
1999 @vindex file, hsite.el
|
|
|
2000 Explicit buttons may be embedded within outgoing USENET news articles
|
|
|
2001 and may be activated from news articles that are being read. This
|
|
|
2002 support is available for the GNUS news reader. It is enabled by default
|
|
|
2003 within @file{hsite.el} by autoloading the @file{hgnus.el} file.
|
|
|
2004
|
|
|
2005 All Hyperbole support should work just as it does when reading or
|
|
|
2006 sending mail. @xref{Buttons in Mail}. When reading news, buttons which
|
|
|
2007 appear in message @emph{Subject} lines may be activated within the GNUS
|
|
|
2008 subject buffer as well as the article buffer. When posting news, the
|
|
|
2009 *post-news* buffer is used for outgoing news articles rather than the
|
|
|
2010 *mail* buffer.
|
|
|
2011
|
|
|
2012 Remember that the articles you post do not contain the action type
|
|
|
2013 definitions used by the buttons, so the receiver must have these or she
|
|
|
2014 will receive an error when he activates the buttons. You should also
|
|
|
2015 keep in mind that most USENET readers will not be using Hyperbole, so if
|
|
|
2016 they receive a news article containing explicit buttons, they will
|
|
|
2017 wonder what the button data at the end of the message is. You should
|
|
|
2018 therefore limit distribution of such messages. For example, if most
|
|
|
2019 people at your site read news with GNUS and use Hyperbole, it would be
|
|
|
2020 reasonable to embed buttons in postings to local newsgroups.
|
|
|
2021
|
|
|
2022 @cindex news comment
|
|
|
2023 In order to alert readers of your postings that you can utilize
|
|
|
2024 Hyperbole mail buttons embedded within personal replies,
|
|
|
2025 the system automatically inserts the same comment that is included
|
|
|
2026 within mail messages to announce this fact. @xref{Buttons in Mail}, for
|
|
|
2027 details and an explanation of how to turn this feature off.
|
|
|
2028
|
|
|
2029 @node Smart Keys, Menus, Buttons, Top
|
|
|
2030 @chapter Smart Keys
|
|
|
2031
|
|
|
2032 @cindex Smart Key
|
|
|
2033 @cindex mouse support
|
|
|
2034 @cindex Action Key
|
|
|
2035 @cindex Assist Key
|
|
|
2036 @kindex Action Key
|
|
|
2037 @kindex Assist Key
|
|
|
2038 Hyperbole provides two special @dfn{Smart Keys} that perform
|
|
|
2039 context-sensitive operations, the Action Key and the Assist Key. By
|
|
|
2040 default, the @dfn{Action Key} is bound to your shift-middle mouse button (or
|
|
|
2041 shift-left on a 2-button mouse) and the @dfn{Assist Key} is bound to your
|
|
|
2042 shift-right mouse button, assuming Hyperbole is run under an external window
|
|
|
2043 system. (InfoDock users should use the middle mouse button as the
|
|
|
2044 Action Key, instead.)
|
|
|
2045
|
|
|
2046 @findex hmouse-shift-buttons
|
|
|
2047 Mouse configuration is automatic for InfoDock, XEmacs, and Epoch under
|
|
|
2048 the X window system and for GNU Emacs versions 18 and 19 under X,
|
|
|
2049 OpenWindows, NEXTSTEP, SunView and Apollo's Display Manager, assuming
|
|
|
2050 your Emacs program has been built with support for any of these window
|
|
|
2051 systems. The command, @code{hmouse-shift-buttons}, can be used to
|
|
|
2052 select between shifted and unshifted Smart Mouse Keys.
|
|
|
2053
|
|
|
2054 @vindex hkey-init
|
|
|
2055 @kindex C-u M-RET
|
|
|
2056 @kindex M-RET
|
|
|
2057 By default (if @var{hkey-init} is set to @code{t} in @file{hsite.el}),
|
|
|
2058 then @{@kbd{M-@key{RET}}@} may also be used as the Action Key and
|
|
|
2059 @{@kbd{C-u M-@key{RET}}@} may be used as the Assist Key. In many
|
|
|
2060 read-only modes like Dired and Rmail,
|
|
|
2061 @{@key{RET}@} also functions as the Action Key. These key bindings allow
|
|
|
2062 context sensitive operation from any keyboard.
|
|
|
2063
|
|
|
2064 @cindex key binding, smart keys
|
|
|
2065 @cindex smart key commands
|
|
|
2066 @findex action-key
|
|
|
2067 @findex assist-key
|
|
|
2068 @findex action-mouse-key
|
|
|
2069 @findex assist-mouse-key
|
|
|
2070 If you prefer other key bindings, simply bind the commands
|
|
|
2071 @code{action-key} and @code{assist-key} to keyboard keys.
|
|
|
2072 @code{hkey-either} may be used instead if you prefer a single
|
|
|
2073 key binding for both commands; a prefix argument then invokes
|
|
|
2074 @code{assist-key}.
|
|
|
2075
|
|
|
2076 You may also bind @code{action-mouse-key} and @code{assist-mouse-key}
|
|
|
2077 to mouse keys, as you like.
|
|
|
2078
|
|
|
2079 @cindex button activation
|
|
|
2080 @cindex activation
|
|
|
2081 @cindex button help
|
|
|
2082 The Action Key generally selects entities, creates links and
|
|
|
2083 activates buttons. The Assist Key generally provides help,
|
|
|
2084 such as reporting on a button's attributes, or serves a complementary
|
|
|
2085 function to whatever the Action Key does within a context.
|
|
|
2086
|
|
|
2087 @cindex Smart Key operation
|
|
|
2088 You can get a summary of what the Smart Keys do in all of their
|
|
|
2089 different contexts by pressing the Assist Key in the right
|
|
|
2090 corner (within the rightmost 3 characters) of a window modeline or by
|
|
|
2091 using the Hyperbole Doc/SmartKy menu entry.
|
|
|
2092
|
|
|
2093 The following table is an example of this summary. Much of the browsing
|
|
|
2094 power of Hyperbole comes from use of the Smart Keys, so you should spend
|
|
|
2095 some time practicing how to use them. This table may appear daunting at
|
|
|
2096 first, but as you practice and notice that the Smart Keys do just a few
|
|
|
2097 context-sensitive things per editor mode, you will find it easy to just
|
|
|
2098 point and click and let Hyperbole do the rest.
|
|
|
2099
|
|
|
2100 For extensive reference documentation on the Smart Keys, @ref{Smart
|
|
|
2101 Key Reference}.
|
|
|
2102
|
|
|
2103 @page
|
|
|
2104 @iftex
|
|
|
2105 @example
|
|
|
2106 @include ../etc/hypb-mouse.txt
|
|
|
2107 @end example
|
|
|
2108 @end iftex
|
|
|
2109 @ifinfo
|
|
|
2110 @format
|
|
|
2111 @include ../etc/hypb-mouse.txt
|
|
|
2112 @end format
|
|
|
2113 @end ifinfo
|
|
|
2114
|
|
|
2115 @vindex action-key-default-function
|
|
|
2116 @vindex assist-key-default-function
|
|
|
2117 Note how the last line in the table explains the default behavior of the
|
|
|
2118 Smart Keys. That is what they do when they cannot find a context match
|
|
|
2119 at your current location. See the documentation for the variables
|
|
|
2120 @var{action-key-default-function} and @var{assist-key-default-function}
|
|
|
2121 for information on how to customize the behavior of the Smart Keys
|
|
|
2122 within default contexts.
|
|
|
2123
|
|
|
2124 @cindex Hyperbole help
|
|
|
2125 A prime design criterion of Hyperbole's user interface is that one
|
|
|
2126 should be able to see what an operation will do before using it.
|
|
|
2127 The Assist Key shows you what a button or minibuffer menu item will do
|
|
|
2128 before you activate it. Hyperbole also shows the result of directly
|
|
|
2129 selecting an argument value with the mouse, to provide feedback as to
|
|
|
2130 whether the right item has been selected. A second click is necessary
|
|
|
2131 before an argument is accepted and processed.
|
|
|
2132
|
|
|
2133 @cindex Smart Key help
|
|
|
2134 @cindex help, Smart Key
|
|
|
2135 @cindex context sensitive help
|
|
|
2136 When you use a mouse and you want to find out what either of the Smart
|
|
|
2137 Keys does within a context, depress the one you want to check on and
|
|
|
2138 hold it down, then press the other and release as you please. A help
|
|
|
2139 buffer will pop up explaining the actions that will be performed in that
|
|
|
2140 context, if any. A press of either Smart Key at the end of that
|
|
|
2141 help buffer will restore your display to its configuration prior to
|
|
|
2142 invoking help.
|
|
|
2143
|
|
|
2144 @kindex C-h A
|
|
|
2145 @vindex hkey-init
|
|
|
2146 By default (if @var{hkey-init} is left set equal to @code{t} in
|
|
|
2147 @file{hsite.el}), then @{@kbd{C-h A}@} will display this same
|
|
|
2148 context-sensitive help for the Action Key while @{@kbd{C-u C-h
|
|
|
2149 A}@} will display the help for the Assist Key. Note that
|
|
|
2150 @{@kbd{C-h a}@} will perform a function unrelated to Hyperbole, so you
|
|
|
2151 must press the shift key when you hit the @kbd{A} character.
|
|
|
2152
|
|
|
2153 @cindex Smart Key toggle
|
|
|
2154 @cindex mouse key toggle
|
|
|
2155 @vindex file, ~/.emacs
|
|
|
2156 @vindex file, hsite.el
|
|
|
2157 @kindex C-c t
|
|
|
2158 When Hyperbole is installed, a key may be bound which allows you
|
|
|
2159 to switch between the Smart Key mouse bindings and your prior ones.
|
|
|
2160 @kbd{C-h w hmouse-toggle-bindings @key{RET}} should show you any key
|
|
|
2161 which performs this command. If no key binding has been established or
|
|
|
2162 if you prefer one of your own, simply select a key and bind it
|
|
|
2163 within your @file{~/.emacs} file. For example, @code{(global-set-key
|
|
|
2164 "\C-ct" 'hmouse-toggle-bindings)}.
|
|
|
2165
|
|
|
2166
|
|
|
2167 @node Menus, Entering Arguments, Smart Keys, Top
|
|
|
2168 @chapter Menus
|
|
|
2169
|
|
|
2170 @cindex InfoDock
|
|
|
2171 @cindex XEmacs
|
|
|
2172 @cindex Emacs 19
|
|
|
2173 @cindex menu use
|
|
|
2174 @cindex menubar, Hyperbole menu
|
|
|
2175 Under InfoDock, XEmacs, and Emacs 19, pulldown and popup menus are
|
|
|
2176 available to invoke Hyperbole commands, including those from the rolodex
|
|
24
|
2177 and the outliner. These menus operate like any other application menus
|
|
|
2178 and are fairly self-explanatory. Use the Quit command on the Hyperbole
|
|
|
2179 menubar menu to get rid of the menu if you do not need it. Invoking
|
|
|
2180 Hyperbole again will add the menu back to the menubar.
|
|
0
|
2181
|
|
|
2182 @cindex minibuffer menus
|
|
|
2183 This section discusses only the specialized @dfn{minibuffer menus} that
|
|
24
|
2184 appear in the minibuffer window and that work with all Emacs versions on
|
|
|
2185 all display devices. Minibuffer menu items may be selected from either
|
|
|
2186 the keyboard or via mouse clicks. When used with the keyboard, they
|
|
|
2187 provide rapid command access similar to key bindings.
|
|
0
|
2188
|
|
|
2189 @kindex C-h h
|
|
|
2190 @vindex action-key-default-function
|
|
|
2191 @cindex menu, top level
|
|
|
2192 The top level menu is invoked from a key given in your @file{hsite.el}
|
|
|
2193 file (by default, @{@kbd{C-h h}@}) or via an Action Key press in a
|
|
|
2194 location with no other action defined. The menu will appear in the
|
|
|
2195 minibuffer and should look mostly like so:
|
|
|
2196
|
|
|
2197 @noindent
|
|
|
2198 @example
|
|
24
|
2199 Hy4> Act Butfile/ Cust/ Doc/ Ebut/ Gbut/ Hist Ibut/ Msg/ Otl/ Rolo/ Win/
|
|
0
|
2200 @end example
|
|
|
2201
|
|
|
2202 @noindent
|
|
|
2203 The above menu items can be summarized as follows:
|
|
|
2204
|
|
|
2205 @table @strong
|
|
|
2206 @cindex menu, Act
|
|
|
2207 @item Act
|
|
|
2208 Perform the action associated with any button at point or prompt for the
|
|
|
2209 name of an explicit button to activate if point is not on one.
|
|
|
2210
|
|
|
2211 @cindex menu, ButFile
|
|
|
2212 @cindex button file, HYPB
|
|
|
2213 @vindex file, HYPB
|
|
|
2214 @item Butfile/
|
|
|
2215 Display a local or global file of buttons, providing easy access.
|
|
|
2216 @file{HYPB} for a local button file and @file{~/.hyperb/HYPB} for your
|
|
|
2217 global file. These are good places to start your button creation testing.
|
|
|
2218
|
|
24
|
2219 @cindex menu, Cust
|
|
|
2220 @cindex customization
|
|
|
2221 @cindex option settings
|
|
|
2222 @item Cust/
|
|
|
2223 Customizes Hyperbole by setting major options.
|
|
|
2224 This includes where Hyperbole link referents are displayed, where URLs
|
|
|
2225 are displayed and whether to use proportional or windowful scrolling
|
|
|
2226 when a Smart Key is pressed at the end of a line. @xref{Configuring}.
|
|
|
2227
|
|
0
|
2228 @cindex menu, EBut
|
|
|
2229 @item Ebut/
|
|
24
|
2230 All explicit button commands. The window-system-based Hyperbole
|
|
|
2231 menu includes a menu item that activates each explicit button found
|
|
|
2232 in the current buffer.
|
|
0
|
2233
|
|
|
2234 @cindex menu, Doc
|
|
|
2235 @cindex menu, Types
|
|
|
2236 @item Doc/
|
|
24
|
2237 Hyperbole documentation quick access. Contains About item describing
|
|
|
2238 Hyperbole and a Demo item which demonstrates a number of Hyperbole
|
|
|
2239 features. It also contains the Types/ submenu for documentation on
|
|
|
2240 Hyperbole implicit button and action types.
|
|
0
|
2241
|
|
|
2242 @cindex menu, Global Buttons
|
|
|
2243 @item Gbut/
|
|
|
2244 All global button commands. Global buttons are accessed by name
|
|
24
|
2245 rather than by direct selection. The window-system-based Hyperbole
|
|
|
2246 menu also includes a menu item that activates each global button.
|
|
0
|
2247
|
|
|
2248 @cindex menu, History
|
|
|
2249 @cindex history
|
|
|
2250 @item Hist
|
|
|
2251 Jumps back to last position in button traversal history.
|
|
|
2252
|
|
|
2253 @cindex menu, Implicit Buttons
|
|
|
2254 @item Ibut/
|
|
|
2255 All implicit button commands.
|
|
|
2256
|
|
|
2257 @cindex menu, Message
|
|
|
2258 @item Msg/
|
|
24
|
2259 Hyperbole-specific mail and news messaging support commands. Use this
|
|
|
2260 to send mail to a Hyperbole mail list or to add/modify/delete your entry
|
|
|
2261 on a list.
|
|
0
|
2262
|
|
|
2263 @cindex menu, Outliner
|
|
|
2264 @item Otl/
|
|
|
2265 Autonumbered, structured outliner and hyper-node manager commands.
|
|
|
2266 @xref{Outliner}.
|
|
|
2267
|
|
|
2268 @cindex menu, Rolodex
|
|
|
2269 @item Rolo/
|
|
|
2270 Hierarchical, multi-file rolodex lookup and edit commands.
|
|
|
2271 @xref{Rolodex}.
|
|
|
2272
|
|
|
2273 @cindex menu, Window Configurations
|
|
|
2274 @cindex menu, Windows
|
|
|
2275 @item Win/
|
|
|
2276 Window configuration management such as adding and restoring window
|
|
|
2277 configurations by name. @xref{Window Configurations}.
|
|
|
2278
|
|
|
2279 @end table
|
|
|
2280
|
|
|
2281 @cindex submenus
|
|
|
2282 @cindex menu help
|
|
|
2283 @cindex help, menu items
|
|
|
2284 All menu items are selected via the first character of their names
|
|
|
2285 (letter case does not matter) or via a press of the Action Key. "/" at
|
|
|
2286 the end of an item name indicates that it brings up a sub-menu. A press
|
|
|
2287 of the Assist Key on an item displays help for the item, including the
|
|
|
2288 action that it performs.
|
|
|
2289
|
|
|
2290 @kindex C-t
|
|
|
2291 @kindex q
|
|
|
2292 @kindex C-g
|
|
|
2293 While a menu is active, to re-activate the top-level Hyperbole menu, you
|
|
|
2294 must use @{@kbd{C-t}@}. This allows you to browse the submenus and then
|
|
|
2295 return to the top. You can quit without selecting an item by using
|
|
|
2296 @{@kbd{q}@}. @{@kbd{C-g}@} aborts whether you are at a menu prompt or
|
|
|
2297 any other Hyperbole prompt.
|
|
|
2298
|
|
|
2299
|
|
|
2300
|
|
|
2301 @node Entering Arguments, Outliner, Menus, Top
|
|
|
2302 @chapter Entering Arguments
|
|
|
2303
|
|
|
2304 @cindex argument entry
|
|
|
2305 @cindex direct selection
|
|
|
2306 @cindex double click
|
|
|
2307 Many Hyperbole commands prompt you for arguments. The standard
|
|
|
2308 Hyperbole user interface has an extensive core of argument types that it
|
|
|
2309 recognizes. Whenever Hyperbole is prompting you for an argument, it
|
|
|
2310 knows the type that it needs and provides some error checking to help
|
|
|
2311 you get it right. More importantly, it allows you to press the Action
|
|
|
2312 Key within an entity that you want to use as an argument and it will grab the
|
|
|
2313 appropriate thing and show it to you at the input prompt within the
|
|
|
2314 minibuffer. If you press the Action Key again at the same point (click
|
|
|
2315 with a mouse) on the same thing again, it accepts the entity as the
|
|
|
2316 argument and moves on. Thus, a double click registers a desired
|
|
|
2317 argument. Double-quoted strings, pathnames, mail messages, Info nodes,
|
|
|
2318 dired listings, buffers, numbers, completion items and so forth are all
|
|
|
2319 recognized at appropriate times. All of the argument types mentioned in
|
|
|
2320 the documentation for the Emacs Lisp @code{(interactive)} function are
|
|
|
2321 recognized. Experiment a little and you will quickly get used to this
|
|
|
2322 direct selection technique.
|
|
|
2323
|
|
|
2324 @cindex completion
|
|
|
2325 Wherever possible, standard Emacs completion is offered, see
|
|
|
2326 @ref{Completion,,,emacs, the Gnu Emacs Manual}. Remember to use @{@kbd{?}@}
|
|
|
2327 to see what your possibilities for an argument are. Once you have a
|
|
|
2328 list of possible completions on screen, you can double click the Action
|
|
|
2329 Key on any one to enter it as the argument.
|
|
|
2330
|
|
|
2331
|
|
|
2332 @node Outliner, Rolodex, Entering Arguments, Top
|
|
|
2333 @chapter Outliner
|
|
|
2334
|
|
|
2335 @cindex outliner
|
|
|
2336 @cindex autonumber
|
|
|
2337 @cindex relative autonumber
|
|
|
2338 @cindex permanent identifier
|
|
|
2339 @cindex idstamp
|
|
|
2340 @cindex hyperlink anchor
|
|
|
2341 The Hyperbole outliner, also known as the Koutliner (pronounced
|
|
|
2342 Kay-outliner), produces structured, autonumbered documents composed of
|
|
|
2343 hierarchies of cells. Each @dfn{cell} has two identifiers, a
|
|
|
2344 @dfn{relative identifier} indicating its present position within the
|
|
|
2345 outline and a @dfn{permanent identifier} called an @dfn{idstamp},
|
|
|
2346 suitable for use within hyperlink references to the cell. The idstamp
|
|
|
2347 is typically not displayed but is available when needed.
|
|
|
2348 @xref{Autonumbering}.
|
|
|
2349
|
|
|
2350 Cells also store their time of creation and the user who created the
|
|
|
2351 cell. User-defined attributes may also be added to cells. @xref{Cell
|
|
|
2352 Attributes}.
|
|
|
2353
|
|
|
2354 @cindex menu, Outline
|
|
|
2355 The outliner works only under GNU Emacs version 19 or higher, XEmacs
|
|
|
2356 version 19.9 or higher or under InfoDock. You can tell whether you are
|
|
|
2357 running a version of Emacs which supports the outliner by hitting
|
|
|
2358 @{@kbd{C-h h}@} to display the Hyperbole menu. If you see an
|
|
|
2359 @code{Otl/} entry in the menu, then the outliner is available.
|
|
|
2360 Otherwise, the outliner does not work with your version of Emacs, so
|
|
|
2361 this section of the manual will not be of interest to you. (The same is
|
|
|
2362 true of the Hyperbole/Outline pulldown menu; if it appears, the outliner
|
|
|
2363 is available for use.)
|
|
|
2364
|
|
|
2365 @vindex file, EXAMPLE.kotl
|
|
|
2366 @cindex menu, Outline/Example
|
|
|
2367 This chapter expands on the information given in @file{EXAMPLE.kotl}
|
|
|
2368 file included with Hyperbole. Use @{@kbd{C-h h o e}@} to display that
|
|
|
2369 file. It is an actual outline file that explains major outliner
|
|
|
2370 operations. You can test out the viewing and motion commands with this
|
|
|
2371 file. If you want to experiment with editing operations, use @{@kbd{C-x
|
|
|
2372 C-w}@} to write the outline to a temporary file such as,
|
|
|
2373 @file{/tmp/e.kotl}, and then use @{@kbd{C-x C-q}@} to make the outline
|
|
|
2374 editable.
|
|
|
2375
|
|
|
2376 @xref{Outliner Keys}, for a full summary of the key bindings and
|
|
|
2377 commands available in the outliner.
|
|
|
2378
|
|
|
2379 @menu
|
|
|
2380 * Menu Commands::
|
|
|
2381 * Creating Outlines::
|
|
|
2382 * Autonumbering::
|
|
|
2383 * Idstamps::
|
|
|
2384 * Editing::
|
|
|
2385 * Viewing::
|
|
|
2386 * Links::
|
|
|
2387 * Cell Attributes::
|
|
|
2388 * Outliner History::
|
|
|
2389 @end menu
|
|
|
2390
|
|
|
2391
|
|
|
2392 @node Menu Commands, Creating Outlines, Outliner, Outliner
|
|
|
2393 @section Menu Commands
|
|
|
2394
|
|
|
2395 The Otl/ menu entry on the Hyperbole top-level menu provides access to
|
|
|
2396 a number of major outliner commands:
|
|
|
2397
|
|
|
2398 @cindex outliner commands
|
|
|
2399 @cindex Koutliner commands
|
|
|
2400 @findex kotl-mode:show-all
|
|
|
2401 @findex kvspec:toggle-blank-lines
|
|
|
2402 @findex kfile:find
|
|
|
2403 @findex kotl-mode:hide-sublevels
|
|
|
2404 @findex kotl-mode:hide-tree
|
|
|
2405 @findex kotl-mode:kill-tree
|
|
|
2406 @findex klink:create
|
|
|
2407 @findex kotl-mode:overview
|
|
|
2408 @findex kotl-mode:show-tree
|
|
|
2409 @findex kotl-mode:top-cells
|
|
|
2410 @findex kvspec:activate
|
|
|
2411 @cindex menu, Outline
|
|
10
|
2412 @example
|
|
|
2413 @group
|
|
0
|
2414 Menu Item Command Description
|
|
|
2415 ====================================================================
|
|
|
2416 All kotl-mode:show-all Expand all cells
|
|
|
2417 Blanks kvspec:toggle-blank-lines Toggle blank lines on or off
|
|
|
2418 Create kfile:find Edit or create an outline
|
|
|
2419 Downto kotl-mode:hide-sublevels Hide cells deeper than a level
|
|
|
2420 Examp <sample outliner file> Show self-descriptive example
|
|
|
2421 Hide kotl-mode:hide-tree Hide tree with root at point
|
|
|
2422 Info <outliner documentation> Show outliner manual section
|
|
|
2423 Kill kotl-mode:kill-tree Kill the current tree
|
|
|
2424 Link klink:create Create a link to another cell
|
|
|
2425 Overvw kotl-mode:overview Show first line of each cell
|
|
|
2426 Show kotl-mode:show-tree Show tree with root at point
|
|
|
2427 Top kotl-mode:top-cells Collapse to top-level cells
|
|
|
2428 Vspec kvspec:activate Set a view specification
|
|
|
2429 ====================================================================
|
|
|
2430 @end group
|
|
|
2431 @end example
|
|
|
2432
|
|
|
2433
|
|
|
2434 @node Creating Outlines, Autonumbering, Menu Commands, Outliner
|
|
|
2435 @section Creating Outlines
|
|
|
2436
|
|
|
2437 @cindex outline file suffix
|
|
|
2438 @cindex outline, creating
|
|
|
2439 @vindex file, .kotl suffix
|
|
|
2440 In addition to the Otl/Create menu item, you can create and experiment
|
|
|
2441 with outline files simply by finding a file, @{@kbd{C-x C-f}@} with a
|
|
|
2442 @file{.kotl} suffix. @file{.kot} will also work for DOS or
|
|
|
2443 Windows-impaired users.
|
|
|
2444
|
|
|
2445 @cindex root cell
|
|
|
2446 @cindex top-level cell
|
|
|
2447 @cindex cell, top-level
|
|
|
2448 @cindex cell, idstamp 0
|
|
|
2449 When a new koutline is created, an invisible root cell is created. Its
|
|
|
2450 permanent and relative ids are both 0, and it is considered to be at
|
|
|
2451 level 0 in the outline. All visible cells in the outline are at level 1
|
|
|
2452 or deeper, and thus are descendants of this root cell. Some koutliner
|
|
|
2453 commands prompt for cell numbers as arguments. An argument of 0 makes
|
|
|
2454 commands operate upon the entire outline.
|
|
|
2455
|
|
|
2456 An initial level 1 cell is also created to make it easy to start
|
|
|
2457 entering text in the outline. A koutline always has at least one
|
|
|
2458 visible cell in it.
|
|
|
2459
|
|
|
2460 @xref{Autonumbering}, which explains how cells are labeled according to their
|
|
|
2461 respective levels in the outline and how these labels are updated as the
|
|
|
2462 structure of the outline changes.
|
|
|
2463
|
|
|
2464
|
|
|
2465 @node Autonumbering, Idstamps, Creating Outlines, Outliner
|
|
|
2466 @section Autonumbering
|
|
|
2467
|
|
|
2468 @cindex autonumber
|
|
|
2469 @cindex relative identifier
|
|
|
2470 @xref{Adding and Killing}, which explains how to add new cells to or remove
|
|
|
2471 cells from a koutline. As you do this, or as you promote or demote
|
|
|
2472 cells within the outline, the labels preceding the contents of each cell
|
|
|
2473 automatically update to reflect the new structure. These labels are
|
|
|
2474 also known as @dfn{autonumbers} and as @dfn{relative ids} because they
|
|
|
2475 change as the structure changes.
|
|
|
2476
|
|
|
2477 @cindex outline structure
|
|
|
2478 The outline structure is shown by these labels and by the indentation of
|
|
|
2479 each outline level. Normally, each deeper level is indented another
|
|
|
2480 three characters, to reflect the nesting.
|
|
|
2481
|
|
|
2482 @cindex label type, alpha
|
|
|
2483 @cindex label type, legal
|
|
|
2484 @cindex alpha labels
|
|
|
2485 @cindex legal labels
|
|
|
2486 @cindex outline, label type
|
|
|
2487 The default autonumbers are called @dfn{alphanumeric labels} because
|
|
|
2488 they alternate between using numbers and letters to distinguish each
|
|
|
2489 successive level. Each alphanumeric label uniquely identifies a cell's
|
|
|
2490 position in an outline, so that there is no need to scan back to prior
|
|
|
2491 cells to see what the current section number of an outline is. This is
|
|
|
2492 similar to a legal numbering scheme but without all the period
|
|
|
2493 characters between level numbers. As an example, 1b3 is equivalent to a
|
|
|
2494 legal label of 1.2.3. Both refer to the 3rd cell at level 3,
|
|
|
2495 below the 2nd child of the first cell at level 1. Said another way,
|
|
|
2496 this is the 3rd child of the 1st cell's 2nd child. In other words, it
|
|
|
2497 is easier to visualize hierarchies than to talk about them.
|
|
|
2498
|
|
|
2499 Alphanumeric labels are the default because they are shorter and easier
|
|
|
2500 to read aloud than equivalent legal ones. They also simplify
|
|
|
2501 distinguishing between even and odd level labels because of the
|
|
|
2502 alternating character set.
|
|
|
2503
|
|
|
2504 @kindex C-c C-l
|
|
|
2505 @cindex label type, changing
|
|
|
2506 You can change the labeling scheme used in a particular outline with the
|
|
|
2507 command @{@kbd{C-c C-l}@}. A @{@kbd{?}@} then will show all of your
|
|
|
2508 options. Legal labels, partial alpha labels (single level autonumbering
|
|
|
2509 where only the last part of the level number is shown, as commonly seen
|
|
|
2510 in other outliner products), idstamps (permanent cell ids), and star
|
|
|
2511 outline level labels (Emacs asterisk-based outline labeling) are all
|
|
|
2512 available. Or you may choose to turn autonumbering off. Cells are
|
|
|
2513 still indented to reflect the outline structure whether or not labels
|
|
|
2514 are displayed.
|
|
|
2515
|
|
|
2516 @cindex label separator, changing
|
|
|
2517 @cindex cell, label separator
|
|
|
2518 @cindex outline, label separator
|
|
|
2519 @kindex C-c M-l
|
|
|
2520 @kindex C-u C-c M-l
|
|
|
2521 A cell label is normally followed by two spaces, called the @dfn{label
|
|
|
2522 separator}, prior to the start of the cell contents. You can change the
|
|
|
2523 separator with for the current outline with @{@kbd{C-c M-l}@}.
|
|
|
2524 @{@kbd{C-u C-c M-l}@} will additionally change the default separator
|
|
|
2525 value used when new outlines are created (for the current session only).
|
|
|
2526 For example, use the value ". " to get a trailing period after each cell
|
|
|
2527 label. The separator must be at least two characters long but may be
|
|
|
2528 longer.
|
|
|
2529
|
|
|
2530 @vindex file, ~/.emacs
|
|
|
2531 @cindex initialization file
|
|
|
2532 If you find a separator that you prefer for all outlines, change the
|
|
|
2533 separator setting permanently by adding the following line to your Emacs
|
|
|
2534 initialization file, @file{~/.emacs}, substituting for `your-separator':
|
|
|
2535
|
|
|
2536 @cindex label separator, default
|
|
|
2537 @vindex kview:default-label-separator
|
|
|
2538 @lisp
|
|
|
2539 (setq kview:default-label-separator "your-separator")
|
|
|
2540 @end lisp
|
|
|
2541
|
|
|
2542
|
|
|
2543 @node Idstamps, Editing, Autonumbering, Outliner
|
|
|
2544 @section Idstamps
|
|
|
2545
|
|
|
2546 @cindex permanent identifier
|
|
|
2547 @cindex idstamp
|
|
|
2548 Idstamps (permanent ids) are associated with each cell and can be
|
|
|
2549 used in hyperlinks that are maintained as cells are reordered in a file.
|
|
|
2550 @xref{Links}. Idstamps may also be displayed in place of the outline
|
|
|
2551 level relative ids. Use @{@kbd{C-c C-l id RET}@}.
|
|
|
2552
|
|
|
2553 @cindex idstamp counter
|
|
|
2554 An idstamp counter for each outline starts at 0 and is incremented by
|
|
|
2555 one each time a cell is added to the outline. This idstamp stays with
|
|
|
2556 the cell no matter where it is moved within the outline. If the cell is
|
|
|
2557 deleted, its idstamp is not reused.
|
|
|
2558
|
|
|
2559 @cindex root cell
|
|
|
2560 @cindex top-level cell
|
|
|
2561 @cindex cell, top-level
|
|
|
2562 @cindex cell, idstamp 0
|
|
|
2563 @cindex idstamp 0
|
|
|
2564 The 0 idstamp is always assigned to the root node of the entire outline.
|
|
|
2565 This node is never visible within the outline, but is used so that the
|
|
|
2566 outline may be treated as a single tree when needed. Idstamps always
|
|
|
2567 begin with a 0, as in 012, to distinguish them from relative ids.
|
|
|
2568
|
|
|
2569
|
|
|
2570 @node Editing, Viewing, Idstamps, Outliner
|
|
|
2571 @section Editing
|
|
|
2572
|
|
|
2573 You edit text and move around in the Koutliner just as you would in any
|
|
|
2574 other Emacs buffer, except when you want to deal with the structural
|
|
|
2575 components of an outline. Within the contents of a cell, all of your
|
|
|
2576 standard editing keys should work properly. You can just type in text
|
|
|
2577 and the left and right margins of the lines will be maintained for you.
|
|
|
2578 @xref{Filling}, for the times when you need to refill a paragraph or to
|
|
|
2579 control when filling occurs.@refill
|
|
|
2580
|
|
|
2581 Don't invoke editing commands with @{@kbd{M-x command-name @key{RET}}@}
|
|
|
2582 since the Koutliner uses special differently named commands made to act
|
|
|
2583 like the regular editing commands but which account for the structure
|
|
|
2584 and indentation in koutlines.
|
|
|
2585
|
|
|
2586 @cindex cell, selection
|
|
|
2587 You can use the mouse to select parts of the contents of a single cell
|
|
|
2588 for editing. But don't drag across cell boundaries and then edit the
|
|
|
2589 selected region, since that can destroy the outline structure.
|
|
|
2590
|
|
|
2591 @menu
|
|
|
2592 * Adding and Killing::
|
|
|
2593 * Moving Around::
|
|
|
2594 * Relocating and Copying::
|
|
|
2595 * Filling::
|
|
|
2596 * Transposing::
|
|
|
2597 * Splitting and Appending::
|
|
|
2598 * Inserting and Importing::
|
|
|
2599 @end menu
|
|
|
2600
|
|
|
2601 @node Adding and Killing, Relocating and Copying, Editing, Editing
|
|
|
2602 @subsection Adding and Killing
|
|
|
2603
|
|
|
2604 @kindex C-j
|
|
|
2605 @kindex C-u c-j
|
|
|
2606 @kindex C-c a
|
|
|
2607 @kindex C-c p
|
|
|
2608 @cindex cell, adding
|
|
|
2609 @cindex cell, creating
|
|
|
2610 @{@kbd{C-j}@} adds a new cell as a successor sibling of the
|
|
|
2611 current cell, that is, the next cell at the same level as the current
|
|
|
2612 cell. If you enter a positive number as a prefix argument, that number
|
|
|
2613 of cells will be inserted, all at the same level. @{@kbd{C-u C-j}@} is
|
|
|
2614 handled specially. It adds a single cell as a child of the current cell.
|
|
|
2615 @{@kbd{C-c a}@} does the same thing. @{@kbd{C-c p}@} adds the cell as
|
|
|
2616 the successor of the current cell's parent.
|
|
|
2617
|
|
|
2618 @kindex C-c C-k
|
|
|
2619 @kindex C-c k
|
|
|
2620 @kindex C-u C-c k
|
|
|
2621 @kindex C-y
|
|
|
2622 @cindex cell, killing
|
|
|
2623 @cindex cell, yanking contents
|
|
|
2624 @cindex tree, killing
|
|
|
2625 @{@kbd{C-c C-k}@} kills the current cell and its entire subtree.
|
|
|
2626 @{@kbd{C-c k}@} kills the contents of a cell from point through the end
|
|
|
2627 of the cell; it does not remove the cell itself. @{@kbd{C-u C-c k}@}
|
|
|
2628 kills the entire contents of the cell regardless of the location of
|
|
|
2629 point. You may then yank the contents into another cell or another
|
|
|
2630 buffer with @{@kbd{C-y}@}.
|
|
|
2631
|
|
|
2632
|
|
|
2633 @node Relocating and Copying, Moving Around, Adding and Killing, Editing
|
|
|
2634 @subsection Relocating and Copying
|
|
|
2635
|
|
|
2636 @cindex promotion
|
|
|
2637 @cindex demotion
|
|
|
2638 @cindex tree, promoting
|
|
|
2639 @cindex tree, demoting
|
|
|
2640 @dfn{Demotion} is the act of moving a tree down one or more levels in the
|
|
|
2641 outline. The new tree will become either the successor or the first
|
|
|
2642 child of the cell which precedes it in the outline. @dfn{Promotion} is
|
|
|
2643 the inverse operation. Note that trees (cells and their entire
|
|
|
2644 substructure) are promoted and demoted, not individual cells.
|
|
|
2645
|
|
|
2646 @kindex @key{TAB}
|
|
|
2647 @kindex M-@key{TAB}
|
|
|
2648 Trees may be demoted or promoted by pressing @{@key{TAB}@} or
|
|
|
2649 @{@kbd{M-@key{TAB}}@} respectively, as in most outliners today.
|
|
|
2650 @{@kbd{M-0 @key{TAB}}@} and @{@kbd{M-0 M-@key{TAB}}@} demote and
|
|
|
2651 promote trees and additionally refill each cell that is not specially
|
|
|
2652 marked to prevent refilling. @xref{Filling}. A positive or negative
|
|
|
2653 prefix argument to these commands promotes or demotes the tree up to a
|
|
|
2654 maximum of the number of levels given by the argument. The outline may
|
|
|
2655 not support movement of the tree by the number of levels requested.
|
|
|
2656
|
|
|
2657 @cindex tree, copying
|
|
|
2658 @cindex tree, moving
|
|
|
2659 @cindex Action Key, cell argument
|
|
|
2660 @kindex Action Key, cell argument
|
|
|
2661 For maximum flexibility in rearranging outlines, there are commands that
|
|
|
2662 move or copy entire trees. Each of these commands prompts for the label
|
|
|
2663 of the root cell to move or copy and for second cell at the new location
|
|
|
2664 for the moved or copied tree. You can either accept the default
|
|
|
2665 provided, type in the cell label or when a mouse is available, simple
|
|
|
2666 double click with the Action Key on the contents of a cell. The
|
|
|
2667 Koutliner knows to use the cell's label in such cases.
|
|
|
2668
|
|
|
2669 In these following commands, words delimited with <> represent the
|
|
|
2670 arguments for which each command prompts. Note how the use of prefix
|
|
|
2671 arguments changes each command's behavior from insertion at the sibling
|
|
|
2672 level to insertion at the child level.
|
|
|
2673
|
|
|
2674 @table @kbd
|
|
|
2675 @kindex C-c c
|
|
|
2676 @item C-c c
|
|
|
2677 Copy <tree> to be the successor of <cell>.
|
|
|
2678 @kindex C-u C-c c
|
|
|
2679 @itemx C-u C-c c
|
|
|
2680 Copy <tree> to follow as the first child of <cell>.
|
|
|
2681
|
|
|
2682 @kindex C-c C-c
|
|
|
2683 @item C-c C-c
|
|
|
2684 Copy <tree> to be the predecessor of <cell>.
|
|
|
2685 @kindex C-u C-c C-c
|
|
|
2686 @itemx C-u C-c C-c
|
|
|
2687 Copy <tree> to be the first child of the parent of <cell>.
|
|
|
2688
|
|
|
2689 @kindex C-c m
|
|
|
2690 @item C-c m
|
|
|
2691 Move <tree> to be the successor of <cell>.
|
|
|
2692 @kindex C-u C-c m
|
|
|
2693 @itemx C-u C-c m
|
|
|
2694 Move <tree> to follow as the first child of <cell>.
|
|
|
2695
|
|
|
2696 @kindex C-c C-m
|
|
|
2697 @item C-c C-m
|
|
|
2698 Move <tree> to precede <cell>.
|
|
|
2699 @kindex C-u C-c C-m
|
|
|
2700 @itemx C-u C-c C-m
|
|
|
2701 Move <tree> to be the first child of the parent of <cell>.
|
|
|
2702 @end table
|
|
|
2703
|
|
|
2704 @cindex mouse, moving trees
|
|
|
2705 If you have mouse support under Hyperbole, you can move entire trees
|
|
|
2706 with mouse clicks. Simply click the Assist Key within the indentation
|
|
|
2707 to the left of a cell and you will be prompted for a tree to move.
|
|
|
2708 Double click the Action Key within the contents the root cell of the tree
|
|
|
2709 to move and then double click within the contents of the root cell of the
|
|
|
2710 tree you want it to follow as a sucessor.
|
|
|
2711
|
|
|
2712 Copying and moving only work within a single outline right now, so don't
|
|
|
2713 try to use them to move trees across different outline files. You can,
|
|
|
2714 however, copy an outline tree to a non-outline buffer with:
|
|
|
2715
|
|
|
2716 @cindex tree, exporting
|
|
|
2717 @cindex outline, exporting
|
|
|
2718 @cindex tree, mailing
|
|
|
2719 @cindex outline, mailing
|
|
|
2720 @cindex exporting an outline
|
|
|
2721 @cindex mailing an outline
|
|
|
2722 @table @kbd
|
|
|
2723 @kindex C-c M-c
|
|
|
2724 @item C-c M-c
|
|
|
2725 Copy <tree> to a non-koutline buffer.
|
|
|
2726 @kindex C-c @@
|
|
|
2727 @itemx C-c @@
|
|
|
2728 Copy a <tree> to an outgoing mail message.
|
|
|
2729 @end table
|
|
|
2730
|
|
|
2731 @node Moving Around, Filling, Relocating and Copying, Editing
|
|
|
2732 @subsection Moving Around
|
|
|
2733
|
|
|
2734 @cindex outline, motion
|
|
|
2735 In addition to normal Emacs movement commands, you can move within a
|
|
|
2736 cell or from one cell or tree to another.
|
|
|
2737
|
|
|
2738 @table @kbd
|
|
|
2739 @kindex C-c ,
|
|
|
2740 @item C-c ,
|
|
|
2741 Move to the beginning of the current cell.
|
|
|
2742 @kindex C-c .
|
|
|
2743 @itemx C-c .
|
|
|
2744 Move to the end of the current cell.
|
|
|
2745
|
|
|
2746 @kindex C-c C-n
|
|
|
2747 @item C-c C-n
|
|
|
2748 Move to the next visible cell, regardless of level.
|
|
|
2749 @kindex C-c C-p
|
|
|
2750 @itemx C-c C-p
|
|
|
2751 Move to the previous visible cell, regardless of level.
|
|
|
2752
|
|
|
2753 @kindex C-c C-f
|
|
|
2754 @item C-c C-f
|
|
|
2755 Move forward to this cell's successor, if any.
|
|
|
2756 @kindex C-c C-b
|
|
|
2757 @itemx C-c C-b
|
|
|
2758 Move backward to this cell's predecessor, if any.
|
|
|
2759
|
|
|
2760 @kindex C-c C-d
|
|
|
2761 @item C-c C-d
|
|
|
2762 Move to the first child of the current cell, if any.
|
|
|
2763 @kindex C-c C-u
|
|
|
2764 @itemx C-c C-u
|
|
|
2765 Move to the parent cell of the current cell, if any.
|
|
|
2766
|
|
|
2767 @kindex C-c <
|
|
|
2768 @item C-c <
|
|
|
2769 Move to the first sibling at the current level within this tree.
|
|
|
2770 @kindex C-c >
|
|
|
2771 @itemx C-c >
|
|
|
2772 Move to the last sibling at the current level within this tree.
|
|
|
2773
|
|
|
2774 @kindex C-c ^
|
|
|
2775 @item C-c ^
|
|
|
2776 Move to the level 1 root cell of the current tree.
|
|
|
2777 @kindex C-c $
|
|
|
2778 @itemx C-c $
|
|
|
2779 Move to the last cell in the tree rooted at point, regardless of level.
|
|
|
2780 @end table
|
|
|
2781
|
|
|
2782
|
|
|
2783 @node Filling, Transposing, Moving Around, Editing
|
|
|
2784 @subsection Filling
|
|
|
2785
|
|
|
2786 @cindex outline, filling
|
|
|
2787 Filling is the process of extending lines that are shorter than the
|
|
|
2788 right margin and reducing lines which extend past the margin by moving
|
|
|
2789 words among the lines. Commands are provided to fill a paragraph within
|
|
|
2790 a cell or a whole cell, which may have multiple paragraphs.
|
|
|
2791
|
|
|
2792 @cindex filling
|
|
|
2793 @cindex cell, filling
|
|
|
2794 @cindex paragraph, filling
|
|
|
2795 @cindex tree, filling
|
|
|
2796 @cindex margin
|
|
|
2797 @kindex M-q
|
|
|
2798 @kindex M-j
|
|
|
2799 @kindex C-c M-q
|
|
|
2800 @kindex C-c M-j
|
|
|
2801 @kindex C-M-q
|
|
|
2802 @kindex C-M-j
|
|
|
2803 @{@kbd{M-q}@} or @{@kbd{M-j}@} refills a paragraph within a
|
|
|
2804 cell so that its lines wrap within the current margin settings.
|
|
|
2805 @{@kbd{C-c M-q}@} or @{@kbd{C-c M-j}@} refills all paragraphs within a
|
|
|
2806 cell. @{@kbd{C-M-q}@} or @{@kbd{C-M-j}@} refills all cells within a
|
|
|
2807 tree. See your Emacs or InfoDock manual for information on how to set
|
|
|
2808 the left and right margins.
|
|
|
2809
|
|
|
2810 @vindex kotl-mode:refill-flag
|
|
|
2811 @cindex refilling
|
|
|
2812 @cindex attribute, no-fill
|
|
|
2813 @cindex cell, no-fill attribute
|
|
|
2814 Set the variable, @var{kotl-mode:refill-flag}, to t if you want
|
|
|
2815 moving, promoting, demoting, exchanging, splitting and appending cells
|
|
|
2816 to also automatically refill each cell. Generally, this is not
|
|
|
2817 recommended since if you happen to move a cell that you have carefully
|
|
|
2818 formatted and forgot to give it a `no-fill' property, your formatting
|
|
|
2819 will be lost.
|
|
|
2820
|
|
|
2821
|
|
|
2822 @node Transposing, Splitting and Appending, Filling, Editing
|
|
|
2823 @subsection Transposing
|
|
|
2824
|
|
|
2825 The Koutliner move and copy commands rearrange entire trees. The
|
|
|
2826 following two commands, in contrast, exchange the locations of two
|
|
|
2827 individual cells.
|
|
|
2828
|
|
|
2829 @kindex C-c e
|
|
|
2830 @cindex cell, transposing
|
|
|
2831 @cindex cell, exchanging
|
|
|
2832 @cindex exchanging cells
|
|
|
2833 @cindex transposing cells
|
|
|
2834 @{@kbd{C-c e}@} prompts for two cell addresses and exchanges the cell
|
|
|
2835 locations.
|
|
|
2836
|
|
|
2837 @kindex C-c t
|
|
|
2838 @{@kbd{C-c t}@} does not prompt. It exchanges the current
|
|
|
2839 and immediatly prior cell, regardless of their levels. If there is no
|
|
|
2840 prior cell it exchanges the current and next cell.
|
|
|
2841
|
|
|
2842 @cindex cell, mark and point
|
|
|
2843 @kindex M-0 C-c t
|
|
|
2844 @{@kbd{M-0 C-c t}@} exchanges the cells in which point and mark fall.
|
|
|
2845 @{@kbd{C-c t}@} with a non-zero numeric prefix argument, N, moves
|
|
|
2846 the current tree past maximally the next N visible cells. If there are
|
|
|
2847 fewer visible, it makes the current cell the last cell in the outline.
|
|
|
2848
|
|
|
2849
|
|
|
2850 @node Splitting and Appending, Inserting and Importing, Transposing, Editing
|
|
|
2851 @subsection Splitting and Appending
|
|
|
2852
|
|
|
2853 @cindex splitting a cell
|
|
|
2854 @cindex cell, splitting
|
|
|
2855 @kindex C-c s
|
|
|
2856 @kindex C-u C-c s
|
|
|
2857 You can split one cell into two adjacent sibling cells with @{@kbd{C-c
|
|
|
2858 s}@}. This leaves the cell contents preceding point in the current
|
|
|
2859 cell, minus any trailing whitespace, and moves the contents following
|
|
|
2860 point to a new sibling cell which is inserted into the outline.
|
|
|
2861 @{@kbd{C-u C-c s}@} instead adds the new cell as the first child of the
|
|
|
2862 original cell, rather than as its successor.
|
|
|
2863
|
|
|
2864 All cell attributes in the original cell are propagated to the new one,
|
|
|
2865 aside from the creation attributes and idstamp.
|
|
|
2866
|
|
|
2867 @kindex C-c +
|
|
|
2868 @cindex cell, appending
|
|
|
2869 @cindex appending to a cell
|
|
|
2870 @cindex attribute, no-fill
|
|
|
2871 @cindex cell, no-fill attribute
|
|
|
2872 @{@kbd{C-c +}@} appends the contents of a specified cell to the end of
|
|
|
2873 another cell. It has no effect on cell attributes, except that if one
|
|
|
2874 cell has a `no-fill' attribute that prevents all but user requested
|
|
|
2875 filling of a cell, then the cell appended to inherits this property.
|
|
|
2876 This helps maintain any special formatting the appended text may have.
|
|
|
2877
|
|
|
2878
|
|
|
2879 @node Inserting and Importing, , Splitting and Appending, Editing
|
|
|
2880 @subsection Inserting and Importing
|
|
|
2881
|
|
|
2882 @cindex outline, inserting into
|
|
|
2883 @cindex outline, importing into
|
|
|
2884 @cindex importation
|
|
|
2885 @cindex insertion
|
|
|
2886 @kindex C-x i
|
|
|
2887 @cindex outline, foreign file
|
|
|
2888 The elements of another buffer or file may be inserted into a koutline
|
|
|
2889 as a set of cells by using the @{@kbd{C-x i}@} command. When prompted,
|
|
|
2890 you may use a buffer name or file name from which to insert, though
|
|
|
2891 completion is provided only for file names.
|
|
|
2892
|
|
|
2893 @kindex C-u C-x i
|
|
|
2894 The elements from the original buffer are converted into kcells and
|
|
|
2895 inserted as the successors of the current cell. If @{@kbd{C-u C-x i}@}
|
|
|
2896 is used, they are instead inserted as the inital children of the current
|
|
|
2897 cell.
|
|
|
2898
|
|
|
2899 @vindex kimport:mode-alist
|
|
|
2900 @vindex kimport:suffix-alist
|
|
|
2901 @cindex outline, conversion
|
|
|
2902 @findex kotl-mode
|
|
|
2903 @cindex outline mode
|
|
|
2904 @cindex koutline mode
|
|
|
2905 @cindex file, importing
|
|
|
2906 @cindex importing a file
|
|
|
2907 See the documentation for the variables, kimport:mode-alist and
|
|
|
2908 kimport:suffix-alist, for information on mode and suffix-specific
|
|
|
2909 conversions performed on file elements before they are inserted. This
|
|
|
2910 same conversion process applies if you invoke @{@kbd{M-x kotl-mode
|
|
|
2911 RET}@} in a non-koutline buffer or if you perform a generic file import
|
|
|
2912 as described later in this section.
|
|
|
2913
|
|
|
2914 @findex kotl-mode:insert-file-contents
|
|
|
2915 Use @{@kbd{M-x kotl-mode:insert-file-contents RET}@} to insert the
|
|
|
2916 entire contents of a file into the current cell at the location of
|
|
|
2917 point.
|
|
|
2918
|
|
|
2919 @findex kimport:file
|
|
|
2920 The outliner presently supports conversion of three types of files into
|
|
|
2921 koutline files. You can choose to import a file into an existing
|
|
|
2922 koutline, following the tree at point, or to create a new koutline of
|
|
|
2923 the imported file contents. @{@kbd{M-x kimport:file RET}@} will select
|
|
|
2924 the importation type based on the buffer or file name suffix of the file
|
|
|
2925 to import.
|
|
|
2926
|
|
|
2927 @findex kotl-mode
|
|
|
2928 If you want to convert a buffer from some other mode into a koutline and
|
|
|
2929 then want to save the converted buffer back to its original file,
|
|
|
2930 thereby replacing the original format, then use @{@kbd{M-x kotl-mode
|
|
|
2931 RET}@} to convert the buffer into a koutline. Remember that you will
|
|
|
2932 lose the old format of the buffer when you do this.
|
|
|
2933
|
|
|
2934 Use one of the following commands if you really need explicit control over the
|
|
|
2935 type of importation used on some text. With these commands, your
|
|
|
2936 original file remains intact.
|
|
|
2937
|
|
|
2938 @findex kimport:text
|
|
|
2939 @cindex text file
|
|
|
2940 Use @{@kbd{M-x kimport:text RET}@} and you will be prompted for a text
|
|
|
2941 buffer or file to import and the new koutline buffer or file to create
|
|
|
2942 from its text. It will also import the contents, attributes and level
|
|
|
2943 structure of cells from a koutline.
|
|
|
2944
|
|
|
2945 @findex kimport:star-outline
|
|
|
2946 @cindex emacs outline
|
|
|
2947 @cindex star outline
|
|
|
2948 Star outlines are standard Emacs outlines where each entry begins with
|
|
|
2949 one or more asterisk characters. Use @{@kbd{M-x kimport:star-outline
|
|
|
2950 RET}@} and you will be prompted for the star outline buffer or file to
|
|
|
2951 import and the new koutline buffer or file to create.
|
|
|
2952
|
|
|
2953 @cindex Augment outline
|
|
|
2954 @findex kimport:aug-post-outline
|
|
|
2955 (Skip this if you are unfamiliar with the Augment system.) Files
|
|
|
2956 exported from the Augment system as text often have alphanumeric
|
|
|
2957 statement identifiers on the right side. You can import such files
|
|
|
2958 while maintaining there outline structure. Use @{@kbd{M-x
|
|
|
2959 kimport:aug-post-outline RET}@} and you will be prompted for the Augment
|
|
|
2960 buffer or file to import and the koutline to create.
|
|
|
2961
|
|
|
2962
|
|
|
2963 @node Viewing, Links, Editing, Outliner
|
|
|
2964 @section Viewing
|
|
|
2965
|
|
|
2966 @cindex outline, viewing
|
|
|
2967 @cindex view
|
|
|
2968 The Koutliner has very flexible viewing facilities to allow you to
|
|
|
2969 effectively browse and study large amounts of material.
|
|
|
2970
|
|
|
2971 @menu
|
|
|
2972 * Hiding and Showing::
|
|
|
2973 * View Specs::
|
|
|
2974 @end menu
|
|
|
2975
|
|
|
2976 @node Hiding and Showing, View Specs, Viewing, Viewing
|
|
|
2977 @subsection Hiding and Showing
|
|
|
2978
|
|
|
2979 @cindex outline, hiding
|
|
|
2980 @cindex outline, showing
|
|
|
2981 @cindex collapsing
|
|
|
2982 @cindex expanding
|
|
|
2983 @cindex hiding
|
|
|
2984 @cindex showing
|
|
|
2985 Individual cells, branches, or particular levels in the outline may be
|
|
|
2986 hidden or shown. These commands work even when an outline buffer is
|
|
|
2987 read-only, e.g. when its file is not checked out of a version control
|
|
|
2988 system yet, so that you can get effective views of an outline without
|
|
|
2989 editing it. Some of these commands affect the current view spec,
|
|
|
2990 @ref{View Specs}.
|
|
|
2991
|
|
|
2992 @table @kbd
|
|
|
2993 @cindex hide tree
|
|
|
2994 @cindex tree, show
|
|
|
2995 @kindex C-c C-h
|
|
|
2996 @item C-c C-h
|
|
|
2997 Hide (collapse) the tree rooted at point.
|
|
|
2998 @cindex show tree
|
|
|
2999 @cindex tree, show
|
|
|
3000 @kindex C-c C-s
|
|
|
3001 @itemx C-c C-s
|
|
|
3002 Show (expand) the tree rooted at point.
|
|
|
3003
|
|
|
3004 @cindex outline, all cells
|
|
|
3005 @cindex cell, show all
|
|
|
3006 @kindex C-c C-a
|
|
|
3007 @item C-c C-a
|
|
|
3008 Show (expand) all of the cells in the outline.
|
|
|
3009 @cindex level
|
|
|
3010 @cindex cell, show levels
|
|
|
3011 @cindex outline, show levels
|
|
|
3012 @kindex C-x $
|
|
|
3013 @itemx C-x $
|
|
|
3014 Show all of the cells down to a particular <level>. You are prompted
|
|
|
3015 for the level or a prefix argument may be given.
|
|
|
3016
|
|
|
3017 @cindex subtree, hide
|
|
|
3018 @cindex tree, hide subtree
|
|
|
3019 @cindex cell, hide subtree
|
|
|
3020 @cindex hide subtree
|
|
|
3021 @kindex C-M-h
|
|
|
3022 @item C-M-h
|
|
|
3023 Hide the subtree at point, excluding the root cell.
|
|
|
3024 @cindex subtree, show
|
|
|
3025 @cindex tree, show subtree
|
|
|
3026 @cindex cell, show subtree
|
|
|
3027 @cindex show subtree
|
|
|
3028 @itemx M-x kotl-mode:show-subtree
|
|
|
3029 Show the subtree at point. Use @{@kbd{C-c C-s}@} to achieve a similar
|
|
|
3030 effect. The only difference is that it will expand the root cell too.
|
|
|
3031
|
|
|
3032 @cindex overview
|
|
|
3033 @cindex outline, overview
|
|
|
3034 @kindex C-c C-o
|
|
|
3035 @item C-c C-o
|
|
|
3036 Show an overview of the outline by showing only the first line of
|
|
|
3037 every cell. This also turns off blank lines between cells to maximize
|
|
|
3038 your view of the outline.
|
|
|
3039 @cindex top-level view
|
|
|
3040 @cindex outline, top-level
|
|
|
3041 @kindex C-c C-t
|
|
|
3042 @itemx C-c C-t
|
|
|
3043 Show a top-level view of the outline by showing only the first line of
|
|
|
3044 each level one cell. This does not turn off blank lines.
|
|
|
3045 @end table
|
|
|
3046
|
|
|
3047 @kindex Action Key, hide or show cell
|
|
|
3048 @cindex Action Key, hide or show cell
|
|
|
3049 @cindex cell, collapse
|
|
|
3050 @cindex cell, expand
|
|
|
3051 @kindex M-@key{RET}
|
|
|
3052 A click or a press of the Action Key within a cell's body, but not on a
|
|
|
3053 Hyperbole button, toggles between hiding and showing the tree rooted at
|
|
|
3054 point. Try it with either your mouse or with @{@kbd{M-@key{RET}}@}.
|
|
|
3055
|
|
|
3056
|
|
|
3057 @node View Specs, , Hiding and Showing, Viewing
|
|
|
3058 @subsection View Specs
|
|
|
3059
|
|
|
3060 @cindex view spec
|
|
|
3061 @cindex modeline, view spec
|
|
|
3062 @vindex kvspec:string
|
|
|
3063 @cindex pipe character
|
|
|
3064 @cindex |
|
|
|
3065 @cindex <|viewspec>
|
|
|
3066 @dfn{View specifications} (view specs, for short) are short codes used
|
|
|
3067 to control the view of a koutline. The view specs in effect for an
|
|
|
3068 outline are always displayed in the modeline of the outline's window,
|
|
|
3069 following the outline buffer name, unless the variable,
|
|
|
3070 @var{kvspec:string}, has been set to @code{nil} to disable view spec
|
|
|
3071 modeline display. The modeline display appears as <|viewspec> so that
|
|
|
3072 you can easily pick them out. The | (pipe character) is also used in
|
|
|
3073 links that specify view specs to indicate the start of a view spec
|
|
|
3074 sequence. @xref{Links}.
|
|
|
3075
|
|
|
3076 @cindex outline, view specs
|
|
|
3077 The current view spec is saved whenever the outline is saved. The next
|
|
|
3078 time the outline is read in, this will be the initial view.
|
|
|
3079
|
|
24
|
3080 The rest of this section documents the the view spec characters that are
|
|
0
|
3081 presently supported and explains how to invoke a view spec. There is no
|
|
|
3082 user-level way to add your own view spec characters, so all character
|
|
|
3083 codes are reserved for future use.
|
|
|
3084
|
|
|
3085 @kindex C-c C-v
|
|
|
3086 @cindex view spec, setting
|
|
|
3087 @cindex view spec, changing
|
|
|
3088 @cindex changing the view spec
|
|
|
3089 @cindex setting the view spec
|
|
|
3090 @{@kbd{C-c C-v}@} prompts for a new view spec setting in which the following
|
|
|
3091 codes are valid. Any invalid characters in a view spec are ignored.
|
|
|
3092 Characters are evaluated in an order meant to do the right thing, even
|
|
|
3093 when you use conflicting view spec characters. The standard initial
|
|
|
3094 view spec is <|ben>.
|
|
|
3095
|
|
|
3096 @cindex view spec, characters
|
|
|
3097 @table @kbd
|
|
|
3098 @cindex view spec, all lines and levels
|
|
|
3099 @item a
|
|
|
3100 Show all cell levels and all lines in cells.
|
|
|
3101
|
|
|
3102 @kindex C-c b
|
|
|
3103 @cindex blank lines, toggle
|
|
|
3104 @cindex view spec, blank lines
|
|
|
3105 @kindex C-c b
|
|
|
3106 @cindex toggling blank lines
|
|
|
3107 @item b
|
|
|
3108 Turn on blank lines between cells. Without this character, blank lines
|
|
|
3109 will be turned off. You can also use the @{@kbd{C-c b}@} key binding to
|
|
|
3110 toggle line numbers on and off independent of any other view settings.
|
|
|
3111
|
|
|
3112 @cindex view spec, lines per cell
|
|
|
3113 @cindex hide lines
|
|
|
3114 @cindex collapse lines
|
|
|
3115 @cindex cutoff lines
|
|
|
3116 @item cN
|
|
|
3117 Hide any lines greater than N in each cell. 0 means don't cutoff any
|
|
|
3118 lines.
|
|
|
3119
|
|
|
3120 @cindex ellipses
|
|
|
3121 @cindex view spec, ellipses
|
|
|
3122 @item e
|
|
|
3123 Show ellipses when some content of a cell or its subtree is hidden.
|
|
|
3124
|
|
|
3125 @cindex level
|
|
|
3126 @cindex cell, hiding levels
|
|
|
3127 @cindex hide levels
|
|
|
3128 @cindex view spec, show levels
|
|
|
3129 @item lN
|
|
|
3130 Hide cells at levels deeper than N. 0 means don't hide any cells.
|
|
|
3131
|
|
|
3132 @cindex label type
|
|
|
3133 @cindex view spec, label type
|
|
|
3134 @vindex kview:default-label-type
|
|
|
3135 @cindex default label type
|
|
|
3136 @item n
|
|
|
3137 Turn on the default label type, as given by the variable,
|
|
|
3138 @var{kview:default-label-type}. Normally, this is alphanumeric labels.
|
|
|
3139 @cindex label type, idstamps
|
|
|
3140 @itemx n0
|
|
|
3141 Display idstamps.
|
|
|
3142 @cindex label type, alpha
|
|
|
3143 @itemx n1
|
|
|
3144 Display alpha labels.
|
|
|
3145 @cindex label type, partial alpha
|
|
|
3146 @itemx n2
|
|
|
3147 Display partial alpha labels (don't use this, as full alpha labels are
|
|
|
3148 better).
|
|
|
3149 @cindex label type, legal
|
|
|
3150 @itemx n.
|
|
|
3151 Display legal labels.
|
|
|
3152 @cindex label type, star
|
|
|
3153 @cindex label type, asterisk
|
|
|
3154 @itemx n*
|
|
|
3155 Display star labels. A level three cell would have three asterisks as a
|
|
|
3156 label, for example.
|
|
|
3157 @cindex label type, no labels
|
|
|
3158 @itemx n~
|
|
|
3159 Turn off labels. (n viewspec is removed from modeline).
|
|
|
3160 @end table
|
|
|
3161
|
|
|
3162 @cindex view spec, example
|
|
|
3163 As a test, use @{@kbd{C-h h o e}@} to display the example koutline.
|
|
|
3164 Then use @{@kbd{C-c C-v}@} to set a view spec of `c2l1'. This will turn
|
|
|
3165 off blank lines, clip each cell after its second line, and hide all
|
|
|
3166 cells below level one.
|
|
|
3167
|
|
|
3168
|
|
|
3169 @node Links, Cell Attributes, Viewing, Outliner
|
|
|
3170 @section Links
|
|
|
3171
|
|
|
3172 @cindex link
|
|
|
3173 @cindex hyperlink
|
|
|
3174 @cindex klink
|
|
|
3175 @cindex <> delimiters
|
|
|
3176 Hyperlinks may be embedded in cells and may refer to other cells or
|
|
|
3177 external sources of information. Explicit Hyperbole buttons may be
|
|
|
3178 created as usual via mouse drags, @ref{By Dragging, Creation Via Action
|
|
|
3179 Key Drags}. A @dfn{klink} is a special implicit link button, delimited
|
|
|
3180 by <> separators, that jumps to a specific outline cell. This section
|
|
|
3181 discusses klinks.
|
|
|
3182
|
|
|
3183 @kindex Action Key, klink
|
|
|
3184 @cindex Action Key, klink
|
|
|
3185 @cindex klink, activating
|
|
|
3186 @cindex klink referent
|
|
|
3187 Press the Action Key over a klink to follow it. This will flash the
|
|
|
3188 klink as a button and then will display its referent in the other
|
|
|
3189 window. If the klink contains a view spec, that will be used when the
|
|
|
3190 referent is displayed.
|
|
|
3191
|
|
|
3192 @cindex klink, inserting
|
|
|
3193 @kindex C-c l
|
|
|
3194 There are a number of easy ways to insert klinks into koutlines. If you
|
|
|
3195 have mouse support under Hyperbole, simply click the Action Key within
|
|
|
3196 the indentation to the left of a cell text. If you then double click on
|
|
|
3197 some cell, a link to that cell will be inserted where you started. From
|
|
|
3198 a keyboard, use @{@kbd{C-c l}@} when in a koutline or @{@kbd{C-h h o
|
|
|
3199 l}@} when not in a koutline to insert a klink. Since klinks are
|
|
|
3200 implicit buttons, you can type in the text of the klink just as you see
|
|
|
3201 it in the examples below and it will work exactly as if it had been
|
|
|
3202 entered with the insert link command.
|
|
|
3203
|
|
|
3204 @cindex klink, formats
|
|
|
3205 @noindent
|
|
|
3206 There are basically three forms of klinks:
|
|
|
3207
|
|
|
3208 @table @bullet
|
|
|
3209 @cindex internal klink
|
|
|
3210 @cindex klink, internal
|
|
|
3211 @cindex <@@ klink>
|
|
|
3212 @item internal
|
|
|
3213 <@@ 2b=06> is an internal klink, since it refers to the koutline in which
|
|
|
3214 it is embedded. When activated, it jumps to the cell within the current
|
|
|
3215 outline which has permanent id `06' and relative id `2b'. <@@ 06> does
|
|
|
3216 the same thing, as does <@@ 2b>, though this latter form will not
|
|
|
3217 maintain the link properly if the cell is moved elsewhere within the
|
|
|
3218 outline. The form, <@@ 2b=06 |ben> additionally sets the view spec of
|
|
|
3219 the current outline back to the default value, with a blank line between
|
|
|
3220 each cell and all levels and lines of cells displayed.
|
|
|
3221
|
|
|
3222 @cindex external klink
|
|
|
3223 @cindex klink, external
|
|
|
3224 @item external
|
|
|
3225 The second klink format is an external link to another koutline, such
|
|
|
3226 as, <EXAMPLE.kotl, 3=012 |c1e>, which displays the named file, starting
|
|
|
3227 at the cell 3 (whose permanent identifer is 012), with the view
|
|
|
3228 specification of: blank lines turned off, cutoff after one line per
|
|
|
3229 cell, and show ellipses for cells or trees which are clipped.
|
|
|
3230
|
|
|
3231 @cindex klink, view spec
|
|
|
3232 @cindex view spec klink
|
|
|
3233 @item view spec
|
|
|
3234 The third format simply allows you to set a view spec for the current
|
|
|
3235 koutline. For example, <|ben>, when activated, sets the view in the
|
|
|
3236 current outline to display blank lines, ellipses following collapsed
|
|
|
3237 lines and standard alphanumeric numbering.
|
|
|
3238 @end table
|
|
|
3239
|
|
|
3240
|
|
|
3241 @node Cell Attributes, Outliner History, Links, Outliner
|
|
|
3242 @section Cell Attributes
|
|
|
3243
|
|
|
3244 @cindex cell, attribute
|
|
|
3245 @cindex attribute
|
|
|
3246 @dfn{Attributes} are named variables whose values are specific to a
|
|
|
3247 particular outline cell. Thus, each cell has its own attribute list.
|
|
|
3248 Every cell has three standard attributes:
|
|
|
3249
|
|
|
3250 @table @bullet
|
|
|
3251 @cindex idstamp attribute
|
|
|
3252 @item idstamp
|
|
|
3253 The permanent id of the cell, typically used in cross-file hyperlinks
|
|
|
3254 that reference the cell.
|
|
|
3255
|
|
|
3256 @cindex creator attribute
|
|
|
3257 @cindex e-mail address
|
|
|
3258 @cindex mail address
|
|
|
3259 @item creator
|
|
|
3260 The e-mail address of the person who created this cell.
|
|
|
3261
|
|
|
3262 @cindex create-time attribute
|
|
|
3263 @cindex cell, creation time
|
|
|
3264 @item create-time
|
|
|
3265 The time at which the cell was created. This is stored in a form that
|
|
|
3266 allows for easy data comparisons but is displayed in a human readable
|
|
|
3267 format, such as "Jan 28 18:27:59 CST 1994".
|
|
|
3268 @end table
|
|
|
3269
|
|
|
3270 @kindex C-c C-i
|
|
|
3271 @cindex attribute, adding
|
|
|
3272 @cindex attribute, modifying
|
|
|
3273 @cindex attribute, removing
|
|
|
3274 @{@kbd{C-c C-i}@} is the command to add an attribute to or to modify an
|
|
|
3275 existing attribute in the cell at point. Think of it as inserting an
|
|
|
3276 attribute value. To remove an attribute from cell, set its value to
|
|
|
3277 @code{nil}.
|
|
|
3278
|
|
|
3279
|
|
|
3280 @cindex attribute, no-fill
|
|
|
3281 @cindex cell, no-fill attribute
|
|
|
3282 @cindex no-fill attribute
|
|
|
3283 @vindex kotl-mode:refill-flag
|
|
|
3284 The `no-fill' attribute is special. When added with a non-nil value, it
|
|
|
3285 prevents moving, promoting, demoting, exchanging, splitting and
|
|
|
3286 appending cells from refilling the cell, even if the variable,
|
|
|
3287 @var{kotl-mode:refill-flag}, is set to t. It does not prevent you from
|
|
|
3288 invoking explicit commands that refill the cell. @xref{Filling}.
|
|
|
3289
|
|
|
3290 @kindex Assist Key, listing attributes
|
|
|
3291 @cindex Assist Key, listing attributes
|
|
|
3292 @cindex listing attributes
|
|
|
3293 @cindex outline, attribute list
|
|
|
3294 The attribute lists for the cells in the tree rooted at point can be
|
|
|
3295 displayed by pressing the Assist Key within the contents of a cell.
|
|
|
3296
|
|
|
3297 @kindex C-c h
|
|
|
3298 @kindex C-u C-c h
|
|
|
3299 @{@kbd{C-c h}@} prompts for a cell label and displays the cell's
|
|
|
3300 attributes. @{@kbd{C-u C-c h}@} prompts for a cell label and displays
|
|
|
3301 the attributes for it and its subtree; use 0 as the kcell id to see
|
|
|
3302 attributes for all visible cells in the outline.
|
|
|
3303
|
|
|
3304
|
|
|
3305 @node Outliner History, , Cell Attributes, Outliner
|
|
|
3306 @section Outliner History
|
|
|
3307
|
|
|
3308 @cindex NLS
|
|
|
3309 @cindex Augment
|
|
|
3310 @cindex Engelbart
|
|
|
3311 Much of the Hyperbole outliner design is based upon concepts pioneered
|
|
|
3312 in the NLS/Augment system, @cite{[Eng84a]}. Augment treated documents as
|
|
|
3313 a hierarchical set of nodes, called statements, rather than cells.
|
|
|
3314 Every Augment document utilized this intrinsic structure.
|
|
|
3315
|
|
|
3316 @cindex distributed collaboration
|
|
|
3317 @cindex collaboration
|
|
|
3318 The system could rapidly change the view of a document by collapsing,
|
|
|
3319 expanding, generating, clipping, filtering, including or reordering
|
|
|
3320 these nodes. It could also map individual views to multiple workstation
|
|
|
3321 displays across a network to aid in distributed, collaborative work.
|
|
|
3322
|
|
|
3323 @cindex knowledge transfer
|
|
|
3324 @cindex idea structuring
|
|
|
3325 @cindex cross referencing
|
|
|
3326 These facilities aided greatly in idea structuring, cross-referencing,
|
|
|
3327 and knowledge transfer. The Koutliner is a start at bringing
|
|
|
3328 these capabilities back into the mainstream of modern computing culture.
|
|
|
3329
|
|
|
3330
|
|
|
3331 @node Rolodex, Window Configurations, Outliner, Top
|
|
|
3332 @chapter Rolodex
|
|
|
3333
|
|
|
3334 @cindex rolodex
|
|
|
3335 @cindex wrolo
|
|
|
3336 Hyperbole includes a complete, advanced rolodex system, Wrolo, for
|
|
|
3337 convenient management of hierarchical, record-oriented information.
|
|
|
3338
|
|
|
3339 @cindex rolo, buttons in
|
|
|
3340 Hyperbole buttons may be included within rolodex records and then
|
|
|
3341 manually activated whenever their records are retrieved.
|
|
|
3342
|
|
|
3343 @vindex file, wrolo.el
|
|
|
3344 See the description at the top of the @file{wrolo.el} file for
|
|
|
3345 details on programmatic interfacing to the rolodex. The following
|
|
|
3346 subsections explain use and basic customization of the rolodex.
|
|
|
3347
|
|
|
3348 @menu
|
|
|
3349 * Rolo Concepts::
|
|
|
3350 * Rolo Menu::
|
|
|
3351 * Rolo Keys::
|
|
|
3352 * Rolo Settings::
|
|
|
3353 @end menu
|
|
|
3354
|
|
|
3355 @node Rolo Concepts, Rolo Menu, Rolodex, Rolodex
|
|
|
3356 @section Rolo Concepts
|
|
|
3357
|
|
|
3358 @cindex rolodex file
|
|
|
3359 @cindex rolodex entry
|
|
|
3360 The rolodex manages and searches rolodex files. A @dfn{rolodex file}
|
|
|
3361 consists of an optional header which starts and ends with a line of
|
|
|
3362 equal signs (at least three equal signs starting at the beginning of a
|
|
|
3363 line), followed by any non-negative number of rolodex records. You must
|
|
|
3364 manually add a header to any rolodex file if you want it to have one.
|
|
|
3365
|
|
|
3366 @noindent
|
|
|
3367 Here is an example of a simple rolodex file.
|
|
|
3368
|
|
|
3369 @example
|
|
|
3370 @group
|
|
|
3371 ==================================================================
|
|
|
3372 PERSONAL ROLODEX
|
|
|
3373 <Last-Name>, <First> <Email> W<Work#> F<Fax#>
|
|
|
3374 ==================================================================
|
|
|
3375 * Smith, John <js@@hiho.com> W708-555-2001 F708-321-1492
|
|
|
3376 Chief Ether Maintainer, HiHo Industries
|
|
|
3377 10/24/95
|
|
|
3378 @end group
|
|
|
3379 @end example
|
|
|
3380
|
|
|
3381 We call rolodex records, @dfn{entries}. Entries begin with a delimiter,
|
|
|
3382 some number of `*' characters at the beginning of a line. Entries may
|
|
|
3383 be arranged in a hierarchy, where child entries begin with one more `*'
|
|
|
3384 characters than do their parents. Top level entries begin with a single
|
|
|
3385 `*'.
|
|
|
3386
|
|
|
3387 Beyond this initial delimiter, entries are completely free-form text.
|
|
|
3388 It is best to use a "lastname, firstname" format, however, when adding
|
|
|
3389 contact entries into a rolodex. Then the rolodex system will
|
|
|
3390 automatically keep your entries alphabetized as you enter them. You'll
|
|
|
3391 also be able to sort them whenever you desire.
|
|
|
3392
|
|
|
3393 Any search done on the rolodex scans the full text of each entry.
|
|
|
3394 During a search, the rolodex file header separator lines and anything in
|
|
|
3395 between are appended to the buffer of matched entries before any entries
|
|
|
3396 are retrieved from the file. Whenever an entry is matched, it and all
|
|
|
3397 of its descendant entries are retrieved. If your Emacs version supports
|
|
|
3398 textual highlighting, each search match is highlighted for quick, visual
|
|
|
3399 location.
|
|
|
3400
|
|
|
3401 @noindent
|
|
|
3402 For example, a search on "Company" could retrieve the following:
|
|
|
3403
|
|
|
3404 @example
|
|
|
3405 @group
|
|
|
3406 ==================================================================
|
|
|
3407 COMPANY ROLODEX
|
|
|
3408 ==================================================================
|
|
|
3409 * Company
|
|
|
3410 ** Manager
|
|
|
3411 *** Underlings
|
|
|
3412 @end group
|
|
|
3413 @end example
|
|
|
3414
|
|
|
3415 @noindent
|
|
|
3416 Thus, searching for Company retrieves all listed employees.
|
|
|
3417 Searching for Manager turns up all Underlings.
|
|
|
3418
|
|
|
3419
|
|
|
3420 @node Rolo Menu, Rolo Keys, Rolo Concepts, Rolodex
|
|
|
3421 @section Rolo Menu
|
|
|
3422
|
|
|
3423 @cindex rolodex menu
|
|
|
3424 The Rolo/ menu entry on the Hyperbole top-level menu provides the
|
|
|
3425 user interface to the rolodex. The rolo menu provides access to the
|
|
|
3426 following commands:
|
|
|
3427
|
|
|
3428 @cindex rolodex commands
|
|
|
3429 @cindex Wrolo commands
|
|
|
3430 @findex rolo-add
|
|
|
3431 @findex rolo-display-matches
|
|
|
3432 @findex rolo-edit
|
|
|
3433 @findex rolo-kill
|
|
|
3434 @findex rolo-mail-to
|
|
|
3435 @findex rolo-sort
|
|
|
3436 @findex rolo-grep
|
|
|
3437 @findex rolo-fgrep
|
|
|
3438 @findex rolo-word
|
|
|
3439 @findex rolo-yank
|
|
10
|
3440 @example
|
|
|
3441 @group
|
|
0
|
3442 Menu Item Command Description
|
|
|
3443 ====================================================================
|
|
|
3444 Add rolo-add Adds a rolodex entry
|
|
|
3445 Display rolo-display-matches Displays last matches again
|
|
|
3446 Edit rolo-edit Edits an existing rolodex entry
|
|
|
3447 Info Displays Rolodex manual entry
|
|
|
3448 Kill rolo-kill Removes an entry from the rolodex
|
|
|
3449 Mail rolo-mail Mail to address following point
|
|
|
3450 Order rolo-sort Sorts all levels in rolodex
|
|
|
3451 RegexFind rolo-grep Finds all entries containing
|
|
|
3452 a regular expression
|
|
|
3453 StringFind rolo-fgrep Finds all entries containing
|
|
|
3454 a string
|
|
|
3455 WordFind rolo-word Finds all entries containing
|
|
|
3456 a string of whole words
|
|
|
3457 Yank rolo-yank Inserts first matching rolodex
|
|
|
3458 entry at point
|
|
|
3459 ====================================================================
|
|
|
3460 @end group
|
|
|
3461 @end example
|
|
|
3462
|
|
|
3463 A prefix argument used with either of the find commands listed above
|
|
|
3464 limits the search to a maximum number of matches given by the argument.
|
|
|
3465 The search is terminated whenever that number of matches is found.
|
|
|
3466
|
|
|
3467 For any of the above commands that prompt for a name, you may use the
|
|
|
3468 form parent/child to locate a child entry below a parent entry. So for
|
|
|
3469 a rolodex which looked like so:
|
|
|
3470
|
|
|
3471 @example
|
|
|
3472 @group
|
|
|
3473 * Company
|
|
|
3474 ** Manager
|
|
|
3475 *** Underlings
|
|
|
3476 @end group
|
|
|
3477 @end example
|
|
|
3478
|
|
|
3479 @noindent
|
|
|
3480 You could edit the Underlings entry by identifying it as
|
|
|
3481 Company/Manager/Underlings. Do not use this hierarchical notation in
|
|
|
3482 search expressions since the whole rolodex will be searched anyway.
|
|
|
3483 Thus, "Underlings" as a search pattern will find an entry containing
|
|
|
3484 "Underlings" at any level in a hierarchy, like so:
|
|
|
3485
|
|
|
3486 @example
|
|
|
3487 *** Underlings
|
|
|
3488 @end example
|
|
|
3489
|
|
|
3490 @node Rolo Keys, Rolo Settings, Rolo Menu, Rolodex
|
|
|
3491 @section Rolo Keys
|
|
|
3492
|
|
|
3493 @kindex e
|
|
|
3494 @cindex rolodex, editing an entry
|
|
|
3495 Use the @{@kbd{e}@} key to edit the entry at point within the rolodex
|
|
|
3496 source file.
|
|
|
3497
|
|
|
3498 @cindex wrolo menu
|
|
|
3499 @cindex rolodex keys
|
|
|
3500 After a rolodex search is performed, point is left in the @dfn{rolodex
|
|
|
3501 match buffer}, @file{*Rolodex*}, which uses @code{wrolo-mode} to
|
|
|
3502 simplify browsing many rolodex matches. Press @{@kbd{?}@} when in the
|
|
|
3503 match buffer for a summary of available keys.
|
|
|
3504
|
|
|
3505 @kindex TAB
|
|
|
3506 @kindex M-TAB
|
|
|
3507 @kindex r
|
|
|
3508 @cindex rolodex, highlighting matches
|
|
|
3509 @cindex rolodex, finding matches
|
|
|
3510 @cindex rolodex, moving through matches
|
|
|
3511 If your Emacs version supports textual highlighting, each search match
|
|
|
3512 is highlighted for quick, visual location. @{@key{TAB}@} moves point
|
|
|
3513 forward to successive spans of text which match the search expression.
|
|
|
3514 @{@kbd{M-@key{TAB}}@} or @{@kbd{r}@} moves point backward to earlier
|
|
|
3515 matches. These keys allow you to quickly find the matching entry of
|
|
|
3516 most interest to you if your search expression failed to narrow the
|
|
|
3517 matches sufficiently.
|
|
|
3518
|
|
|
3519 @kindex M-s
|
|
|
3520 @kindex C-r
|
|
|
3521 @cindex rolodex, extending a match
|
|
|
3522 @cindex rolodex, interactive searching
|
|
|
3523 If you want to extend the match expression with some more characters to
|
|
|
3524 find a particular entry, use @{@kbd{M-s}@}, which performs an
|
|
|
3525 interactive search forward for the match expression. You can add or
|
|
|
3526 delete characters to this expression to find different occurences.
|
|
|
3527 @{@kbd{C-r}@} will reverse the direction of the search.
|
|
|
3528
|
|
|
3529 @kindex a
|
|
|
3530 @kindex h
|
|
|
3531 @kindex s
|
|
|
3532 @kindex t
|
|
|
3533 @cindex rolodex, outlining
|
|
|
3534 Single key outlining commands are also available for browsing matches.
|
|
|
3535 If your search matches a large number of entries, use
|
|
|
3536 @{@kbd{t}@} to get a top-level overview of all the entries. Each entry
|
|
|
3537 is collapsed so that only its first line shows. Press @{@kbd{s}@} to
|
|
|
3538 show (expand) the entry at point. Use @{@kbd{h}@} to hide (collapse)
|
|
|
3539 the entry again. Press @{@kbd{a}@} to expand all entries in the buffer.
|
|
|
3540
|
|
|
3541 Many other keys are defined to help you move through matching entries.
|
|
|
3542
|
|
|
3543 @cindex rolodex, moving to entries
|
|
|
3544 @table @kbd
|
|
|
3545 @kindex b
|
|
|
3546 @item b
|
|
|
3547 Move to the previous entry at the same level as the current entry.
|
|
|
3548 @kindex f
|
|
|
3549 @item f
|
|
|
3550 Move to the next entry at the same level as the current entry.
|
|
|
3551 @kindex n
|
|
|
3552 @item n
|
|
|
3553 Move to the next entry at any level.
|
|
|
3554 @kindex p
|
|
|
3555 @item p
|
|
|
3556 Move to the previous entry at any level.
|
|
|
3557 @kindex u
|
|
|
3558 @item u
|
|
24
|
3559 Move the the previous entry one level up.
|
|
0
|
3560 @kindex .
|
|
|
3561 @kindex <
|
|
|
3562 @item .
|
|
|
3563 @itemx <
|
|
|
3564 Move to the beginning of the buffer.
|
|
|
3565 @kindex ,
|
|
|
3566 @kindex >
|
|
|
3567 @item ,
|
|
|
3568 @itemx >
|
|
|
3569 Move to the end of the buffer.
|
|
|
3570 @kindex @key{DEL}
|
|
|
3571 @item @key{DEL}
|
|
|
3572 Scroll backward a windowful.
|
|
|
3573 @kindex @key{SPC}
|
|
|
3574 @item @key{SPC}
|
|
|
3575 Scroll forward a windowful.
|
|
|
3576 @end table
|
|
|
3577
|
|
|
3578 @kindex q
|
|
|
3579 @cindex rolodex, quitting
|
|
|
3580 Once you have found an entry of interest and you want to remove the
|
|
|
3581 rolodex match buffer, use @{@kbd{q}@} to quit. This will restore your
|
|
|
3582 current frame to its state prior to the rolodex search.
|
|
|
3583
|
|
|
3584 @node Rolo Settings, , Rolo Keys, Rolodex
|
|
|
3585 @section Rolo Settings
|
|
|
3586
|
|
|
3587 @vindex rolo-highlight-face
|
|
|
3588 @cindex rolodex, highlighting matches
|
|
|
3589 If textual highlighting is available in your Emacs on your current
|
|
|
3590 display type, the rolodex uses the value of @var{rolo-highlight-face} as
|
|
|
3591 the face to use to highlight search matches.
|
|
|
3592
|
|
|
3593 @vindex rolo-kill-buffers-after-use
|
|
|
3594 The buffers containing the rolodex files are not killed after a search
|
|
|
3595 on the assumption that another search is likely to follow within this
|
|
|
3596 Emacs session. You may wish to change this behavior with the following
|
|
|
3597 setting: @code{(setq rolo-kill-buffers-after-use t)}.
|
|
|
3598
|
|
|
3599 @vindex rolo-save-buffers-after-use
|
|
|
3600 After an entry is killed, the modified rolodex file is automatically
|
|
|
3601 saved. If you would rather always save files yourself, use this
|
|
|
3602 setting: @code{(setq rolo-save-buffers-after-use nil)}.
|
|
|
3603
|
|
|
3604 @vindex rolo-email-format
|
|
|
3605 When adding an entry from within a buffer containing a mail message, the
|
|
|
3606 rolodex add function will extract the sender's name and e-mail address
|
|
|
3607 and prompt you with the name as a default. If you accept it, it will
|
|
|
3608 enter the name and the email address using the format given by the
|
|
|
3609 @var{rolo-email-format} variable. See its documentation if you want to
|
|
|
3610 change its value.
|
|
|
3611
|
|
|
3612 @vindex rolo-file-list
|
|
|
3613 @cindex rolodex, personal
|
|
|
3614 The files used in any rolodex search are given by the
|
|
|
3615 @var{rolo-file-list} variable, whose default value is
|
|
|
3616 @code{("~/.rolodex.otl")}, so that searches initially scan only your
|
|
|
3617 personal rolodex. Any entries added to this list should be file
|
|
|
3618 pathnames. If a file in the list does not exist or is not readable, it
|
|
|
3619 is skipped. Files are searched in the order in which they appear in the
|
|
|
3620 list. In general, you should leave your personal rolodex file as the
|
|
|
3621 first entry in the list, since this is the only file to which the rolo
|
|
|
3622 menu Add command adds entries.@refill
|
|
|
3623
|
|
|
3624 @vindex rolo-entry-regexp
|
|
|
3625 The rolodex entry start delimiter is given by the regular expression
|
|
|
3626 variable, @var{rolo-entry-regexp}, whose default value is "^\*+".
|
|
|
3627
|
|
|
3628 @vindex rolo-hdr-regexp
|
|
|
3629 A rolodex file may begin with an optional header section which is copied
|
|
|
3630 to the match display buffer whenever any matches are found during a
|
|
|
3631 search. The start and end lines of this header are controlled by
|
|
|
3632 the regular expression variable, @var{rolo-hdr-regexp}, whose default
|
|
|
3633 value is "^===". This allows lines of all equal signs to visually
|
|
|
3634 separate matching entries from multiple files retrieved from a single
|
|
|
3635 search.
|
|
|
3636
|
|
|
3637 @node Window Configurations, Developing with Hyperbole, Rolodex, Top
|
|
|
3638 @chapter Window Configurations
|
|
|
3639
|
|
|
3640 @cindex window configurations
|
|
|
3641 @cindex restoring windows
|
|
|
3642 @cindex saving window configurations
|
|
|
3643 @vindex file, wconfig.el
|
|
|
3644 Hyperbole includes the @file{wconfig.el} package which lets you save and
|
|
|
3645 restore window configurations, i.e@. the window layout and buffers
|
|
|
3646 displayed within an Emacs frame. This is useful to save a particular
|
|
|
3647 working context and then to jump back to it at a later time during an
|
|
|
3648 Emacs session. It is also useful during demonstrations to pull up many
|
|
|
3649 informational artifacts all at once, e.g@. all of the windows for a
|
|
|
3650 particular subsystem. None of this information is stored between Emacs
|
|
|
3651 sessions, so your window configurations will last only through a single
|
|
|
3652 session of use.
|
|
|
3653
|
|
|
3654 The wconfig library provides two distinct means of managing window
|
|
|
3655 configurations. The first means associates a name with each stored
|
|
|
3656 window configuration. The name can then be used to retrieve the window
|
|
|
3657 configuration later. The second means uses a ring structure to save
|
|
|
3658 window configurations and then allows browsing through the sequence of
|
|
|
3659 saved configurations.
|
|
|
3660
|
|
|
3661 The Win/ menu entry on the Hyperbole top-level menu displays a menu of
|
|
|
3662 window configuration commands:
|
|
|
3663
|
|
|
3664 @noindent
|
|
|
3665 @display
|
|
|
3666 WinConfig> AddName DeleteName RestoreName PopRing SaveRing YankRing
|
|
|
3667 @end display
|
|
|
3668
|
|
10
|
3669 @cindex wconfig commands
|
|
|
3670 @cindex window configuration commands
|
|
0
|
3671 @findex wconfig-add-by-name
|
|
|
3672 @findex wconfig-delete-by-name
|
|
|
3673 @findex wconfig-restore-by-name
|
|
|
3674 @findex wconfig-delete-pop
|
|
|
3675 @findex wconfig-ring-save
|
|
|
3676 @findex wconfig-yank-pop
|
|
24
|
3677 @example
|
|
|
3678 @group
|
|
0
|
3679 Menu Item Command Description
|
|
|
3680 ====================================================================
|
|
|
3681 AddName wconfig-add-by-name Name current wconfig
|
|
|
3682 DeleteName wconfig-delete-by-name Delete wconfig with name
|
|
|
3683 RestoreName wconfig-restore-by-name Restore wconfig by name
|
|
|
3684
|
|
|
3685 PopRing wconfig-delete-pop Restore and delete wconfig
|
|
|
3686 SaveRing wconfig-ring-save Store wconfig to ring
|
|
|
3687 YankRing wconfig-yank-pop Restore next wconfig
|
|
|
3688 ====================================================================
|
|
|
3689 @end group
|
|
|
3690 @end example
|
|
|
3691
|
|
|
3692 Saving and restoring window configurations by name is the easiest
|
|
|
3693 method, but it requires that you input the chosen name from the
|
|
|
3694 keyboard. The ring commands permit saving and restoring through mouse
|
|
|
3695 interaction only, if so desired. The prior section, @ref{Smart Keys},
|
|
|
3696 mentions how to save and restore window configurations with the Smart Keys.
|
|
|
3697 Since the ring commands are a bit more complex than their by-name
|
|
|
3698 counterparts, the following paragraphs explain them in more detail.
|
|
|
3699
|
|
|
3700 @vindex kill-ring
|
|
|
3701 Wconfig creates a ring structure that operates just like the Emacs
|
|
|
3702 @var{kill-ring}, @ref{Kill Ring,,,emacs, The GNU Emacs Manual}, but its
|
|
|
3703 elements are window configurations rather than text regions. One can
|
|
|
3704 add an element to the ring based upon the current window configuration.
|
|
|
3705 After several elements are in the ring, one can walk through all of them
|
|
|
3706 in sequence until the desired configuration is restored.
|
|
|
3707
|
|
|
3708 @findex wconfig-ring-save
|
|
|
3709 SaveRing executes the @code{wconfig-ring-save} command which
|
|
|
3710 saves the current window configuration to the ring.
|
|
|
3711
|
|
|
3712 @findex wconfig-yank-pop
|
|
|
3713 YankRing executes the @code{wconfig-yank-pop} command. It restores the
|
|
|
3714 window configuration from the currently pointed to configuration in the
|
|
|
3715 ring. It does not delete this configuration from the ring but it does
|
|
|
3716 move the pointer to the prior ring element. Repeated calls to this
|
|
|
3717 command thus restore successive window configurations until the ring
|
|
|
3718 pointer wraps around. Simply stop when a desired configuration appears
|
|
|
3719 and use @{@kbd{q}@} to quit from the minibuffer menu.
|
|
|
3720
|
|
|
3721 @findex wconfig-delete-pop
|
|
|
3722 PopRing calls the @code{wconfig-delete-pop} command.
|
|
|
3723 It is used to restore a previously saved configuration and at the same
|
|
|
3724 time delete it from the ring. Simply stop when a desired configuration
|
|
|
3725 appears and use @{@kbd{q}@} to quit from the minibuffer menu.
|
|
|
3726
|
|
|
3727 @vindex wconfig-ring-max
|
|
|
3728 The maximum number of elements the ring can hold is set by the
|
|
|
3729 @var{wconfig-ring-max} variable whose default is 10. Any saves beyond
|
|
|
3730 this value cause deletion of the oldest element in the ring before
|
|
|
3731 a new one is added.
|
|
|
3732
|
|
|
3733 @node Developing with Hyperbole, Glossary, Window Configurations, Top
|
|
|
3734 @chapter Developing with Hyperbole
|
|
|
3735
|
|
|
3736 This chapter is only for people who are familiar with Emacs Lisp and
|
|
|
3737 wish to customize Hyperbole, to extend it, or to develop other systems
|
|
|
3738 using Hyperbole as a base.
|
|
|
3739
|
|
|
3740 @menu
|
|
|
3741 * Hook Variables::
|
|
|
3742 * Creating Types::
|
|
|
3743 * Explicit Button Technicalities::
|
|
|
3744 * Encapsulating Systems::
|
|
|
3745 * Embedding Hyperbole::
|
|
|
3746 @end menu
|
|
|
3747
|
|
|
3748 @node Hook Variables, Creating Types, Developing with Hyperbole, Developing with Hyperbole
|
|
|
3749 @section Hook Variables
|
|
|
3750
|
|
|
3751 @cindex variables
|
|
|
3752 @cindex hook variables
|
|
|
3753 Hyperbole provides a number of hook variables that allow you to adjust
|
|
|
3754 its basic operations to meet your own needs, without requiring you to
|
|
|
3755 change the code for those operations.
|
|
|
3756
|
|
|
3757 We find it best to always set the value of hook variables either to nil
|
|
|
3758 or to a list of function names of no arguments, each of which will be
|
|
|
3759 called in sequence when the hook is triggered.
|
|
|
3760
|
|
|
3761 Given the name of a function, a Hyperbole hook variable triggered within
|
|
|
3762 that function has the same name as the function with a @code{-hook}
|
|
|
3763 appended. Hyperbole provides the following hook variables:
|
|
|
3764
|
|
|
3765 @table @var
|
|
|
3766
|
|
|
3767 @vindex hyperb:init-hook
|
|
|
3768 @item hyperb:init-hook
|
|
|
3769 For customization at Hyperbole initialization time. Use this to load
|
|
|
3770 any personal Hyperbole type definitions you might have. It is run after
|
|
|
3771 Hyperbole support code is loaded but before Hyperbole session
|
|
|
3772 initializations take place.
|
|
|
3773
|
|
|
3774 @vindex action:act-hook
|
|
|
3775 @vindex hbut:current
|
|
|
3776 @item action:act-hook
|
|
|
3777 Run before each Hyperbole button activation.
|
|
|
3778 The variable @var{hbut:current} contains the button to be activated when
|
|
|
3779 this is run.
|
|
|
3780
|
|
|
3781 @vindex ebut:create-hook
|
|
|
3782 @item ebut:create-hook
|
|
|
3783 To add to the Hyperbole explicit button creation process.
|
|
|
3784
|
|
|
3785 @vindex ebut:delete-hook
|
|
|
3786 @item ebut:delete-hook
|
|
|
3787 To add to the Hyperbole explicit button deletion process.
|
|
|
3788
|
|
|
3789 @vindex ebut:modify-hook
|
|
|
3790 @item ebut:modify-hook
|
|
|
3791 Executed when an explicit button's attributes are modified.
|
|
|
3792
|
|
|
3793 @vindex hibtypes:begin-load-hook
|
|
|
3794 @item hibtypes:begin-load-hook
|
|
|
3795 Executed prior to loading of standard Hyperbole implicit button types.
|
|
|
3796 Used to load site-specific low priority implicit button types since
|
|
|
3797 lowest priority ibtypes are loaded first.
|
|
|
3798
|
|
|
3799 @vindex hibtypes:end-load-hook
|
|
|
3800 @item hibtypes:end-load-hook
|
|
|
3801 Executed after loading of standard Hyperbole implicit button types.
|
|
|
3802 Used to load site-specific high priority implicit button types since
|
|
|
3803 highest priority ibtypes are loaded last.
|
|
|
3804
|
|
|
3805 @vindex htype:create-hook
|
|
|
3806 @item htype:create-hook
|
|
|
3807 Executed when a Hyperbole type (e.g@. action type or implicit button
|
|
|
3808 type) is added to the environment.
|
|
|
3809
|
|
|
3810 @vindex htype:delete-hook
|
|
|
3811 @item htype:delete-hook
|
|
|
3812 Executed when a type is deleted from the environment.
|
|
|
3813
|
|
|
3814 @vindex kotl-mode-hook
|
|
|
3815 @item kotl-mode-hook
|
|
|
3816 Executed when a Koutline is created or read in or when kotl-mode is
|
|
|
3817 invoked.
|
|
|
3818
|
|
|
3819 @vindex wrolo-display-hook
|
|
|
3820 @item wrolo-display-hook
|
|
|
3821 Executed when rolodex matches are displayed.
|
|
|
3822
|
|
|
3823 @vindex wrolo-mode-hook
|
|
|
3824 @item wrolo-mode-hook
|
|
|
3825 Executed when a rolodex match buffer is created and put into wrolo-mode.
|
|
|
3826
|
|
|
3827 @vindex wrolo-yank-reformat-function
|
|
|
3828 @cindex yank, reformatting
|
|
|
3829 @item wrolo-yank-reformat-function
|
|
|
3830 A variable whose value may be set to a function of two arguments, START
|
|
|
3831 and END, indicating the region of the rolodex entry yanked into the
|
|
|
3832 current buffer by the rolo-yank command. The function may reformat this
|
|
|
3833 region to meed user-specific needs.
|
|
|
3834
|
|
|
3835 @end table
|
|
|
3836
|
|
|
3837 @noindent
|
|
|
3838 Hyperbole also makes use of a number of external Emacs hook variables.
|
|
|
3839
|
|
|
3840 @table @var
|
|
|
3841
|
|
|
3842 @vindex find-file-hooks
|
|
|
3843 @cindex button highlighting
|
|
|
3844 @item find-file-hooks
|
|
|
3845 This is called whenever a file is read into a GNU Emacs buffer.
|
|
|
3846 Hyperbole uses it to highlight any buttons within files when run under
|
|
|
3847 any NEXTSTEP or X window system-based versions of GNU Emacs.
|
|
|
3848
|
|
|
3849 @vindex write-file-hooks
|
|
|
3850 @cindex button data saving
|
|
|
3851 @item write-file-hooks
|
|
|
3852 This is called whenever a GNU Emacs buffer is written to a file.
|
|
|
3853 Hyperbole uses it to save any modified button data associated with the
|
|
|
3854 file's directory.
|
|
|
3855
|
|
|
3856 @cindex mail hooks
|
|
|
3857 @cindex news hooks
|
|
|
3858 Hyperbole mail and news facilities also utilize a number of external hook
|
|
|
3859 variables. These hide button data and highlight buttons if possible.
|
|
|
3860 See the various support files for details.
|
|
|
3861 @end table
|
|
|
3862
|
|
|
3863 @node Creating Types, Explicit Button Technicalities, Hook Variables, Developing with Hyperbole
|
|
|
3864 @section Creating Types
|
|
|
3865
|
|
|
3866 @cindex type definition
|
|
|
3867 @cindex type redefinition
|
|
|
3868 @noindent
|
|
|
3869 To define or redefine a single Hyperbole type, you may either:
|
|
|
3870
|
|
|
3871 @itemize @bullet
|
|
|
3872 @kindex C-M-x
|
|
|
3873 @findex eval-defun
|
|
|
3874 @kindex C-x C-e
|
|
|
3875 @findex eval-last-sexp
|
|
|
3876 @item
|
|
|
3877 move your Emacs point to within the type definition and use
|
|
|
3878 @{@kbd{C-M-x}@} @code{(eval-defun)} (only works in Emacs Lisp mode);
|
|
|
3879
|
|
|
3880 @item
|
|
|
3881 or move your point to the end of the last line of the type definition and
|
|
|
3882 use @{@kbd{C-x C-e}@} @code{(eval-last-sexp)} (works in most modes).
|
|
|
3883 @end itemize
|
|
|
3884
|
|
|
3885 @cindex Hyperbole types
|
|
|
3886 @vindex class, htype
|
|
|
3887 The functions from the @code{htype} class may be applied to any
|
|
|
3888 Hyperbole types, if needed.
|
|
|
3889
|
|
|
3890 @vindex file, hactypes.el
|
|
|
3891 @vindex file, hibtypes.el
|
|
|
3892 The following subsections explain the specifics of Hyperbole type
|
|
|
3893 definitions which are beyond standard practice for Emacs Lisp programming.
|
|
|
3894 See the definitions of the standard types in @file{hactypes.el}
|
|
|
3895 and @file{hibtypes.el} for examples.
|
|
|
3896
|
|
|
3897 @menu
|
|
|
3898 * Action Type Creation::
|
|
|
3899 * Implicit Button Types::
|
|
|
3900 @end menu
|
|
|
3901
|
|
|
3902 @node Action Type Creation, Implicit Button Types, Creating Types, Creating Types
|
|
|
3903 @subsection Action Type Creation
|
|
|
3904
|
|
|
3905 @findex actype:create
|
|
|
3906 @vindex file, hactypes.el
|
|
|
3907 @vindex file, hbut.el
|
|
|
3908 New forms of explicit buttons may be created by adding new action types
|
|
|
3909 to a Hyperbole environment. The file, @file{hactypes.el}, provides
|
|
|
3910 many examples of working action types.
|
|
|
3911
|
|
|
3912 @cindex action type, creation
|
|
|
3913 @findex defact
|
|
|
3914 @findex actype:create
|
|
|
3915 An action type is created, i.e@. loaded into the Hyperbole environment,
|
|
|
3916 with the @code{(defact)} function (which is an alias for
|
|
|
3917 @code{(actype:create)}). The calling signature for this function is
|
|
|
3918 given in its documentation; it is the same as that of @code{(defun)}
|
|
|
3919 except that a documentation string is required. (An interactive calling
|
|
|
3920 form is also required if the action type has formal parameters and is to
|
|
|
3921 be used in explicit button definitions. Implicit buttons never use an
|
|
|
3922 action type's interactive form. It is good practice to include an
|
|
|
3923 interactive form since the type creator cannot know how users may choose
|
|
|
3924 to apply the type.)@refill
|
|
|
3925
|
|
|
3926 An action type's parameters are used differently than those of a
|
|
|
3927 function being called. Its interactive calling form is used when an
|
|
|
3928 explicit button is created to prompt for type-specific button
|
|
|
3929 attributes. The rest of its body is used when a button with that action
|
|
|
3930 type is activated. Then the button attributes together with the action
|
|
|
3931 type body are used to form an action that is executed in response to the
|
|
|
3932 button activation. The action's result is returned to the action caller
|
|
|
3933 unless it returns nil, in which case t is returned to the caller to
|
|
|
3934 ensure that it registers the performance of the action.
|
|
|
3935
|
|
|
3936 An action type body may perform any computation using Emacs Lisp and
|
|
|
3937 Hyperbole functions.
|
|
|
3938
|
|
|
3939 @cindex interactive form
|
|
|
3940 @findex interactive
|
|
|
3941 The interactive calling form for an action type is of the same form as
|
|
|
3942 that of a regular Emacs Lisp function definition (see the documentation
|
|
|
3943 for the Emacs Lisp @code{(interactive)} form). It may additionally use
|
|
|
3944 Hyperbole command character extensions when the form is given as a
|
|
|
3945 string. Each such extension character @emph{must} be preceded by a plus
|
|
|
3946 sign, @code{+}, in order to be recognized since such characters may also
|
|
|
3947 have standard interactive form meanings.
|
|
|
3948
|
|
|
3949 The present Hyperbole extension characters are:
|
|
|
3950
|
|
|
3951 @table @strong
|
|
|
3952 @cindex argument, Info node
|
|
|
3953 @cindex interactive cmd char, +I
|
|
|
3954 @item +I
|
|
|
3955 Prompts for an existing Info node name and file.
|
|
|
3956
|
|
|
3957 @cindex argument, kcell
|
|
|
3958 @cindex argument, koutline
|
|
|
3959 @cindex interactive cmd char, +K
|
|
|
3960 @item +K
|
|
|
3961 Prompts for an existing kcell identifier, either a full outline level
|
|
|
3962 identifier or a permanent idstamp.
|
|
|
3963
|
|
|
3964 @cindex interactive cmd char, +M
|
|
|
3965 @cindex argument, mail message
|
|
|
3966 @item +M
|
|
|
3967 Prompts for a mail message date and the file name it resides in.
|
|
|
3968 The mail parameters prompted for by this character code are likely to
|
|
|
3969 change in the future.
|
|
|
3970
|
|
|
3971 @cindex argument, view spec
|
|
|
3972 @cindex interactive cmd char, +V
|
|
|
3973 @item +V
|
|
|
3974 Prompts for a Hyperbole view specification.
|
|
|
3975 Not yet available for use.
|
|
|
3976
|
|
|
3977 @end table
|
|
|
3978
|
|
|
3979 @vindex class, hargs
|
|
|
3980 @cindex argument, reading
|
|
|
3981 Arguments are read by the functions in Hyperbole's @code{hargs} class,
|
|
|
3982 rather than the standard Lisp @code{read} functions, in order to allow
|
|
|
3983 direct selection of arguments via the Action Key.
|
|
|
3984
|
|
|
3985 If an action type create is successful, the symbol that Hyperbole uses
|
|
|
3986 internally to reference the type is returned. @code{Nil} is returned on
|
|
|
3987 failure so that you may test whether or not the operation succeeds.
|
|
|
3988
|
|
|
3989 Once you have defined an action type within your present Hyperbole
|
|
|
3990 environment, you can create new explicit buttons which use it. There is
|
|
|
3991 no explicit button type beyond its action type, so no further work is
|
|
|
3992 necessary.
|
|
|
3993
|
|
|
3994 @findex actype:delete
|
|
|
3995 Call @code{(actype:delete)} to remove an action type from a Hyperbole
|
|
|
3996 environment. It takes a single parameter which should be the same type
|
|
|
3997 symbol used in the type definition call (not the Hyperbole symbol
|
|
|
3998 returned by the call).
|
|
|
3999
|
|
|
4000 @node Implicit Button Types, , Action Type Creation, Creating Types
|
|
|
4001 @subsection Implicit Button Types
|
|
|
4002
|
|
|
4003 @cindex implicit button type
|
|
|
4004 @cindex ibtype
|
|
|
4005 @findex defib
|
|
|
4006 @findex ibtype:create
|
|
|
4007 An implicit button type is created or loaded via the @code{(defib)}
|
|
|
4008 function (which is an alias for @code{(ibtype:create)}). The calling
|
|
|
4009 signature for this function is given in its documentation; it is the
|
|
|
4010 same as that of @code{(defun)}, but with a number of constraints. The
|
|
|
4011 parameter list should always be empty since no parameters will be used.
|
|
|
4012 A documentation string is required. The type's body follows this.
|
|
|
4013
|
|
|
4014 @cindex ibtype, predicate
|
|
|
4015 @cindex ibtype, argument
|
|
|
4016 @cindex ibtype, return val
|
|
|
4017 @cindex ibtype, actype
|
|
|
4018 The body of an implicit button type is a predicate which determines
|
|
|
4019 whether or not point is within an implicit button of the type. If not,
|
|
|
4020 the predicate returns @code{nil}. If so, it may optionally setup to
|
|
|
4021 flash the button and then perform one or more actions. A call of the
|
|
|
4022 form: @code{(ibut:label-set label start-pos end-pos)} is used to setup
|
|
|
4023 the button flashing, if desired. This is then typically immediately
|
|
|
4024 followed by an action invocation of the form:
|
|
|
4025 @code{(hact 'actype &rest actype-arguments)}. It is imperative that all
|
|
|
4026 actions (non-predicate code) be invoked through the @code{(hact)}
|
|
|
4027 function rather than directly or your ibtypes will not work properly.
|
|
|
4028 (Hyperbole first tests to see if any ibtype matches the current context
|
|
|
4029 before activating any type, so it ensures that @code{(hact)} calls are
|
|
|
4030 disabled during this testing.) Any action types used may be created
|
|
|
4031 before or after the implicit button type definition but obviously should
|
|
|
4032 be defined before any implicit buttons of the given type are activated;
|
|
|
4033 an error will result, otherwise.
|
|
|
4034
|
|
|
4035 If an implicit button type create is successful, the symbol that
|
|
|
4036 Hyperbole uses internally to reference the type is returned. @code{Nil}
|
|
|
4037 is returned on failure so that you may test whether or not the operation
|
|
|
4038 succeeds. Implicit button type names and action type names may be the
|
|
|
4039 same without any conflict. In fact, such naming is encouraged when an
|
|
|
4040 implicit button type is the exclusive user of an action type.
|
|
|
4041
|
|
|
4042 @findex ibtype:delete
|
|
|
4043 Call @code{(ibtype:delete)} to remove an implicit button type from a
|
|
|
4044 Hyperbole environment. It takes a single parameter which should be the
|
|
|
4045 same type symbol used in the type definition call (not the Hyperbole
|
|
|
4046 symbol returned by the call). This will not delete the action type used
|
|
|
4047 by the implicit button; that must be done separately.
|
|
|
4048
|
|
|
4049 @cindex ibtype, help
|
|
|
4050 @findex ibut:at-p
|
|
|
4051 @vindex class, hattr
|
|
|
4052 @vindex class, hbut
|
|
|
4053 @vindex file, hib-kbd.el
|
|
|
4054 By default, a request for help on an implicit button will display the
|
|
|
4055 button's attributes in the same manner as is done for explicit buttons.
|
|
|
4056 For some implicit button types, other forms of help will be more
|
|
|
4057 appropriate. If an Emacs Lisp function is defined whose name is formed
|
|
|
4058 from the concatenation of the type name followed by @code{:help}, e.g@.
|
|
|
4059 @code{my-ibtype:help}, it is used to respond to requests for
|
|
|
4060 help on buttons of that type. Any such function should take a single
|
|
|
4061 argument of an implicit button construct. (This is what
|
|
|
4062 @code{(ibut:at-p)} returns when point is within an implicit button
|
|
|
4063 context.) The button may be queried for its attributes using functions
|
|
|
4064 from the @code{hbut} and @code{hattr} classes. See the @file{hib-kbd.el}
|
|
|
4065 file for an example of a custom help function.
|
|
|
4066
|
|
|
4067 @node Explicit Button Technicalities, Encapsulating Systems, Creating Types, Developing with Hyperbole
|
|
|
4068 @section Explicit Button Technicalities
|
|
|
4069 @menu
|
|
|
4070 * Button Label Normalization::
|
|
|
4071 * Operational and Storage Formats::
|
|
|
4072 * Programmatic Button Creation::
|
|
|
4073 @end menu
|
|
|
4074
|
|
|
4075 @node Button Label Normalization, Operational and Storage Formats, Explicit Button Technicalities, Explicit Button Technicalities
|
|
|
4076 @subsection Button Label Normalization
|
|
|
4077 @cindex normalized label
|
|
|
4078 @cindex button label
|
|
|
4079 @cindex button key
|
|
|
4080 @vindex hbut:label-to-key
|
|
|
4081 Hyperbole uses a normalized form of button labels called button keys (or
|
|
|
4082 label keys) for all internal operations. See the documentation for the
|
|
|
4083 function @code{(hbut:label-to-key)} for details of the normalization
|
|
|
4084 process. The normalized form permits Hyperbole to recognize buttons that
|
|
|
4085 are the same but whose labels appear different from one another, due to
|
|
|
4086 text formatting conventions. For example, all of the following would
|
|
|
4087 be recognized as the same button.
|
|
|
4088
|
|
|
4089 @example
|
|
|
4090 <(fake button)> <( fake button)>
|
|
|
4091
|
|
|
4092 Pam> <(fake
|
|
|
4093 Pam> button)>
|
|
|
4094
|
|
|
4095 ;; <(fake
|
|
|
4096 ;; button)>
|
|
|
4097
|
|
|
4098 /* <( fake */
|
|
|
4099 /* button )> */
|
|
|
4100 @end example
|
|
|
4101
|
|
|
4102 @vindex hbut:fill-prefix-regexps
|
|
|
4103 @vindex fill-prefix
|
|
|
4104 @cindex fill prefix
|
|
|
4105 @cindex button, multiple lines
|
|
|
4106 @cindex button, split across lines
|
|
|
4107 The last three examples demonstrate how Hyperbole ignores common fill
|
|
|
4108 prefix patterns that happen to fall within the middle of a button label
|
|
|
4109 that spans multiple lines. As long as such buttons are selected with
|
|
|
4110 point at a location within the label's first line, the button will be
|
|
|
4111 recognized. The variable @var{hbut:fill-prefix-regexps} holds the list
|
|
|
4112 of fill prefixes recognized when embedded within button labels. All
|
|
|
4113 such prefixes are recognized (one per button label), regardless of the
|
|
|
4114 setting of the GNU Emacs variable, @var{fill-prefix}, so no user
|
|
|
4115 intervention is required.
|
|
|
4116
|
|
|
4117 @node Operational and Storage Formats, Programmatic Button Creation, Button Label Normalization, Explicit Button Technicalities
|
|
|
4118 @subsection Operational and Storage Formats
|
|
|
4119
|
|
|
4120 @cindex explicit button, formats
|
|
|
4121 @cindex explicit button, storage
|
|
|
4122 @cindex storage manager
|
|
|
4123 @cindex button attributes
|
|
|
4124 @vindex hbut:current
|
|
|
4125 Hyperbole uses a terse format to store explicit buttons and a more
|
|
|
4126 meaningful one to show users and to manipulate during editing. The
|
|
|
4127 terse format consists solely of button attribute values whereas the edit
|
|
|
4128 format includes an attribute name with each attribute value. A button
|
|
|
4129 in edit format consists of a Lisp symbol together with its attribute list
|
|
|
4130 which holds the attribute names and values. In this way, buttons may be
|
|
|
4131 passed along from function to function simply by passing the symbol to
|
|
|
4132 which the button is attached. Most functions utilize the pre-defined
|
|
|
4133 @var{hbut:current} symbol by default to store and retrieve the last
|
|
|
4134 encountered button in edit format.
|
|
|
4135
|
|
|
4136 @vindex class, hbdata
|
|
|
4137 @vindex class, ebut
|
|
|
4138 @vindex class, hbut
|
|
|
4139 The @code{hbdata} class handles the terse, stored format. The
|
|
|
4140 @code{hbut}, @code{ebut}, and @code{ibut} classes work with the
|
|
|
4141 name/value format. This separation permits the wholesale replacement of
|
|
|
4142 the storage manager with another, with any interface changes hidden from
|
|
|
4143 any Hyperbole client programming.
|
|
|
4144
|
|
|
4145 @node Programmatic Button Creation, , Operational and Storage Formats, Explicit Button Technicalities
|
|
|
4146 @subsection Programmatic Button Creation
|
|
|
4147
|
|
|
4148 @cindex explicit button, creation
|
|
|
4149 A common need when developing with Hyperbole is the ability to create or
|
|
|
4150 modify explicit buttons without user interaction. For example, an
|
|
|
4151 application might require the addition of an explicit summary button to
|
|
|
4152 a file for each new mail message a user reads that contains a set of
|
|
|
4153 keywords. The user could then check the summary file and jump to
|
|
|
4154 desired messages quickly.
|
|
|
4155
|
|
|
4156 @vindex class, ebut
|
|
|
4157 @vindex file, hbut.el
|
|
|
4158 @findex ebut:create
|
|
|
4159 @findex ebut:map
|
|
|
4160 The Hyperbole class @code{ebut} supports programmatic access to explicit
|
|
|
4161 buttons. See it within the @file{hbut.el} file for full details. The
|
|
|
4162 documentation for @code{(ebut:create)} explains the set of attributes
|
|
|
4163 settings necessary to create an explicit button. For operations over
|
|
|
4164 the whole set of buttons within the visible (non-narrowed) portion of a
|
|
|
4165 buffer, use the @code{(ebut:map)} function.
|
|
|
4166
|
|
|
4167 @page
|
|
|
4168 @node Encapsulating Systems, Embedding Hyperbole, Explicit Button Technicalities, Developing with Hyperbole
|
|
|
4169 @section Encapsulating Systems
|
|
|
4170
|
|
|
4171 @vindex file, hsys-*
|
|
|
4172 @cindex Hyperbole, system encapsulation
|
|
|
4173 @cindex system encapsulation
|
|
|
4174 A powerful use of implicit button types is to provide a Hyperbole-based
|
|
|
4175 interface to external systems. The basic idea is to interpret patterns
|
|
|
4176 output by the application as implicit buttons.
|
|
|
4177
|
|
|
4178 See the @file{hsys-*} files for examples of how to do this.
|
|
|
4179 Encapsulations are provided for the following systems (the systems
|
|
|
4180 themselves are not included with Hyperbole):
|
|
|
4181
|
|
|
4182 @table @bullet
|
|
|
4183 @item World-Wide Web
|
|
|
4184 The world-wide web system originally developed at CERN, that now spans
|
|
|
4185 the Internet universe. This is automatically loaded by Hyperbole so
|
|
|
4186 that a press of the Action Key follows a URL.
|
|
|
4187
|
|
|
4188 @item WAIS
|
|
|
4189 The Wide Area Information Systems full text-retrieval system orginally
|
|
|
4190 developed at Thinking Machines and then later at WAIS Inc.
|
|
|
4191
|
|
|
4192 @item HyperBase
|
|
|
4193 A hypertextual storage manager that stores textual nodes as records with
|
|
|
4194 locking so that multiple users can read and edit hypertexts.
|
|
|
4195 @end table
|
|
|
4196
|
|
|
4197
|
|
|
4198 @node Embedding Hyperbole, , Encapsulating Systems, Developing with Hyperbole
|
|
|
4199 @section Embedding Hyperbole
|
|
|
4200
|
|
|
4201 [NOTE: We have never done this ourselves, though we have done similar
|
|
|
4202 things which leads us to infer that the task should not be difficult.]
|
|
|
4203
|
|
|
4204 @cindex Hyperbole API
|
|
|
4205 @cindex API
|
|
|
4206 @cindex programming interface
|
|
|
4207 @cindex Hyperbole, embedding
|
|
|
4208 The standard Emacs-based Hyperbole user interface has purposely been
|
|
|
4209 separated from the Hyperbole backend to support the development of
|
|
|
4210 alternative interfaces and the embedding of Hyperbole functionality
|
|
|
4211 within other system prototypes. The Hyperbole backend functionality
|
|
|
4212 that system developers can make use of is called its Application
|
|
|
4213 Programming Interface (API). The API may be used to make server-based
|
|
|
4214 calls to Hyperbole when Emacs is run as a non-interactive (batch)
|
|
|
4215 process, with its input/output streams attached to another process.
|
|
|
4216
|
|
|
4217 The public functions and variables from the following files may be
|
|
|
4218 considered the present Hyperbole API:
|
|
|
4219
|
|
|
4220 @noindent
|
|
|
4221 @file{hact.el}, @file{hargs.el}, @file{hbmap.el}, @file{hbut.el},
|
|
|
4222 @file{hhist.el}, @file{hmail.el}, @file{hmoccur.el}, @file{hpath.el},
|
|
|
4223 @file{htz.el}, @file{hypb.el}, @file{set.el}, @file{wconfig.el},
|
|
|
4224 @file{wrolo.el}, and @file{wrolo-logic.el}.@refill
|
|
|
4225
|
|
|
4226 @noindent
|
|
|
4227 Note when looking at these files, that they are divided into sections
|
|
|
4228 that separate one data abstraction (class) from another. A line of
|
|
|
4229 dashes within a class separates public parts of the class from the
|
|
|
4230 private parts that follow the line.
|
|
|
4231
|
|
|
4232 This API does not include the Hyperbole outliner, as it has been
|
|
|
4233 designed for interactive use, rather than programmatic extensibility.
|
|
|
4234 You can certainly study its code, below the @file{hyperbole/kotl/}
|
|
|
4235 directory and learn to program it, however.
|
|
|
4236
|
|
|
4237
|
|
|
4238 @node Glossary, Smart Key Reference, Developing with Hyperbole, Top
|
|
|
4239 @appendix Glossary
|
|
|
4240
|
|
|
4241 Concepts pertinent to operational usage of Hyperbole are defined here.
|
|
|
4242 If some GNU Emacs terms are unfamiliar to you, @ref{Glossary, Emacs
|
|
|
4243 Glossary,, emacs, the GNU Emacs Manual}.
|
|
|
4244
|
|
|
4245 @table @code
|
|
|
4246
|
|
|
4247 @cindex action
|
|
|
4248 @item action
|
|
|
4249 An executable behavior associated with a Hyperbole button. A specific
|
|
|
4250 class of actions which display entities are called @emph{links},
|
|
|
4251 such as a link to a file.
|
|
|
4252
|
|
|
4253 @cindex Action Key
|
|
|
4254 @item Action Key
|
|
|
4255 See @emph{Smart Key}.
|
|
|
4256
|
|
|
4257 @cindex action type
|
|
|
4258 @item action type
|
|
|
4259 A behavioral specification for use within Hyperbole buttons. Action
|
|
|
4260 types usually contain a set of parameters which must be given values for
|
|
|
4261 each button with which they are associated. An action type together
|
|
|
4262 with a set of values, called arguments, may be considered an @emph{action}.
|
|
|
4263 @emph{Actype} is a synonym for action type.
|
|
|
4264
|
|
|
4265 @cindex activation
|
|
|
4266 @item activation
|
|
|
4267 Request for a Hyperbole button to perform its action.
|
|
|
4268 Ordinarily the user presses a key which selects and activates a button.
|
|
|
4269
|
|
|
4270 @cindex ange-ftp
|
|
|
4271 @cindex ftp
|
|
|
4272 @item ange-ftp
|
|
|
4273 A standard GNU Emacs Lisp package which allows one to use pathnames
|
|
|
4274 that are accessible via the Internet File Transfer Protocol (ftp) just
|
|
|
4275 like other pathnames, for example when finding a file. The
|
|
|
4276 latest version of ange-ftp may always be obtained via anonymous ftp to:
|
|
|
4277 @file{/ftp.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.gz}.
|
|
|
4278
|
|
|
4279 @cindex argument
|
|
|
4280 @item argument
|
|
|
4281 A button-specific value fed to a Hyperbole type specification when the
|
|
|
4282 button is activated.
|
|
|
4283
|
|
|
4284 @cindex Assist Key
|
|
|
4285 @item Assist Key
|
|
|
4286 See @emph{Smart Key}.
|
|
|
4287
|
|
|
4288 @cindex attributes
|
|
|
4289 @item attributes
|
|
|
4290 Slot names associated with Hyperbole buttons. An @emph{attribute value}
|
|
|
4291 is associated with each button attribute.
|
|
|
4292
|
|
|
4293 @cindex Augment
|
|
|
4294 @cindex NLS
|
|
|
4295 @cindex hypertext
|
|
|
4296 @cindex interactive computing
|
|
|
4297 @cindex mouse
|
|
|
4298 @cindex windows
|
|
|
4299 @cindex hypertext
|
|
|
4300 @cindex outline processor
|
|
|
4301 @cindex groupware
|
|
|
4302 @cindex digital signature
|
|
|
4303 @cindex Engelbart
|
|
|
4304 @item Augment
|
|
|
4305 The Augment system, originally named NLS, was a pioneering research and
|
|
|
4306 production system aimed at augmenting human intellect and group
|
|
|
4307 knowledge processing capabilities through integrated tools and
|
|
|
4308 organizational development strategies. This approach led to the
|
|
|
4309 invention of much of interactive computing technology decades ahead of
|
|
|
4310 other efforts, including: the mouse, screen windows, true hypertext,
|
|
|
4311 outline processors, groupware, and digitally signed documents.
|
|
|
4312 @xref{References}, which cites several Douglas Engelbart papers on the
|
|
|
4313 subject. The Koutliner concept emerged from studies of publicly
|
|
|
4314 available information concerning Augment.
|
|
|
4315
|
|
|
4316 @cindex button
|
|
|
4317 @item button
|
|
|
4318 A selectable Hyperbole construct which performs an action. A button
|
|
|
4319 consists of a set of attributes that includes: a textual label, a
|
|
|
4320 category, a type and zero or more arguments. @emph{Explicit buttons}
|
|
|
4321 also have creator, create time, last modifier, and last modifier time
|
|
|
4322 attributes.
|
|
|
4323
|
|
|
4324 Buttons provide the user's gateway to information. The user sees and
|
|
|
4325 interacts with button labels, the rest of the button data is managed
|
|
|
4326 invisibly by Hyperbole and displayed only in response to user queries.
|
|
|
4327
|
|
|
4328 @cindex button activation
|
|
|
4329 @item button activation
|
|
|
4330 See @emph{activation}.
|
|
|
4331
|
|
|
4332 @cindex button attributes
|
|
|
4333 @item button attributes
|
|
|
4334 See @emph{attributes}.
|
|
|
4335
|
|
|
4336 @cindex button data
|
|
|
4337 @item button data
|
|
|
4338 Lists of button attribute values explicitly saved and managed by Hyperbole.
|
|
|
4339 One list for each button created by Hyperbole.
|
|
|
4340
|
|
|
4341 @cindex button file, local
|
|
|
4342 @item button file, local
|
|
|
4343 A per-directory file named @file{HYPB} that may be used to store any
|
|
|
4344 desired buttons and may then be displayed via a menu selection whenever
|
|
|
4345 a user is within that directory.
|
|
|
4346
|
|
|
4347 @cindex button file, personal
|
|
|
4348 @item button file, personal
|
|
|
4349 A per-user file named @file{HYPB} that may be used to store any desired
|
|
|
4350 buttons and may then be displayed via a menu selection.
|
|
|
4351
|
|
|
4352 @cindex button key
|
|
|
4353 @item button key
|
|
|
4354 A normalized form of a @emph{button label} used internally by Hyperbole.
|
|
|
4355
|
|
|
4356 @cindex button label
|
|
|
4357 @item button label
|
|
|
4358 A text string that visually indicates a Hyperbole button location and
|
|
|
4359 provides it with a name and unique identifier. Within a buffer, buttons
|
|
|
4360 with the same label are considered separate views of the same button and
|
|
|
4361 so behave exactly alike. Since button labels are simply text strings,
|
|
|
4362 they may be embedded within any text to provide non-linear information
|
|
|
4363 or operational access points.
|
|
|
4364
|
|
|
4365 The maximum length of a button label is limited by the variable
|
|
|
4366 @var{ebut:max-len}.
|
|
|
4367
|
|
|
4368 @cindex button selection
|
|
|
4369 @item button selection
|
|
|
4370 The act of designating a Hyperbole button upon which to operate.
|
|
|
4371 Use the Action Key to select a button.
|
|
|
4372
|
|
|
4373 @cindex category
|
|
|
4374 @item category
|
|
|
4375 A high-level, conceptual grouping of Hyperbole buttons into classes.
|
|
|
4376 @emph{Implicit} and @emph{explicit} groupings represent categories.
|
|
|
4377
|
|
|
4378 @cindex cell
|
|
|
4379 @item cell
|
|
|
4380 See @emph{kcell}.
|
|
|
4381
|
|
|
4382 @cindex children
|
|
|
4383 @item children
|
|
|
4384 The set of koutline cells which share a common parent cell and are one
|
|
|
4385 level deeper than the parent.
|
|
|
4386
|
|
|
4387 @cindex class
|
|
|
4388 @item class
|
|
|
4389 A group of functions and variables with the same prefix in their names,
|
|
|
4390 used to provide an interface to an internal or external Hyperbole
|
|
|
4391 abstraction.
|
|
|
4392
|
|
|
4393 @cindex context
|
|
|
4394 @item context
|
|
|
4395 A programmatic or positional state recognized by Hyperbole.
|
|
|
4396 We speak of Smart Key and implicit button contexts. Both are typically
|
|
|
4397 defined in terms of surrounding patterns within a buffer, but may be
|
|
|
4398 defined by arbitrary Emacs Lisp predicates. (Context may come to have a
|
|
|
4399 broader meaning within future versions of Hyperbole.)
|
|
|
4400
|
|
|
4401 @cindex environment
|
|
|
4402 @item environment
|
|
|
4403 See @emph{Hyperbole environment}.
|
|
|
4404
|
|
|
4405 @cindex efs
|
|
|
4406 @item efs
|
|
|
4407 The much larger successor to ange-ftp. It does the same thing as
|
|
|
4408 ange-ftp but works with more types of ftp hosts. See @emph{ange-ftp}.
|
|
|
4409
|
|
|
4410 @cindex explicit button
|
|
|
4411 @item explicit button
|
|
|
4412 A button created and managed by Hyperbole. By default, explicit buttons
|
|
|
4413 are delimited like this @code{<(fake button)>}. Direct selection is
|
|
|
4414 used to operate upon an explicit button.
|
|
|
4415
|
|
|
4416 @cindex global button
|
|
|
4417 @item global button
|
|
|
4418 @vindex gbut:file
|
|
|
4419 A form of explicit button which is typically accessed by name rather
|
|
|
4420 than direct selection. Global buttons are useful when one wants
|
|
|
4421 quick access to actions such as jumping to common file locations or for
|
|
|
4422 performing sequences of operations. One need not locate them since they
|
|
|
4423 are always available by name, with full completion offered. All global
|
|
|
4424 buttons are stored in the file given by the variable @var{gbut:file} and
|
|
|
4425 may be activated as regular explicit buttons by visiting this file. By
|
|
|
4426 default, this is the same as the user's personal button file.
|
|
|
4427
|
|
|
4428 @cindex global button file
|
|
|
4429 @item global button file
|
|
|
4430 See @emph{button file, personal}.
|
|
|
4431
|
|
|
4432 @findex run-hooks
|
|
|
4433 @cindex hook variable
|
|
|
4434 @item hook variable
|
|
|
4435 A variable that permits customization of an existing function's
|
|
|
4436 operation without the need to edit the function's code. See also the
|
|
|
4437 documentation for the function @code{(run-hooks)}.
|
|
|
4438
|
|
|
4439 @cindex Hyperbole
|
|
|
4440 @item Hyperbole
|
|
|
4441 A flexible, programmable information management and viewing system built
|
|
|
4442 on top of GNU Emacs. It utilizes a button-action model and supports
|
|
|
4443 hypertextual linkages. Hyperbole is all things to all people.
|
|
|
4444
|
|
|
4445 @cindex Hyperbole environment
|
|
|
4446 @item Hyperbole environment
|
|
|
4447 A programmatic context within which Hyperbole operates. This includes
|
|
|
4448 the set of Hyperbole types defined and the set of Hyperbole code modules
|
|
|
4449 loaded. It does not include the set of accessible buttons.
|
|
|
4450 Although the entire Emacs environment is available to Hyperbole, we do
|
|
|
4451 not speak of this as part of the Hyperbole environment.
|
|
|
4452
|
|
|
4453 @cindex hypertext
|
|
|
4454 @item hypertext
|
|
|
4455 A text or group of texts which may be explored in a non-linear fashion
|
|
|
4456 through associative linkages embedded throughout the text. Instead of
|
|
|
4457 simply referring to other pieces of work, hypertext references when
|
|
|
4458 followed actually take you to the works themselves.
|
|
|
4459
|
|
|
4460 @cindex implicit button
|
|
|
4461 @item implicit button
|
|
|
4462 A button recognized contextually by Hyperbole. Such buttons contain no
|
|
|
4463 button data. See also @emph{implicit button type}.
|
|
|
4464
|
|
|
4465 @cindex implicit button type
|
|
|
4466 @item implicit button type
|
|
|
4467 A specification of how to recognize and activate implicit buttons of a
|
|
|
4468 specific kind. Implicit button types often utilize structure internal
|
|
|
4469 to documents created and managed without Hyperbole assistance, for
|
|
|
4470 example, programming documentation. @emph{Ibtype} is a synonym for
|
|
|
4471 implicit button type. See also @emph{system encapsulation}.
|
|
|
4472
|
|
|
4473 @cindex instance number
|
|
|
4474 @item instance number
|
|
|
4475 A colon prefaced number appended to the label of a newly created button
|
|
|
4476 when the button's label duplicates the label of an existing button in
|
|
|
4477 the current buffer. This number makes the label unique and so allows
|
|
|
4478 any number of buttons with the same base label within a single buffer.
|
|
|
4479
|
|
|
4480 @cindex koutline
|
|
|
4481 @item koutline
|
|
|
4482 A hierarchically ordered grouping of cells which may be stored as a file
|
|
|
4483 and viewed and edited as an outline.
|
|
|
4484
|
|
|
4485 @cindex Koutliner
|
|
|
4486 @item Koutliner
|
|
|
4487 Koutliner, the Hyperbole outliner, is a powerful autonumbering outliner
|
|
|
4488 with permanent hypertext anchors for easy hyperlinking and view
|
|
|
4489 specs for rapid outline view alteration.
|
|
|
4490
|
|
|
4491 @cindex kcell
|
|
|
4492 @item kcell
|
|
|
4493 Cells or kcells are elements within koutlines. Each cell contains
|
|
|
4494 textual and graphical contents, a relative identifier, a permanent
|
|
|
4495 identifier and a set of attributes such as the user who created the cell
|
|
|
4496 and the time of creation. See also @emph{Koutliner}.
|
|
|
4497
|
|
|
4498 @cindex link
|
|
|
4499 @item link
|
|
|
4500 A reference from a Hyperbole button to an entity. The referenced entity
|
|
|
4501 is sometimes called a @emph{node} or @emph{referent}.
|
|
|
4502 A specific class of actions which display entities are called
|
|
|
4503 @emph{links}, such as a link to a file.
|
|
|
4504
|
|
|
4505 @cindex local button file
|
|
|
4506 @item local button file
|
|
|
4507 See @emph{button file, local}.
|
|
|
4508
|
|
|
4509 @cindex minibuffer window
|
|
|
4510 @item minibuffer window
|
|
|
4511 The one line window at the bottom of a frame where messages and prompts
|
|
|
4512 are displayed.
|
|
|
4513
|
|
|
4514 @cindex minibuffer menu
|
|
|
4515 @item minibuffer menu
|
|
|
4516 A Hyperbole menu displayed in the minibuffer window. Each menu item
|
|
|
4517 within a minibuffer menu begins with a different letter that can be used
|
|
|
4518 to invoke the item (case doesn't matter). Items that display other
|
|
|
4519 menus end with a forward slash, /.
|
|
|
4520
|
|
|
4521 @cindex mouse button
|
|
|
4522 @item mouse button
|
|
|
4523 @item mouse key
|
|
|
4524 See @emph{Smart Key}.
|
|
|
4525
|
|
|
4526 @cindex node
|
|
|
4527 @item node
|
|
|
4528 See @emph{link} or @emph{cell}.
|
|
|
4529
|
|
|
4530 @cindex outline
|
|
|
4531 @item outline
|
|
|
4532 See @emph{koutline}.
|
|
|
4533
|
|
|
4534 @cindex parent
|
|
|
4535 @item parent
|
|
|
4536 Any koutline cell which has children.
|
|
|
4537
|
|
|
4538 @cindex predecessor
|
|
|
4539 @item predecessor
|
|
|
4540 The previous same level koutline cell with the same parent.
|
|
|
4541
|
|
|
4542 @cindex predicate
|
|
|
4543 @item predicate
|
|
|
4544 A boolean (nil = false, non-nil = true) Lisp expression typically
|
|
|
4545 evaluated as part of a conditional expression.
|
|
|
4546
|
|
|
4547 @cindex referent
|
|
|
4548 @item referent
|
|
|
4549 See @emph{link}.
|
|
|
4550
|
|
|
4551 @cindex rolodex
|
|
|
4552 @item rolodex
|
|
|
4553 Wrolo, the Hyperbole rolodex, provides rapid lookup of multi-line,
|
|
|
4554 hierarchically ordered free form text records.
|
|
|
4555
|
|
|
4556 @cindex root cell
|
|
|
4557 @item root cell
|
|
|
4558 A koutline cell which has cells below it. All such cells share the same
|
|
|
4559 root cell.
|
|
|
4560
|
|
|
4561 @cindex Smart Key
|
|
|
4562 @vindex smart-scroll-proportional
|
|
|
4563 @cindex proportional scrolling
|
|
|
4564 @cindex scrolling
|
|
|
4565 @item Smart Key
|
|
|
4566 A context-sensitive key used within Hyperbole and beyond. Actually,
|
|
|
4567 there are two Smart Keys, the Action Key and the Assist Key. The
|
|
|
4568 Action Key, typically bound to the shift-middle mouse key (or shift-left
|
|
|
4569 mouse key on a 2-button mouse), activates Hyperbole buttons and scrolls
|
|
|
4570 the current buffer line to the top of the window when pressed at the end
|
|
|
4571 of a line. The Assist Key, typically bound to the shift-right mouse
|
|
|
4572 key, explains what a Hyperbole button does or scrolls the current line
|
|
|
4573 to the bottom of the window when pressed at the end of a line. (See the
|
|
|
4574 documentation for the variable, @var{smart-scroll-proportional}, for
|
|
|
4575 information on how to make these keys scroll forward and backward a
|
|
|
4576 windowful at a time).
|
|
|
4577
|
|
|
4578 To see what a Smart Key will do within a particular context, depress and
|
|
|
4579 hold the key at the point desired and depress the other Smart Key. A
|
|
|
4580 buffer containing a description of its contextual function will then be
|
|
|
4581 displayed. You may release the two keys in any order after you have
|
|
|
4582 them both depressed. A press of the Assist Key in an unsupported
|
|
|
4583 context displays a summary of Smart Key functions in each context, as
|
|
|
4584 does the Doc/SmartKy menu item.
|
|
|
4585
|
|
|
4586 @cindex source buffer
|
|
|
4587 @cindex source file
|
|
|
4588 @item source buffer / file
|
|
|
4589 The buffer or file within which a Hyperbole button is embedded.
|
|
|
4590
|
|
|
4591 @cindex subtree
|
|
|
4592 @item subtree
|
|
|
4593 All of the cells in a koutline which share the same root cell, excluding
|
|
|
4594 the root cell.
|
|
|
4595
|
|
|
4596 @cindex successor
|
|
|
4597 @item successor
|
|
|
4598 The next same level koutline cell with the same parent.
|
|
|
4599
|
|
|
4600 @cindex system encapsulation
|
|
|
4601 @item system encapsulation
|
|
|
4602 Use of Hyperbole to provide an improved or simply consistent user
|
|
|
4603 interface to another system. Typically, implicit button types are
|
|
|
4604 defined to recognize and activate button-type constructs managed by the
|
|
|
4605 other system.
|
|
|
4606
|
|
|
4607 @cindex tree
|
|
|
4608 @item tree
|
|
|
4609 The set of cells in a koutline that share a common root cell, including
|
|
|
4610 the root cell.
|
|
|
4611
|
|
|
4612 @cindex view
|
|
|
4613 @item view
|
|
|
4614 A perspective on some information. A view can affect the extent of the
|
|
|
4615 information displayed, its format, modes used to operate on it, its
|
|
|
4616 display location and so forth.
|
|
|
4617
|
|
|
4618 @cindex view spec
|
|
|
4619 @item view spec
|
|
|
4620 A terse (and to the uninitiated, cryptic) string that specifies a
|
|
|
4621 particular view of koutline or a link referent. If a view spec is in
|
|
|
4622 use in a buffer, the view spec appears in the modeline delimited by
|
|
|
4623 <|view spec>.
|
|
|
4624
|
|
|
4625 @end table
|
|
|
4626
|
|
|
4627 @node Smart Key Reference, Outliner Keys, Glossary, Top
|
|
|
4628 @appendix Smart Key Reference
|
|
|
4629
|
|
|
4630 This appendix supplies complete documentation on Smart Key operation. It is
|
|
|
4631 quite extensive and is meant for reference rather than sequential reading.
|
|
|
4632 @xref{Smart Keys}, for a description of the Smart Keys. That section also
|
|
|
4633 describes how to get context-sensitive Smart Key help, with which you can
|
|
|
4634 explore Smart Key operation bit by bit.
|
|
|
4635
|
|
|
4636 Smart Key operations are context-sensitive. Contexts are described herein as
|
|
|
4637 conditionals, e.g@. when depressed here, if this is true, etc. Each Smart
|
|
|
4638 Key context is listed in the order in which it will be checked. The first
|
|
|
4639 matching context is always the one applied. Within each context, the
|
|
|
4640 actions performed by the Action and Assist Keys are listed.
|
|
|
4641
|
|
|
4642 @menu
|
|
|
4643 * Smart Mouse Keys::
|
|
|
4644 * Smart Keyboard Keys::
|
|
|
4645 @end menu
|
|
|
4646
|
|
|
4647 @node Smart Mouse Keys, Smart Keyboard Keys, Smart Key Reference, Smart Key Reference
|
|
|
4648 @section Smart Mouse Keys
|
|
|
4649
|
|
|
4650 @cindex Smart Mouse Keys
|
|
|
4651 Smart Key drags and modeline presses can only be used when running under
|
|
|
4652 a window system with mouse key support. So keep in mind that the
|
|
|
4653 operations in this section apply only if you have mouse support within
|
|
|
4654 Hyperbole. The Smart Key operations in, @ref{Smart Keyboard Keys},
|
|
|
4655 apply to both mouse and keyboard Smart Key usage.
|
|
|
4656
|
|
10
|
4657 @cindex drag, side edge
|
|
|
4658 @cindex side drag
|
|
0
|
4659 @format
|
|
|
4660 @group
|
|
|
4661 If dragged from a side-by-side window edge or from the immediate left of
|
|
|
4662 a vertical scroll bar:
|
|
|
4663 ACTION or ASSIST
|
|
|
4664 Resizes adjacent window sides to the point of drag release.
|
|
|
4665 @end group
|
|
|
4666 @end format
|
|
|
4667
|
|
|
4668 @format
|
|
|
4669 @group
|
|
24
|
4670 @cindex drag, between windows
|
|
0
|
4671 If dragged from inside one window to another:
|
|
|
4672 ACTION
|
|
|
4673 Creates a new link button at the drag start location, linked to the
|
|
|
4674 drag end location. If drag start position is within a button,
|
|
|
4675 modifies the button to link to drag end location.
|
|
|
4676 ASSIST
|
|
|
4677 Swaps buffers in the two windows.
|
|
|
4678 @end group
|
|
|
4679 @end format
|
|
|
4680
|
|
|
4681 @page
|
|
10
|
4682 @cindex drag, horizontal
|
|
|
4683 @cindex horizontal drag
|
|
0
|
4684 @format
|
|
|
4685 @group
|
|
|
4686 If dragged horizontally within a single window while depressed
|
|
|
4687 (hmouse-x-drag-sensitivity sets the minimal horizontal movement which
|
|
|
4688 registers a drag):
|
|
|
4689 ACTION
|
|
|
4690 Goes to buffer end if drag was to the right, otherwise goes to beginning.
|
|
|
4691 ASSIST
|
|
|
4692 Splits window vertically if drag was to the right, otherwise deletes
|
|
|
4693 window.
|
|
|
4694 @end group
|
|
|
4695 @end format
|
|
|
4696
|
|
10
|
4697 @cindex depress, modeline
|
|
|
4698 @cindex modeline depress
|
|
0
|
4699 @format
|
|
|
4700 @group
|
|
|
4701 If depressed within a window mode line:
|
|
|
4702 ACTION
|
|
|
4703 (1) clicked on left edge of a window's modeline,
|
|
|
4704 window's buffer is buried (placed at bottom of buffer list);
|
|
|
4705 (2) clicked on right edge of a window's modeline,
|
|
|
4706 the Info buffer is displayed, or if already displayed and the
|
|
|
4707 modeline clicked belongs to a window displaying Info, the Info
|
|
|
4708 buffer is hidden;
|
|
|
4709 (3) clicked anywhere in the middle of a window's modeline,
|
|
24
|
4710 the functions listed in `assist-key-modeline-hook' are
|
|
0
|
4711 called;
|
|
|
4712 (4) dragged vertically from modeline to within a window,
|
|
|
4713 the modeline is moved to point of key release, thereby resizing
|
|
|
4714 its window and potentially its vertical neighbors.
|
|
|
4715 ASSIST
|
|
|
4716 (1) clicked on left edge of a window's modeline,
|
|
|
4717 bottom buffer in buffer list is unburied and placed in window;
|
|
|
4718 (2) clicked on right edge of a window's modeline,
|
|
|
4719 the summary of Smart Key behavior is displayed, or if already
|
|
|
4720 displayed and the modeline clicked belongs to a window displaying
|
|
|
4721 the summary, the summary buffer is hidden;
|
|
|
4722 (3) clicked anywhere in the middle of a window's modeline,
|
|
|
4723 a popup menu (if available) is displayed;
|
|
|
4724 (4) dragged vertically from modeline to within a window,
|
|
|
4725 the modeline is moved to point of key release, thereby resizing
|
|
|
4726 its window and potentially its vertical neighbors.
|
|
|
4727 @end group
|
|
|
4728 @end format
|
|
|
4729
|
|
|
4730 @page
|
|
10
|
4731 @cindex drag, vertical
|
|
|
4732 @cindex vertical drag
|
|
0
|
4733 @format
|
|
|
4734 @group
|
|
|
4735 If dragged vertically within a single window while depressed
|
|
|
4736 (hmouse-y-drag-sensitivity sets the minimal vertical movement which
|
|
|
4737 registers a drag):
|
|
|
4738 ACTION or ASSIST
|
|
|
4739 Splits current window into two side-by-side windows.
|
|
|
4740 @end group
|
|
|
4741 @end format
|
|
|
4742
|
|
10
|
4743 @cindex drag, diagonal
|
|
|
4744 @cindex diagonal drag
|
|
0
|
4745 @format
|
|
|
4746 @group
|
|
|
4747 If dragged diagonally within a single window while depressed
|
|
|
4748 (hmouse-x-diagonal-sensitivity and hmouse-y-diagonal-sensitivity set the
|
|
|
4749 minimal diagonal movement which registers a drag):
|
|
|
4750 ACTION
|
|
|
4751 Save current window configuration onto a ring of window configurations.
|
|
|
4752 ASSIST
|
|
|
4753 Restores prior window configuration from ring. A prefix argument N
|
|
|
4754 specifies the Nth prior configuration from the ring.
|
|
|
4755 @end group
|
|
|
4756 @end format
|
|
|
4757
|
|
|
4758 @page
|
|
|
4759
|
|
|
4760 @node Smart Keyboard Keys, , Smart Mouse Keys, Smart Key Reference
|
|
|
4761 @section Smart Keyboard Keys
|
|
|
4762
|
|
|
4763 @cindex Smart Keyboard Keys
|
|
|
4764 @format
|
|
|
4765 @group
|
|
|
4766 When prompting for a Hyperbole argument, a press in the minibuffer:
|
|
|
4767 ACTION
|
|
|
4768 Terminates this minibuffer argument.
|
|
|
4769 ASSIST
|
|
|
4770 Offers completion help for current minibuffer argument.
|
|
|
4771 @end group
|
|
|
4772 @end format
|
|
|
4773
|
|
|
4774 @format
|
|
|
4775 @group
|
|
|
4776 When reading a Hyperbole menu item or a Hyperbole completion-based argument:
|
|
|
4777 ACTION
|
|
|
4778 Returns value selected at point if any, else nil. If
|
|
|
4779 value is the same as the contents of the minibuffer, it is used as the
|
|
|
4780 current minibuffer argument, otherwise, the minibuffer is erased and
|
|
|
4781 value is inserted there.
|
|
|
4782
|
|
|
4783 ASSIST
|
|
|
4784 Displays Hyperbole menu item help when item is selected.
|
|
|
4785 @end group
|
|
|
4786 @end format
|
|
|
4787
|
|
24
|
4788 @format
|
|
|
4789 @group
|
|
|
4790 If in ID-edit mode (a package from InfoDock Associates that supports
|
|
|
4791 rapid killing, copying, ynaking and display-management):
|
|
|
4792 ACTION or ASSIST
|
|
|
4793 Yanks (pastes) last selected region at point.
|
|
|
4794 @end group
|
|
|
4795 @end format
|
|
|
4796
|
|
0
|
4797 @vindex smart-scroll-proportional
|
|
|
4798 @cindex proportional scrolling
|
|
|
4799 @cindex scrolling
|
|
10
|
4800 @cindex click, end of line
|
|
|
4801 @cindex end of line click
|
|
0
|
4802 @format
|
|
|
4803 @group
|
|
|
4804 When pressed at the end of a line but not the end of a buffer:
|
|
|
4805 ACTION
|
|
|
4806 Scrolls up according to value of smart-scroll-proportional. If
|
|
|
4807 smart-scroll-proportional is nil or if point is on the top
|
|
|
4808 window line, scrolls up (forward) a windowful. Otherwise, tries to
|
|
|
4809 bring current line to top of window. Leaves point at end of line and
|
|
|
4810 returns t if scrolled, nil if not.
|
|
|
4811 ASSIST
|
|
|
4812 Scrolls down according to value of smart-scroll-proportional. If
|
|
|
4813 smart-scroll-proportional is nil or if point is on the
|
|
|
4814 bottom window line, scrolls down (backward) a windowful. Otherwise,
|
|
|
4815 tries to bring current line to bottom of window. Leaves point at end of
|
|
|
4816 line and returns t if scrolled, nil if not.
|
|
|
4817 @end group
|
|
|
4818 @end format
|
|
|
4819
|
|
24
|
4820 @format
|
|
|
4821 @group
|
|
|
4822 When pressed on a Smart Menu item:
|
|
|
4823 ACTION
|
|
|
4824 Activates item.
|
|
|
4825 ASSIST
|
|
|
4826 Displays help for item.
|
|
|
4827 @end group
|
|
|
4828 @end format
|
|
|
4829
|
|
10
|
4830 @cindex click, button
|
|
|
4831 @cindex button click
|
|
0
|
4832 @format
|
|
|
4833 @group
|
|
|
4834 When pressed on a Hyperbole button:
|
|
|
4835 ACTION
|
|
|
4836 Activates button.
|
|
|
4837 ASSIST
|
|
|
4838 Displays help for button, typically a summary of its attributes.
|
|
|
4839 @end group
|
|
|
4840 @end format
|
|
|
4841
|
|
|
4842 @format
|
|
|
4843 @group
|
|
24
|
4844 If Smart Menu package has been loaded and `hkey-always-display-menu' is
|
|
|
4845 non-nil:
|
|
|
4846 ACTION or ASSIST
|
|
|
4847 Pops up a window with a Smart Menu of commands.
|
|
|
4848 Menu displayed is selected by (smart-menu-choose-menu).
|
|
|
4849 @end group
|
|
|
4850 @end format
|
|
|
4851
|
|
|
4852 @format
|
|
|
4853 @group
|
|
0
|
4854 If pressed within a buffer in View major or minor mode:
|
|
|
4855 ACTION
|
|
|
4856 Scrolls buffer forward a windowful and quits from view mode when at
|
|
|
4857 the last line of the buffer.
|
|
|
4858 ASSIST
|
|
|
4859 Scrolls buffer backward a windowful.
|
|
|
4860 @end group
|
|
|
4861 @end format
|
|
|
4862
|
|
|
4863 @format
|
|
|
4864 @group
|
|
|
4865 When pressed within a Hyperbole outliner buffer (kotl-mode):
|
|
|
4866 ACTION
|
|
|
4867 (1) at the end of buffer, uncollapse and unhide all cells in view;
|
|
|
4868 (2) within a cell, if its subtree is hidden then show it,
|
|
|
4869 otherwise hide it;
|
|
|
4870 (3) between cells or within the read-only indentation region to the
|
|
|
4871 left of a cell, then move point to prior location and begin
|
|
|
4872 creation of a klink to some other outline cell; hit the Action
|
|
|
4873 Key twice to select the link referent cell;
|
|
|
4874 (4) anywhere else, scroll up a windowful.
|
|
|
4875 ASSIST
|
|
|
4876 (1) at the end of buffer, collapse all cells and hide all non-level-one
|
|
|
4877 cells;
|
|
|
4878 (2) on a header line but not at the beginning or end, display
|
|
|
4879 properties of each cell in kotl beginning at point;
|
|
|
4880 (3) between cells or within the read-only indentation region to the
|
|
|
4881 left of a cell, then move point to prior location and prompt to
|
|
|
4882 move one tree to a new location in the outline; hit the Action
|
|
|
4883 Key twice to select the tree to move and where to move it;
|
|
|
4884 (4) anywhere else, scroll down a windowful.
|
|
|
4885 @end group
|
|
|
4886 @end format
|
|
|
4887
|
|
|
4888 @page
|
|
|
4889 @format
|
|
|
4890 @group
|
|
|
4891 When pressed at the end of a Help buffer:
|
|
|
4892 ACTION or ASSIST
|
|
|
4893 Restores window configuration prior to help display.
|
|
|
4894 @end group
|
|
|
4895 @end format
|
|
|
4896
|
|
|
4897 @format
|
|
|
4898 @group
|
|
|
4899 When pressed within a C source code file:
|
|
|
4900 ACTION
|
|
|
4901 Jumps to the definition of selected C construct:
|
|
24
|
4902 (1) on a `#include' statement, the include file is displayed;
|
|
0
|
4903 Look for include file in directory lists
|
|
24
|
4904 `smart-c-cpp-include-dirs' and `smart-c-include-dirs'.
|
|
0
|
4905 (2) on a C identifier, the identifier definition is displayed,
|
|
24
|
4906 assuming the identifier is found within an `etags' generated tag file
|
|
0
|
4907 in the current directory or any of its ancestor directories.
|
|
24
|
4908 (3) if `smart-c-use-lib-man' is non-nil, the C identifier is
|
|
0
|
4909 recognized as a library symbol, and a man page is found for the
|
|
|
4910 identifier, then the man page is displayed.
|
|
|
4911 ASSIST
|
|
|
4912 Jumps to the next tag matching an identifier at point.
|
|
|
4913 @end group
|
|
|
4914 @end format
|
|
|
4915
|
|
|
4916 @format
|
|
|
4917 @group
|
|
|
4918 When pressed within an assembly source code file:
|
|
|
4919 ACTION
|
|
|
4920 Jumps to the definition of selected assembly construct:
|
|
|
4921 (1) on an include statement, the include file is displayed;
|
|
|
4922 Look for include file in directory list
|
|
24
|
4923 `smart-asm-include-dirs'.
|
|
0
|
4924 (2) on an identifier, the identifier definition is displayed,
|
|
24
|
4925 assuming the identifier is found within an `etags' generated
|
|
0
|
4926 tag file in the current directory or any of its ancestor
|
|
|
4927 directories.
|
|
|
4928 ASSIST
|
|
|
4929 Jumps to the next tag matching an identifier at point.
|
|
|
4930 @end group
|
|
|
4931 @end format
|
|
|
4932
|
|
|
4933 @page
|
|
|
4934 @format
|
|
|
4935 @group
|
|
|
4936 When pressed on a Lisp symbol within a Lisp code buffer:
|
|
|
4937 ACTION
|
|
|
4938 Jumps to the definition of any selected Lisp construct.
|
|
24
|
4939 If on an Emacs Lisp require, load, or autoload clause and `find-library'
|
|
0
|
4940 from load-library package by Hallvard Furuseth <hallvard@@ifi.uio.no> has
|
|
|
4941 been loaded, jumps to library source, if possible.
|
|
|
4942 ASSIST
|
|
|
4943 Jumps to the next tag matching an identifier at point or if using the
|
|
|
4944 "wtags" package and identifier is an Emacs Lisp symbol, then displays
|
|
|
4945 documentation for the symbol.
|
|
|
4946 @end group
|
|
|
4947 @end format
|
|
|
4948
|
|
24
|
4949 @page
|
|
|
4950 @format
|
|
|
4951 @group
|
|
|
4952 When pressed within a Java source code file:
|
|
|
4953 ACTION
|
|
|
4954 Jumps to the definition of selected Java construct:
|
|
|
4955 (1) within a commented @@see cross-reference, the referent is
|
|
|
4956 displayed;
|
|
|
4957 (2) on a `package' or `import' statement, the referent is
|
|
|
4958 displayed; Look for referent files in the directory list
|
|
|
4959 `smart-java-package-dirs'.
|
|
|
4960 (3) on an Java identifier, the identifier definition is displayed,
|
|
|
4961 assuming the identifier is found within an `etags' generated
|
|
|
4962 tag file in the current directory or any of its ancestor
|
|
|
4963 directories."
|
|
|
4964 ASSIST
|
|
|
4965 Jumps to the next tag matching an identifier at point.
|
|
|
4966 @end group
|
|
|
4967 @end format
|
|
|
4968
|
|
|
4969 @format
|
|
|
4970 @group
|
|
|
4971 When pressed within a C++ source code file:
|
|
|
4972 ACTION
|
|
|
4973 Jumps to the definition of selected C++ construct:
|
|
|
4974 (1) on a `#include' statement, the include file is displayed;
|
|
|
4975 Look for include file in directory lists
|
|
|
4976 `smart-c-cpp-include-dirs' and `smart-c-include-dirs'.
|
|
|
4977 (2) on a C++ identifier, the identifier definition is displayed,
|
|
|
4978 assuming the identifier is found within an `etags' generated tag file
|
|
|
4979 in the current directory or any of its ancestor directories.
|
|
|
4980 (3) if `smart-c-use-lib-man' is non-nil, the C++ identifier is
|
|
|
4981 recognized as a library symbol, and a man page is found for the
|
|
|
4982 identifier, then the man page is displayed.
|
|
|
4983 ASSIST
|
|
|
4984 Jumps to the next tag matching an identifier at point.
|
|
|
4985 @end group
|
|
|
4986 @end format
|
|
|
4987
|
|
0
|
4988 @format
|
|
|
4989 @group
|
|
|
4990 When the OO-Browser has been loaded and the press is within a C++ buffer:
|
|
|
4991 ACTION or ASSIST
|
|
|
4992 Jumps to the definition of selected C++ construct via OO-Browser support.
|
|
24
|
4993 (1) on a `#include' statement, the include file is displayed;
|
|
0
|
4994 Look for include file in directory lists
|
|
24
|
4995 `smart-c-cpp-include-dirs' and `smart-c-include-dirs'.
|
|
0
|
4996 (2) within a method declaration, its definition is displayed;
|
|
|
4997 (3) on a class name, the class definition is shown.
|
|
|
4998 @end group
|
|
|
4999 @end format
|
|
|
5000
|
|
|
5001 @format
|
|
|
5002 @group
|
|
24
|
5003 When pressed within a Objective-C source code file:
|
|
|
5004 ACTION
|
|
|
5005 Jumps to the definition of selected C+ construct:
|
|
|
5006 (1) on a `#include' statement, the include file is displayed;
|
|
|
5007 Look for include file in directory lists
|
|
|
5008 `smart-c-cpp-include-dirs' and `smart-c-include-dirs'.
|
|
|
5009 (2) on an Objective-C identifier, the identifier definition is displayed,
|
|
|
5010 assuming the identifier is found within an `etags' generated tag file
|
|
|
5011 in the current directory or any of its ancestor directories.
|
|
|
5012 (3) if `smart-c-use-lib-man' is non-nil, the Objective-C identifier is
|
|
|
5013 recognized as a library symbol, and a man page is found for the
|
|
|
5014 identifier, then the man page is displayed.
|
|
|
5015 ASSIST
|
|
|
5016 Jumps to the next tag matching an identifier at point.
|
|
|
5017 @end group
|
|
|
5018 @end format
|
|
|
5019
|
|
|
5020 @format
|
|
|
5021 @group
|
|
0
|
5022 When the OO-Browser has been loaded and the press is within a
|
|
|
5023 Objective-C buffer:
|
|
|
5024 ACTION or ASSIST
|
|
|
5025 Jumps to the definition of selected Objective-C construct via
|
|
|
5026 OO-Browser support.
|
|
24
|
5027 (1) on a `#include' statement, the include file is displayed;
|
|
0
|
5028 Look for include file in directory lists
|
|
24
|
5029 `smart-c-cpp-include-dirs' and `smart-c-include-dirs'.
|
|
0
|
5030 (2) within a method declaration, its definition is displayed;
|
|
|
5031 (3) on a class name, the class definition is shown.
|
|
|
5032 @end group
|
|
|
5033 @end format
|
|
|
5034
|
|
|
5035 @format
|
|
|
5036 @group
|
|
24
|
5037 When pressed within a Fortran source code file:
|
|
|
5038 ACTION or ASSIST
|
|
|
5039 Jumps to the next tag matching an identifier at point.
|
|
|
5040 @end group
|
|
|
5041 @end format
|
|
|
5042
|
|
|
5043 @format
|
|
|
5044 @group
|
|
0
|
5045 When pressed within an occur-mode or moccur-mode buffer:
|
|
|
5046 ACTION or ASSIST
|
|
|
5047 Jumps to the source buffer and line of the current occurrence.
|
|
|
5048 @end group
|
|
|
5049 @end format
|
|
|
5050
|
|
|
5051 @page
|
|
|
5052 @format
|
|
|
5053 @group
|
|
|
5054 When pressed within a calendar-mode buffer:
|
|
|
5055 ACTION
|
|
|
5056 (1) at the end of the buffer, the calendar is scrolled forward 3 months;
|
|
|
5057 (2) to the left of any dates on a calendar line, the calendar is scrolled
|
|
|
5058 backward 3 months;
|
|
|
5059 (3) on a date, the diary entries for the date, if any, are displayed.
|
|
|
5060 ASSIST
|
|
|
5061 (1) at the end of the buffer, the calendar is scrolled backward 3 months;
|
|
|
5062 (2) to the left of any dates on a calendar line, the calendar is scrolled
|
|
|
5063 forward 3 months;
|
|
|
5064 (3) anywhere else, all dates with marking diary entries are marked in the
|
|
|
5065 calendar window.
|
|
|
5066 @end group
|
|
|
5067 @end format
|
|
|
5068
|
|
|
5069 @format
|
|
|
5070 @group
|
|
|
5071 When pressed within a man page apropos buffer:
|
|
|
5072 ACTION
|
|
|
5073 (1) on a UNIX man apropos entry, the man page for that entry is
|
|
|
5074 displayed in another window;
|
|
|
5075 (2) on or after the last line, the buffer in the other window is
|
|
|
5076 scrolled up a windowful.
|
|
|
5077 ASSIST
|
|
|
5078 (1) on a UNIX man apropos entry, the man page for that entry is
|
|
|
5079 displayed in another window;
|
|
|
5080 (2) on or after the last line, the buffer in the other window is
|
|
|
5081 scrolled down a windowful.
|
|
|
5082 @end group
|
|
|
5083 @end format
|
|
|
5084
|
|
24
|
5085 @page
|
|
0
|
5086 @format
|
|
|
5087 @group
|
|
24
|
5088 When pressed within an OO-Browser listing window:
|
|
|
5089 ACTION
|
|
|
5090 (1) in a blank buffer or at the end of a buffer, browser help
|
|
|
5091 information is displayed in the viewer window;
|
|
|
5092 (2) at the beginning of a (non-single char) class name, the class'
|
|
|
5093 ancestors are listed;
|
|
|
5094 (3) at the end of an entry line, scrolls listing up;
|
|
|
5095 (4) on the `...', following a class name, point is moved to the class
|
|
|
5096 descendency expansion;
|
|
|
5097 (5) before an element name, the implementor classes of the name are
|
|
|
5098 listed;
|
|
|
5099 (6) anywhere else on an entry line, the source is displayed for editing.
|
|
|
5100 ASSIST
|
|
|
5101 (1) in a blank buffer, a selection list of buffer files is displayed;
|
|
|
5102 (2) at the beginning of a (non-single char) entry, the class'
|
|
|
5103 descendants are listed;
|
|
|
5104 (3) at the end of an entry line, scrolls listing down;
|
|
|
5105 (4) on the `...', following a class name, point is moved to the class
|
|
|
5106 expansion;
|
|
|
5107 (5) anywhere else on a class entry line, lists the class' elements;
|
|
|
5108 (6) anywhere else on an element line, lists the element's implementor
|
|
|
5109 classes;
|
|
|
5110 (7) on a blank line following all entries, the current listing buffer
|
|
|
5111 is exited.
|
|
|
5112 @end group
|
|
|
5113 @end format
|
|
|
5114
|
|
|
5115 @format
|
|
|
5116 @group
|
|
|
5117 When pressed within an OO-Browser Command Help Menu buffer:
|
|
|
5118 ACTION
|
|
|
5119 Executes an OO-Browser command whose key binding is at point.
|
|
|
5120 ASSIST
|
|
|
5121 Displays help for an OO-Browser command whose key binding is at point.
|
|
|
5122 @end group
|
|
|
5123 @end format
|
|
|
5124
|
|
|
5125 @format
|
|
|
5126 @group
|
|
|
5127 When pressed on an identifier within an OO-Browser source file:
|
|
|
5128 ACTION
|
|
|
5129 Tries to display identifier definition.
|
|
|
5130 ASSIST
|
|
|
5131 Not applicable.
|
|
0
|
5132 @end group
|
|
|
5133 @end format
|
|
|
5134
|
|
|
5135 @page
|
|
|
5136 @format
|
|
|
5137 @group
|
|
24
|
5138 If pressed within an outline-mode buffer or when `selective-display' is
|
|
0
|
5139 non-nil:
|
|
|
5140 ACTION
|
|
|
5141 Collapses, expands, and moves outline entries.
|
|
|
5142 (1) after an outline heading has been cut via the Action Key, then paste
|
|
|
5143 the cut heading at point;
|
|
|
5144 (2) at the end of buffer, show all buffer text
|
|
|
5145 (3) at the beginning of a heading line, cut the headings subtree from the
|
|
|
5146 buffer;
|
|
|
5147 (4) on a header line but not at the beginning or end, if headings
|
|
|
5148 subtree is hidden then show it, otherwise hide it;
|
|
|
5149 (5) anywhere else, scroll up a windowful.
|
|
|
5150 ASSIST
|
|
|
5151 (1) after an outline heading has been cut via the Action Key, allow
|
|
|
5152 multiple pastes throughout the buffer (last paste should be done
|
|
|
5153 with the Action Key, not the Assist Key);
|
|
|
5154 (2) at the end of buffer, hide all bodies in buffer;
|
|
|
5155 (3) at the beginning of a heading line, cut the current heading (sans
|
|
|
5156 subtree) from the buffer;
|
|
|
5157 (4) on a header line but not at the beginning or end, if heading body is
|
|
|
5158 hidden then show it, otherwise hide it;
|
|
|
5159 (5) anywhere else, scroll down a windowful.
|
|
|
5160 @end group
|
|
|
5161 @end format
|
|
|
5162
|
|
10
|
5163 @cindex click, Info
|
|
|
5164 @cindex Info browsing
|
|
0
|
5165 @format
|
|
|
5166 @group
|
|
|
5167 If pressed within an Info manual node:
|
|
|
5168 ACTION
|
|
|
5169 (1) the first line of an Info Menu Entry or Cross Reference, the desired
|
|
|
5170 node is found;
|
|
|
5171 (2) the Up,Next,or Previous entries of a Node Header (first line),
|
|
|
5172 the desired node is found;
|
|
|
5173 (3) the File entry of a Node Header (first line),
|
|
24
|
5174 the `Top' node within that file is found;
|
|
0
|
5175 (4) at the end of the current node, the Next node is found (this will
|
|
24
|
5176 descend subtrees if the function `Info-global-next' is bound);
|
|
0
|
5177 (5) anywhere else (e.g@. at the end of a line), the current node entry is
|
|
|
5178 scrolled up a windowful.
|
|
|
5179 ASSIST
|
|
|
5180 (1) the first line of an Info Menu Entry or Cross Reference, the desired
|
|
|
5181 node is found;
|
|
|
5182 (2) the Up,Next,or Previous entries of a Node Header (first line),
|
|
|
5183 the last node in the history list is found;
|
|
|
5184 (3) the File entry of a Node Header (first line),
|
|
24
|
5185 the `DIR' root-level node is found;
|
|
0
|
5186 (4) at the end of the current node, the Previous node is found (this will
|
|
|
5187 return from subtrees if the function 'Info-global-prev is bound);
|
|
|
5188 (5) anywhere else (e.g@. at the end of a line), the current node entry is
|
|
|
5189 scrolled down a windowful.
|
|
|
5190 @end group
|
|
|
5191 @end format
|
|
|
5192
|
|
|
5193 @page
|
|
|
5194 @format
|
|
|
5195 @group
|
|
24
|
5196 If pressed within a Hyperbole-supported mail reader, `hmail:reader', or mail
|
|
|
5197 summary mode, `hmail:lister', buffer at:
|
|
0
|
5198 ACTION
|
|
|
5199 (1) a msg buffer, within the first line or at the end of a message,
|
|
|
5200 the next undeleted message is displayed;
|
|
|
5201 (2) a msg buffer within the first line of an Info cross reference, the
|
|
|
5202 reference is followed;
|
|
|
5203 (3) anywhere else in a msg buffer, the window is scrolled up one
|
|
|
5204 windowful;
|
|
|
5205 (4) a msg summary buffer on a header entry, the message corresponding to
|
|
|
5206 the header is displayed in the msg window;
|
|
|
5207 (5) a msg summary buffer, on or after the last line, the messages marked
|
|
|
5208 for deletion are expunged.
|
|
|
5209 ASSIST
|
|
|
5210 (1) a msg buffer, within the first line or at the end of a message,
|
|
|
5211 the previous undeleted message is displayed;
|
|
|
5212 (2) a msg buffer within the first line of an Info cross reference, the
|
|
|
5213 reference is followed;
|
|
|
5214 (3) anywhere else in a msg buffer, the window is scrolled down one
|
|
|
5215 windowful;
|
|
|
5216 (4) a msg summary buffer on a header entry, the message corresponding to
|
|
|
5217 the header is marked as deleted;
|
|
|
5218 (5) a msg summary buffer, on or after the last line, all messages are
|
|
|
5219 marked undeleted.
|
|
|
5220 @end group
|
|
|
5221 @end format
|
|
|
5222
|
|
10
|
5223 @cindex click, GNUS
|
|
|
5224 @cindex GNUS browsing
|
|
0
|
5225 @format
|
|
|
5226 @group
|
|
|
5227 If pressed within a GNUS listing of newsgroups buffer at:
|
|
|
5228 ACTION
|
|
|
5229 (1) a GNUS-GROUP line, that newsgroup is read;
|
|
|
5230 (2) to the left of any GNUS-GROUP line, on any of the whitespace, the
|
|
|
5231 current group is unsubscribed or resubscribed;
|
|
|
5232 (3) at the end of the GNUS-GROUP buffer, after all lines, checks for new
|
|
|
5233 news.
|
|
|
5234 ASSIST
|
|
|
5235 (1) a GNUS-GROUP line, that newsgroup is read;
|
|
|
5236 (2) to the left of any GNUS-GROUP line, on any of the whitespace, the
|
|
|
5237 user is prompted for a group name to subscribe or unsubscribe to;
|
|
|
5238 (3) at the end of the GNUS-GROUP buffer, after all lines, quits from the
|
|
|
5239 newsreader.
|
|
|
5240 @end group
|
|
|
5241 @end format
|
|
|
5242
|
|
|
5243 @page
|
|
|
5244 @format
|
|
|
5245 @group
|
|
|
5246 If pressed within a GNUS newsreader subject listing buffer at:
|
|
|
5247 ACTION
|
|
|
5248 (1) a GNUS-SUBJECT line, that article is read, marked deleted, and
|
|
|
5249 scrolled forward;
|
|
|
5250 (2) at the end of the GNUS-SUBJECT buffer, the next undeleted article
|
|
|
5251 is read or the next group is entered.
|
|
|
5252 ASSIST
|
|
|
5253 (1) a GNUS-SUBJECT line, that article is read and scrolled backward;
|
|
|
5254 (2) at the end of the GNUS-SUBJECT buffer, the subject is exited, the
|
|
|
5255 user is returned to group mode.
|
|
|
5256 @end group
|
|
|
5257 @end format
|
|
|
5258
|
|
|
5259 @format
|
|
|
5260 @group
|
|
|
5261 If pressed within a GNUS newsreader article buffer at:
|
|
|
5262 ACTION
|
|
|
5263 (1) the first line or end of an article, the next unread message is
|
|
|
5264 displayed;
|
|
|
5265 (2) the first line of an Info cross reference, the reference is followed;
|
|
|
5266 (3) anywhere else, the window is scrolled up a windowful.
|
|
|
5267 ASSIST
|
|
|
5268 (1) the first line or end of an article, the previous message is
|
|
|
5269 displayed;
|
|
|
5270 (2) the first line of an Info cross reference, the reference is followed;
|
|
|
5271 (3) anywhere else, the window is scrolled down a windowful.
|
|
|
5272 @end group
|
|
|
5273 @end format
|
|
|
5274
|
|
|
5275 @page
|
|
10
|
5276 @cindex click, buffer menu
|
|
|
5277 @cindex buffer menu
|
|
0
|
5278 @format
|
|
|
5279 @group
|
|
|
5280 If pressed within a listing of buffers (Buffer-menu-mode):
|
|
|
5281 ACTION
|
|
|
5282 (1) on the first column of an entry, the selected buffer is marked for
|
|
|
5283 display;
|
|
|
5284 (2) on the second column of an entry, the selected buffer is marked to be
|
|
|
5285 saved;
|
|
|
5286 (3) anywhere else within an entry line, all saves and deletes are done,
|
|
|
5287 and selected buffers are displayed, including the one just clicked
|
|
|
5288 on (if in the OO-Browser, only the selected buffer is displayed);
|
|
|
5289 (4) on or after the last line in the buffer, all saves and deletes are
|
|
|
5290 done.
|
|
|
5291 ASSIST
|
|
|
5292 (1) on the first or second column of an entry, the selected buffer is
|
|
|
5293 unmarked for display and for saving or deletion;
|
|
|
5294 (2) anywhere else within an entry line, the selected buffer is marked for
|
|
|
5295 deletion;
|
|
|
5296 (3) on or after the last line in the buffer, all display, save, and delete
|
|
|
5297 marks on all entries are undone.
|
|
|
5298 @end group
|
|
|
5299 @end format
|
|
|
5300
|
|
10
|
5301 @cindex click, dired
|
|
|
5302 @cindex dired browsing
|
|
0
|
5303 @format
|
|
|
5304 @group
|
|
|
5305 If pressed within a dired-mode buffer:
|
|
|
5306 ACTION
|
|
|
5307 (1) within an entry line, the selected file/directory is displayed
|
|
|
5308 for editing in the other window;
|
|
|
5309 (2) on or after the last line in the buffer, if any deletes are to be
|
|
|
5310 performed, they are executed after user verification, otherwise, this
|
|
|
5311 dired invocation is quit.
|
|
|
5312 ASSIST
|
|
24
|
5313 (1) on a `~' character, all backup files in the directory are marked for
|
|
0
|
5314 deletion;
|
|
24
|
5315 (2) on a `#' character, all auto-save files in the directory are marked
|
|
0
|
5316 for deletion;
|
|
|
5317 (3) anywhere else within an entry line, the current entry is marked for
|
|
|
5318 deletion;
|
|
|
5319 (4) on or after the last line in the buffer, all delete marks on all
|
|
|
5320 entries are undone.
|
|
|
5321 @end group
|
|
|
5322 @end format
|
|
|
5323
|
|
|
5324 @page
|
|
|
5325 @cindex click, tar
|
|
|
5326 @cindex tar archive browsing
|
|
|
5327 @cindex extracting from tar files
|
|
10
|
5328 @format
|
|
|
5329 @group
|
|
0
|
5330 If pressed within a tar-mode buffer:
|
|
|
5331 ACTION
|
|
|
5332 (1) within an entry line, the selected file/directory is displayed
|
|
|
5333 for editing in the other window;
|
|
|
5334 (2) on or after the last line in the buffer, if any deletes are to be
|
|
|
5335 performed, they are executed after user verification, otherwise, this
|
|
|
5336 tar file browser is quit.
|
|
|
5337 ASSIST
|
|
|
5338 (1) on an entry line, the current entry is marked for deletion;
|
|
|
5339 (2) on or after the last line in the buffer, all delete marks on all
|
|
|
5340 entries are undone.
|
|
|
5341 @end group
|
|
|
5342 @end format
|
|
|
5343
|
|
10
|
5344 @cindex man page references
|
|
0
|
5345 @format
|
|
|
5346 @group
|
|
|
5347 If pressed on a cross reference within a man page entry section labeled
|
|
|
5348 NAME, SEE ALSO, or PACKAGES USED, or within a man page C routine
|
|
24
|
5349 specification (see `smart-man-c-routine-ref') and man page buffer
|
|
0
|
5350 has either an attached file or else a @var{man-path} local variable
|
|
|
5351 containing its pathname:
|
|
|
5352 ACTION or ASSIST
|
|
|
5353 Displays man page or source code for cross reference.
|
|
|
5354 @end group
|
|
|
5355 @end format
|
|
|
5356
|
|
|
5357 @cindex click, world-wide web
|
|
|
5358 @cindex W3
|
|
|
5359 @cindex URL
|
|
|
5360 @cindex world-wide web
|
|
10
|
5361 @format
|
|
|
5362 @group
|
|
0
|
5363 If pressed on a world-wide web universal resource locator:
|
|
|
5364 ACTION
|
|
|
5365 Displays the URL referent at point.
|
|
|
5366 ASSIST
|
|
|
5367 Goes back to a previously displayed web page.
|
|
|
5368 @end group
|
|
|
5369 @end format
|
|
|
5370
|
|
10
|
5371 @cindex game, gomoku
|
|
|
5372 @cindex gomoku
|
|
0
|
5373 @format
|
|
|
5374 @group
|
|
|
5375 If pressed in a Gomoku game buffer.
|
|
|
5376 ACTION
|
|
|
5377 Makes a move at the space pointed to.
|
|
|
5378 ASSIST
|
|
|
5379 Takes back a prior move made at the space pointed to.
|
|
|
5380 @end group
|
|
|
5381 @end format
|
|
|
5382
|
|
10
|
5383 @cindex click, wrolo matches
|
|
|
5384 @cindex wrolo matches
|
|
0
|
5385 @format
|
|
|
5386 @group
|
|
|
5387 If pressed within an entry in the wrolo match display buffer:
|
|
|
5388 ACTION or ASSIST
|
|
|
5389 The entry is edited in the other window.
|
|
|
5390 @end group
|
|
|
5391 @end format
|
|
|
5392
|
|
|
5393 @node Outliner Keys, Suggestion or Bug Reporting, Smart Key Reference, Top
|
|
|
5394 @appendix Outliner Keys
|
|
|
5395
|
|
|
5396 @cindex outliner keys
|
|
|
5397 This appendix summarizes the specialized key bindings available when
|
|
|
5398 editing an outline with Hyperbole. Each key is shown together with its
|
|
|
5399 command binding and the documentation for that command. Normal emacs
|
|
|
5400 editing keys are modified to account for the structure within outlines.
|
|
|
5401 An outliner command which overloads an Emacs command named @emph{cmd}
|
|
|
5402 would be named @emph{kotl-mode:cmd}.
|
|
|
5403
|
|
|
5404 @table @code
|
|
|
5405
|
|
|
5406 @findex kfile:write
|
|
|
5407 @item kfile:write @{@kbd{C-x C-w}@}
|
|
|
5408 Write current outline to FILE.
|
|
|
5409
|
|
|
5410 @findex klink:create
|
|
|
5411 @item klink:create @{@kbd{C-c l}@}
|
|
|
5412 Insert at point an implicit link to REFERENCE.
|
|
|
5413 REFERENCE should be a cell-ref or a string containing "filename, cell-ref".
|
|
|
5414 See documentation for @code{kcell:ref-to-id} for valid cell-ref formats.
|
|
|
5415
|
|
|
5416 @findex kotl-mode:add-cell
|
|
|
5417 @item kotl-mode:add-cell @{@key{LFD}@}
|
|
|
5418 Add a cell following current cell at optional RELATIVE-LEVEL with CONTENTS string.
|
|
|
5419 Optional prefix arg RELATIVE-LEVEL means add as sibling if nil or >= 0, as child
|
|
|
5420 if equal to universal argument, @kbd{C-u}, and as sibling of current cell's
|
|
|
5421 parent, otherwise. If added as sibling of current level, RELATIVE-LEVEL is
|
|
|
5422 used as a repeat count for the number of cells to add.
|
|
|
5423
|
|
|
5424 Return last newly added cell.
|
|
|
5425
|
|
|
5426 @findex kotl-mode:add-child
|
|
|
5427 @item kotl-mode:add-child @{@kbd{C-c a}@}
|
|
|
5428 Add a new cell to current kview as first child of current cell.
|
|
|
5429
|
|
|
5430 @findex kotl-mode:add-parent
|
|
|
5431 @item kotl-mode:add-parent @{@kbd{C-c p}@}
|
|
|
5432 Add a new cell to current kview as sibling of current cell's parent.
|
|
|
5433
|
|
|
5434 @findex kotl-mode:append-cell
|
|
|
5435 @item kotl-mode:append-cell @{@kbd{C-c +}@}
|
|
|
5436 Append CONTENTS-CELL to APPEND-TO-CELL.
|
|
|
5437 APPEND-TO-CELL is refilled if neither cell has a no-fill property and
|
|
|
5438 kotl-mode:refill-flag is enabled.
|
|
|
5439
|
|
|
5440 @findex kotl-mode:back-to-indentation
|
|
|
5441 @item kotl-mode:back-to-indentation @{@kbd{M-m}@}
|
|
|
5442 Move point to the first non-read-only non-whitespace character on this line.
|
|
|
5443
|
|
|
5444 @findex kotl-mode:backward-cell
|
|
|
5445 @item kotl-mode:backward-cell @{@kbd{C-c C-b}@}
|
|
|
5446 Move to prefix ARGth prior cell (same level) within current view.
|
|
|
5447 Return number of cells left to move.
|
|
|
5448
|
|
|
5449 @findex kotl-mode:backward-char
|
|
|
5450 @item kotl-mode:backward-char @{@kbd{C-b}@}
|
|
|
5451 Move point backward ARG (or 1) characters and return point.
|
|
|
5452
|
|
|
5453 @findex kotl-mode:backward-kill-word
|
|
|
5454 @item kotl-mode:backward-kill-word @{@kbd{M-DEL}@}
|
|
|
5455 Kill up to prefix ARG words preceding point within a single cell.
|
|
|
5456
|
|
|
5457 @findex kotl-mode:backward-sentence
|
|
|
5458 @item kotl-mode:backward-sentence @{@kbd{M-a}@}
|
|
|
5459 Move point backward ARG (or 1) sentences and return point.
|
|
|
5460
|
|
|
5461 @findex kotl-mode:backward-word
|
|
|
5462 @item kotl-mode:backward-word @{@kbd{M-b}@}
|
|
|
5463 Move point backward ARG (or 1) words and return point.
|
|
|
5464
|
|
|
5465 @findex kotl-mode:beginning-of-buffer
|
|
|
5466 @item kotl-mode:beginning-of-buffer @{@kbd{M-<}@}
|
|
|
5467 Move point to beginning of buffer and return point.
|
|
|
5468
|
|
|
5469 @findex kotl-mode:beginning-of-cell
|
|
|
5470 @item kotl-mode:beginning-of-cell @{@kbd{C-c ,}@}
|
|
|
5471 Move point to beginning of current or ARGth - 1 prior cell and return point.
|
|
|
5472
|
|
|
5473 @findex kotl-mode:beginning-of-line
|
|
|
5474 @item kotl-mode:beginning-of-line @{@kbd{C-a}@}
|
|
|
5475 Move point to beginning of current or ARGth - 1 line and return point.
|
|
|
5476
|
|
|
5477 @findex kotl-mode:beginning-of-tree
|
|
|
5478 @item kotl-mode:beginning-of-tree @{@kbd{C-c ^}@}
|
|
|
5479 Move point to the level 1 root of the current cell's tree.
|
|
|
5480 Leave point at the start of the cell.
|
|
|
5481
|
|
|
5482 @findex kotl-mode:center-line
|
|
|
5483 @item kotl-mode:center-line @{@kbd{M-s}@}
|
|
|
5484 @vindex fill-column
|
|
|
5485 Center the line point is on, within the width specified by @var{fill-column}.
|
|
|
5486 This means adjusting the indentation so that it equals the distance between
|
|
|
5487 the end of the text and @var{fill-column}.
|
|
|
5488
|
|
|
5489 @findex kotl-mode:center-paragraph
|
|
|
5490 @item kotl-mode:center-paragraph @{@kbd{M-S}@}
|
|
|
5491 Center each nonblank line in the paragraph at or after point.
|
|
|
5492 See @code{center-line} for more info.
|
|
|
5493
|
|
|
5494 @findex kotl-mode:copy-after
|
|
|
5495 @item kotl-mode:copy-after @{@kbd{C-c c}@}
|
|
|
5496 Copy tree rooted at FROM-CELL-REF to follow tree rooted at TO-CELL-REF.
|
|
|
5497 If prefix arg CHILD-P is non-nil, make FROM-CELL-REF the first child of
|
|
|
5498 TO-CELL-REF, otherwise make it the sibling following TO-CELL-REF.
|
|
|
5499
|
|
|
5500 Leave point at the start of the root cell of the new tree.
|
|
|
5501
|
|
|
5502 @findex kotl-mode:copy-before
|
|
|
5503 @item kotl-mode:copy-before @{@kbd{C-c C-c}@}
|
|
|
5504 Copy tree rooted at FROM-CELL-REF to precede tree rooted at TO-CELL-REF.
|
|
|
5505 If prefix arg PARENT-P is non-nil, make FROM-CELL-REF the first child of
|
|
|
5506 TO-CELL-REF's parent, otherwise make it the preceding sibling of TO-CELL-REF.
|
|
|
5507
|
|
|
5508 Leave point at the start of the root cell of the new tree.
|
|
|
5509
|
|
|
5510 @findex kotl-mode:copy-to-buffer
|
|
|
5511 @item kotl-mode:copy-to-buffer @{@kbd{C-c M-c}@}
|
|
|
5512 Copy outline tree rooted at CELL-REF to a non-koutline BUFFER.
|
|
|
5513 Use 0 to copy the whole outline buffer.
|
|
|
5514
|
|
|
5515 @findex kotl-mode:copy-to-register
|
|
|
5516 @item kotl-mode:copy-to-register @{@kbd{C-x x}@}
|
|
|
5517 Copy into REGISTER the region START to END.
|
|
|
5518 With optional prefix arg DELETE-FLAG, delete region.
|
|
|
5519
|
|
|
5520 @findex kotl-mode:delete-backward-char
|
|
|
5521 @item kotl-mode:delete-backward-char @{@kbd{DEL}@}
|
|
|
5522 Delete up to the preceding prefix ARG characters.
|
|
|
5523 Return number of characters deleted.
|
|
|
5524 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
|
|
|
5525 Does not delete across cell boundaries.
|
|
|
5526
|
|
|
5527 @findex kotl-mode:delete-blank-lines
|
|
|
5528 @item kotl-mode:delete-blank-lines @{@kbd{C-x C-o}@}
|
|
|
5529 On blank line within a cell, delete all surrounding blank lines, leaving just one.
|
|
|
5530 On isolated blank line, delete that one.
|
|
|
5531 On nonblank line, delete all blank lines that follow it.
|
|
|
5532
|
|
|
5533 If nothing but whitespace follows point until the end of a cell, delete all
|
|
|
5534 whitespace at the end of the cell.
|
|
|
5535
|
|
|
5536 @findex kotl-mode:delete-char
|
|
|
5537 @item kotl-mode:delete-char @{@kbd{C-d}@}
|
|
|
5538 Delete up to prefix ARG characters following point.
|
|
|
5539 Return number of characters deleted.
|
|
|
5540 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
|
|
|
5541 Does not delete across cell boundaries.
|
|
|
5542
|
|
|
5543 @findex kotl-mode:delete-indentation
|
|
|
5544 @item kotl-mode:delete-indentation @{@kbd{M-^}@}
|
|
|
5545 Join this line to previous and fix up whitespace at join.
|
|
|
5546 If there is a fill prefix, delete it from the beginning of this line.
|
|
|
5547 With argument, join this line to following line.
|
|
|
5548
|
|
|
5549 @findex kotl-mode:demote-tree
|
|
|
5550 @vindex kotl-mode:refill-flag
|
|
|
5551 @item kotl-mode:demote-tree @{@kbd{TAB}@}
|
|
|
5552 Move current kotl a maximum of prefix ARG levels lower in current view.
|
|
|
5553 Each cell is refilled iff its @emph{no-fill} attribute is nil and
|
|
|
5554 @var{kotl-mode:refill-flag} is non-nil. With prefix ARG = 0, cells are
|
|
|
5555 demoted up to one level and kotl-mode:refill-flag is treated as true.
|
|
|
5556
|
|
|
5557 @findex kotl-mode:down-level
|
|
|
5558 @item kotl-mode:down-level @{@kbd{C-c C-d}@}
|
|
|
5559 Move down prefix ARG levels lower within current tree.
|
|
|
5560
|
|
|
5561 @findex kotl-mode:end-of-buffer
|
|
|
5562 @item kotl-mode:end-of-buffer @{@kbd{M->}@}
|
|
|
5563 Move point to end of buffer and return point.
|
|
|
5564
|
|
|
5565 @findex kotl-mode:end-of-cell
|
|
|
5566 @item kotl-mode:end-of-cell @{@kbd{C-c .}@}
|
|
|
5567 Move point to end of current or ARGth - 1 succeeding cell and return point.
|
|
|
5568
|
|
|
5569 @findex kotl-mode:end-of-line
|
|
|
5570 @item kotl-mode:end-of-line @{@kbd{C-e}@}
|
|
|
5571 Move point to end of current or ARGth - 1 line and return point.
|
|
|
5572
|
|
|
5573 @findex kotl-mode:end-of-tree
|
|
|
5574 @item kotl-mode:end-of-tree @{@kbd{C-c $}@}
|
|
|
5575 Move point to the last cell in tree rooted at the current cell.
|
|
|
5576 Leave point at the start of the cell.
|
|
|
5577
|
|
|
5578 @findex kotl-mode:exchange-cells
|
|
|
5579 @item kotl-mode:exchange-cells @{@kbd{C-c e}@}
|
|
|
5580 Exchange CELL-REF-1 with CELL-REF-2 in current view. Don't move point.
|
|
|
5581
|
|
|
5582 @findex kotl-mode:fill-cell
|
|
|
5583 @item kotl-mode:fill-cell @{@kbd{C-c M-j}@}
|
|
|
5584 Fill current cell within current view if it does not have the 'no-fill attribute.
|
|
|
5585 With optional JUSTIFY, justify cell as well.
|
|
|
5586 IGNORE-COLLAPSED-P is used when caller has already expanded cell, indicating
|
|
|
5587 it is not collapsed.
|
|
|
5588
|
|
|
5589 @findex kotl-mode:fill-paragraph
|
|
|
5590 @item kotl-mode:fill-paragraph @{@kbd{C-x f}@}
|
|
|
5591 Fill current paragraph within cell. With optional JUSTIFY, justify
|
|
|
5592 paragraph as well. Ignore any non-nil no-fill attribute attached to the
|
|
|
5593 cell.
|
|
|
5594
|
|
|
5595 @findex kotl-mode:fill-tree
|
|
|
5596 @item kotl-mode:fill-tree @{@kbd{C-M-j}@}
|
|
|
5597 Refill each cell within the tree whose root is at point.
|
|
|
5598
|
|
|
5599 @findex kotl-mode:first-sibling
|
|
|
5600 @item kotl-mode:first-sibling @{@kbd{C-c <}@}
|
|
|
5601 Move point to the first sibling of the present cell.
|
|
|
5602 Leave point at the start of the cell or at its present position if it is
|
|
|
5603 already within the first sibling cell.
|
|
|
5604
|
|
|
5605 @findex kotl-mode:fkey-backward-char
|
|
|
5606 @item kotl-mode:fkey-backward-char @{@kbd{left}@}
|
|
|
5607 Move point backward ARG (or 1) characters and return point.
|
|
|
5608
|
|
|
5609 @findex kotl-mode:fkey-forward-char
|
|
|
5610 @item kotl-mode:fkey-forward-char @{@kbd{right}@}
|
|
|
5611 Move point forward ARG (or 1) characters and return point.
|
|
|
5612
|
|
|
5613 @findex kotl-mode:fkey-next-line
|
|
|
5614 @item kotl-mode:fkey-next-line @{@kbd{down}@}
|
|
|
5615 Move point to ARGth next line and return point.
|
|
|
5616
|
|
|
5617 @findex kotl-mode:fkey-previous-line
|
|
|
5618 @item kotl-mode:fkey-previous-line @{@kbd{up}@}
|
|
|
5619 Move point to ARGth previous line and return point.
|
|
|
5620
|
|
|
5621 @findex kotl-mode:forward-cell
|
|
|
5622 @item kotl-mode:forward-cell @{@kbd{C-c C-f}@}
|
|
|
5623 Move to prefix ARGth following cell (same level) within current view.
|
|
|
5624 Return number of cells left to move.
|
|
|
5625
|
|
|
5626 @findex kotl-mode:forward-char
|
|
|
5627 @item kotl-mode:forward-char @{@kbd{C-f}@}
|
|
|
5628 Move point forward ARG (or 1) characters and return point.
|
|
|
5629
|
|
|
5630 @findex kotl-mode:forward-para
|
|
|
5631 @item kotl-mode:forward-para @{@kbd{M-n}@}
|
|
|
5632 Move to prefix ARGth next cell (any level) within current view.
|
|
|
5633
|
|
|
5634 @findex kotl-mode:forward-paragraph
|
|
|
5635 @item kotl-mode:forward-paragraph @{@kbd{M-]}@}
|
|
|
5636 Move to prefix ARGth next cell (any level) within current view.
|
|
|
5637
|
|
|
5638 @findex kotl-mode:forward-sentence
|
|
|
5639 @item kotl-mode:forward-sentence @{@kbd{M-e}@}
|
|
|
5640 Move point forward ARG (or 1) sentences and return point.
|
|
|
5641
|
|
|
5642 @findex kotl-mode:forward-word
|
|
|
5643 @item kotl-mode:forward-word @{@kbd{M-f}@}
|
|
|
5644 Move point forward ARG (or 1) words and return point.
|
|
|
5645
|
|
|
5646 @findex kotl-mode:goto-cell
|
|
|
5647 @item kotl-mode:goto-cell @{@kbd{C-c g}@}
|
|
24
|
5648 Move point to start of cell given by CELL-REF. (See `kcell:ref-to-id'.)
|
|
0
|
5649 Return point iff CELL-REF is found within current view.
|
|
|
5650 With a prefix argument, CELL-REF is assigned the argument value for use
|
|
|
5651 as an idstamp.
|
|
|
5652
|
|
|
5653 Optional second arg, ERROR-P, non-nil means signal an error if CELL-REF is
|
|
|
5654 not found within current view. Will signal same error if called
|
|
|
5655 interactively when CELL-REF is not found.
|
|
|
5656
|
|
|
5657 @findex kotl-mode:hide-sublevels
|
|
|
5658 @item kotl-mode:hide-sublevels @{@kbd{C-X $}@}
|
|
|
5659 Hide all cells in outline at levels deeper than LEVELS-TO-KEEP (a
|
|
|
5660 number). Shows any hidden cells within LEVELS-TO-KEEP. 1 is the first
|
|
|
5661 level.
|
|
|
5662
|
|
|
5663 @findex kotl-mode:hide-subtree
|
|
|
5664 @item kotl-mode:hide-subtree @{@kbd{C-M-h}@}
|
|
|
5665 Hide subtree, ignoring root, at optional CELL-REF (defaults to cell at
|
|
|
5666 point).
|
|
|
5667
|
|
|
5668 @findex kotl-mode:hide-tree
|
|
|
5669 @item kotl-mode:hide-tree @{@kbd{C-c BS}@}
|
|
|
5670 Collapse kotl rooted at optional CELL-REF (defaults to cell at point).
|
|
|
5671
|
|
|
5672 @findex kotl-mode:insert-file
|
|
|
5673 @item kotl-mode:insert-file @{@kbd{C-x i}@}
|
|
|
5674 Insert each paragraph in IMPORT-FROM as a separate cell in the current view.
|
|
|
5675 Insert as sibling cells following the current cell. IMPORT-FROM may be a
|
|
|
5676 buffer name or file name (file name completion is provided).
|
|
|
5677
|
|
|
5678 @findex kotl-mode:insert-register
|
|
|
5679 @item kotl-mode:insert-register @{@kbd{C-c r i}@}
|
|
|
5680 Insert contents of register REGISTER at point in current cell.
|
|
|
5681 REGISTER is a character naming the register to insert.
|
|
|
5682 Normally puts point before and mark after the inserted text.
|
|
|
5683 If optional second arg is non-nil, puts mark before and point after.
|
|
|
5684 Interactively, second arg is non-nil if prefix arg is supplied.
|
|
|
5685
|
|
|
5686 @findex kotl-mode:just-one-space
|
|
|
5687 @item kotl-mode:just-one-space @{@kbd{M-\}@}
|
|
|
5688 Delete all spaces and tabs around point and leave one space.
|
|
|
5689
|
|
|
5690 @findex kotl-mode:kcell-help
|
|
|
5691 @item kotl-mode:kcell-help @{@kbd{C-c h}@}
|
|
|
5692 Display a temporary buffer with CELL-REF's properties.
|
|
|
5693 CELL-REF defaults to current cell.
|
|
|
5694 Optional prefix arg CELLS-FLAG selects the cells to print:
|
|
|
5695 If = 1, print CELL-REF's cell only;
|
|
|
5696 If > 1, print CELL-REF's visible kotl (the tree rooted at CELL-REF);
|
|
|
5697 If < 1, print all visible cells in current view (CELL-REF is not used).
|
|
|
5698
|
|
|
5699 See also the documentation for @code{kotl-mode:properties}.
|
|
|
5700
|
|
|
5701 @findex kotl-mode:kill-contents
|
|
|
5702 @item kotl-mode:kill-contents @{@kbd{C-c k}@}
|
|
|
5703 Kill contents of cell from point to cell end.
|
|
|
5704 With prefix ARG, kill entire cell contents.
|
|
|
5705
|
|
|
5706 @findex kotl-mode:kill-line
|
|
|
5707 @item kotl-mode:kill-line @{@kbd{C-k}@}
|
|
|
5708 Kill ARG lines from point.
|
|
|
5709
|
|
|
5710 @findex kotl-mode:kill-region
|
|
|
5711 @item kotl-mode:kill-region @{@kbd{C-w}@}
|
|
|
5712 Kill region between START and END within a single kcell.
|
|
|
5713 With optional COPY-P equal to 't, copy region to kill ring but does not
|
|
|
5714 kill it. With COPY-P any other non-nil value, return region as a
|
|
|
5715 string without affecting kill ring.
|
|
|
5716
|
|
|
5717 If the buffer is read-only and COPY-P is nil, the region will not be deleted
|
|
|
5718 but it will be copied to the kill ring and then an error will be signaled.
|
|
|
5719
|
|
|
5720 @findex kotl-mode:kill-ring-save
|
|
|
5721 @item kotl-mode:kill-ring-save @{@kbd{M-w}@}
|
|
|
5722 Copy region between START and END within a single kcell to kill ring.
|
|
|
5723
|
|
|
5724 @findex kotl-mode:kill-sentence
|
|
|
5725 @item kotl-mode:kill-sentence @{@kbd{M-k}@}
|
|
|
5726 Kill up to prefix ARG (or 1) sentences following point within a single cell.
|
|
|
5727
|
|
|
5728 @findex kotl-mode:kill-tree
|
|
|
5729 @item kotl-mode:kill-tree @{@kbd{C-c C-k}@}
|
|
|
5730 Kill ARG following trees starting with tree rooted at point.
|
|
|
5731 If ARG is not a non-positive number, nothing is done.
|
|
|
5732
|
|
|
5733 @findex kotl-mode:kill-word
|
|
|
5734 @item kotl-mode:kill-word @{@kbd{M-d}@}
|
|
|
5735 Kill up to prefix ARG words following point within a single cell.
|
|
|
5736
|
|
|
5737 @findex kotl-mode:last-sibling
|
|
|
5738 @item kotl-mode:last-sibling @{@kbd{C-c >}@}
|
|
|
5739 Move point to the last sibling of the present cell.
|
|
|
5740 Leave point at the start of the cell or at its present position if it is
|
|
|
5741 already within the last sibling cell.
|
|
|
5742
|
|
|
5743 @findex kotl-mode:mail-tree
|
|
|
5744 @item kotl-mode:mail-tree @{@kbd{C-c @@}@}
|
|
|
5745 Mail outline tree rooted at CELL-REF. Use "0" for whole outline buffer.
|
|
|
5746
|
|
|
5747 @findex kotl-mode:move-after
|
|
|
5748 @item kotl-mode:move-after @{@kbd{C-c m}@}
|
|
|
5749 Move tree rooted at FROM-CELL-REF to follow tree rooted at TO-CELL-REF.
|
|
|
5750 If prefix arg CHILD-P is non-nil, make FROM-CELL-REF the first child of
|
|
|
5751 TO-CELL-REF, otherwise make it the sibling following TO-CELL-REF.
|
|
|
5752 With optional COPY-P, copies tree rather than moving it.
|
|
|
5753
|
|
|
5754 Leave point at original location but return the tree's new start point.
|
|
|
5755
|
|
|
5756 @findex kotl-mode:move-before
|
|
|
5757 @item kotl-mode:move-before @{@kbd{C-c RET}@}
|
|
|
5758 Move tree rooted at FROM-CELL-REF to precede tree rooted at TO-CELL-REF.
|
|
|
5759 If prefix arg PARENT-P is non-nil, make FROM-CELL-REF the first child of
|
|
|
5760 TO-CELL-REF's parent, otherwise make it the preceding sibling of TO-CELL-REF.
|
|
|
5761 With optional COPY-P, copies tree rather than moving it.
|
|
|
5762
|
|
|
5763 Leave point at original location but return the tree's new start point.
|
|
|
5764
|
|
|
5765 @findex kotl-mode:newline
|
|
|
5766 @item kotl-mode:newline @{@kbd{RET}@}
|
|
|
5767 Insert a newline. With ARG, insert ARG newlines.
|
|
|
5768 In Auto Fill mode, if no numeric arg, break the preceding line if it is
|
|
|
5769 too long.
|
|
|
5770
|
|
|
5771 @findex kotl-mode:next-cell
|
|
|
5772 @item kotl-mode:next-cell @{@kbd{C-c C-n}@}
|
|
|
5773 Move to prefix ARGth next cell (any level) within current view.
|
|
|
5774
|
|
|
5775 @findex kotl-mode:next-line
|
|
|
5776 @item kotl-mode:next-line @{@kbd{C-n}@}
|
|
|
5777 Move point to ARGth next line and return point.
|
|
|
5778
|
|
|
5779 @findex kotl-mode:open-line
|
|
|
5780 @item kotl-mode:open-line @{@kbd{C-o}@}
|
|
|
5781 Insert a newline and leave point before it.
|
|
|
5782 With arg N, insert N newlines.
|
|
|
5783
|
|
|
5784 @findex kotl-mode:overview
|
|
|
5785 @item kotl-mode:overview @{@kbd{C-c C-o}@}
|
|
|
5786 Show only the first line of each cell in the current outline.
|
|
|
5787
|
|
|
5788 @findex kotl-mode:previous-cell
|
|
|
5789 @item kotl-mode:previous-cell @{@kbd{C-c C-p}@}
|
|
|
5790 Move to prefix ARGth previous cell (any level) within current view.
|
|
|
5791
|
|
|
5792 @findex kotl-mode:previous-line
|
|
|
5793 @item kotl-mode:previous-line @{@kbd{C-p}@}
|
|
|
5794 Move point to ARGth previous line and return point.
|
|
|
5795
|
|
|
5796 @findex kotl-mode:promote-tree
|
|
|
5797 @vindex kotl-mode:refill-flag
|
|
|
5798 @item kotl-mode:promote-tree @{@kbd{M-TAB}@}
|
|
|
5799 Move current kotl a maximum of prefix ARG levels higher in current view.
|
|
|
5800 Each cell is refilled iff its @emph{no-fill} attribute is nil and
|
|
|
5801 @var{kotl-mode:refill-flag} is non-nil. With prefix ARG = 0, cells are
|
|
|
5802 promoted up to one level and kotl-mode:refill-flag is treated as true.
|
|
|
5803
|
|
|
5804 @findex kotl-mode:scroll-down
|
|
|
5805 @item kotl-mode:scroll-down @{@kbd{M-v}@}
|
|
|
5806 Scroll text of current window downward ARG lines; or a windowful if no ARG.
|
|
|
5807
|
|
|
5808 @findex kotl-mode:scroll-up
|
|
|
5809 @item kotl-mode:scroll-up @{@kbd{C-v}@}
|
|
|
5810 Scroll text of current window upward ARG lines; or a windowful if no ARG.
|
|
|
5811
|
|
|
5812 @findex kotl-mode:set-cell-attribute
|
|
|
5813 @item kotl-mode:set-cell-attribute @{@kbd{C-c C-i}@}
|
|
|
5814 Include ATTRIBUTE VALUE with the current cell or the cell at optional POS.
|
|
|
5815 Replaces any existing value that ATTRIBUTE has.
|
|
|
5816 When called interactively, it displays the setting in the minibuffer as
|
|
|
5817 confirmation.
|
|
|
5818
|
|
|
5819 @findex kotl-mode:set-fill-prefix
|
|
|
5820 @item kotl-mode:set-fill-prefix @{@kbd{C-x l}@}
|
|
|
5821 Sets fill prefix to line up to point.
|
|
|
5822 With prefix arg TURN-OFF or at begin of line, turns fill prefix off.
|
|
|
5823
|
|
|
5824 @findex kotl-mode:show-all
|
|
|
5825 @item kotl-mode:show-all @{@kbd{C-c C-a}@}
|
|
|
5826 Show (expand) all cells in current view.
|
|
|
5827
|
|
|
5828 @findex kotl-mode:show-subtree
|
|
|
5829 @item kotl-mode:show-subtree
|
|
|
5830 Show subtree, ignoring root, at optional CELL-REF (defaults to cell at
|
|
|
5831 point).
|
|
|
5832
|
|
|
5833 @findex kotl-mode:show-tree
|
|
|
5834 @item kotl-mode:show-tree @{@kbd{C-c C-s}@}
|
|
|
5835 Display fully expanded kotl rooted at CELL-REF.
|
|
|
5836
|
|
|
5837 @findex kotl-mode:split-cell
|
|
|
5838 @item kotl-mode:split-cell @{@kbd{C-c s}@}
|
|
|
5839 Split cell into two cells and move to new cell.
|
|
|
5840 Cell contents after point become part of newly created cell.
|
|
|
5841 Default is to create new cell as sibling of current cell.
|
|
|
5842 With optional universal ARG, @kbd{C-u}, new cell is added as child of
|
|
|
5843 current cell.
|
|
|
5844
|
|
|
5845 @findex kotl-mode:top-cells
|
|
|
5846 @item kotl-mode:top-cells @{@kbd{C-c C-t}@}
|
|
|
5847 Collapse all level 1 cells in view and hide any deeper sublevels.
|
|
|
5848
|
|
|
5849 @findex kotl-mode:transpose-cells
|
|
|
5850 @item kotl-mode:transpose-cells @{@kbd{C-c t}@}
|
|
|
5851 Exchange current and previous visible cells, leaving point after both.
|
|
|
5852 If no previous cell, exchange current with next cell.
|
|
|
5853 With prefix ARG, take current cell and move it past ARG cells.
|
|
|
5854 With prefix ARG = 0, interchange the cell that contains point with the cell
|
|
|
5855 that contains mark.
|
|
|
5856
|
|
|
5857 @findex kotl-mode:transpose-chars
|
|
|
5858 @item kotl-mode:transpose-chars @{@kbd{C-t}@}
|
|
|
5859 Interchange characters around point, moving forward one character.
|
|
|
5860 With prefix ARG, take character before point and drag it forward past ARG
|
|
|
5861 other characters (backward if ARG negative).
|
|
|
5862 If no prefix ARG and at end of line, the previous two characters are
|
|
|
5863 exchanged.
|
|
|
5864
|
|
|
5865 @findex kotl-mode:transpose-lines
|
|
|
5866 @item kotl-mode:transpose-lines @{@kbd{C-x C-t}@}
|
|
|
5867 Exchange current line and previous line, leaving point after both.
|
|
|
5868 If no previous line, exchange current with next line.
|
|
|
5869 With prefix ARG, take previous line and move it past ARG lines.
|
|
|
5870 With prefix ARG = 0, interchange the line that contains point with the line
|
|
|
5871 that contains mark.
|
|
|
5872
|
|
|
5873 @findex kotl-mode:transpose-words
|
|
|
5874 @item kotl-mode:transpose-words @{@kbd{M-t}@}
|
|
|
5875 Interchange words around point, leaving point after both words.
|
|
|
5876 With prefix ARG, take word before or around point and drag it forward past
|
|
|
5877 ARG other words (backward if ARG negative). If ARG is zero, the words around
|
|
|
5878 or after point and around or after mark are interchanged.
|
|
|
5879
|
|
|
5880 @findex kotl-mode:up-level
|
|
|
5881 @item kotl-mode:up-level @{@kbd{C-c C-u}@}
|
|
|
5882 Move up prefix ARG levels higher in current outline view.
|
|
|
5883
|
|
|
5884 @findex kotl-mode:yank
|
|
|
5885 @item kotl-mode:yank @{@kbd{C-y}@}
|
|
|
5886 Reinsert the last stretch of killed text.
|
|
|
5887 More precisely, reinsert the stretch of killed text most recently
|
|
|
5888 killed OR yanked. Put point at end, and set mark at beginning.
|
|
|
5889 With just C-u as argument, same but put point at beginning (and mark at end).
|
|
|
5890 With argument N, reinsert the Nth most recently killed stretch of killed
|
|
|
5891 text.
|
|
|
5892 See also the command M-x kotl-mode:yank-pop.
|
|
|
5893
|
|
|
5894 @findex kotl-mode:yank-pop
|
|
|
5895 @item kotl-mode:yank-pop @{@kbd{M-y}@}
|
|
|
5896 Replace just-yanked stretch of killed text with a different stretch.
|
|
|
5897 This command is allowed only immediately after a @code{yank} or a
|
|
|
5898 @code{yank-pop}. At such a time, the region contains a stretch of
|
|
|
5899 reinserted previously-killed text. @code{yank-pop} deletes that text
|
|
|
5900 and inserts in its place a different stretch of killed text.
|
|
|
5901
|
|
|
5902 With no argument, the previous kill is inserted.
|
|
|
5903 With argument N, insert the Nth previous kill.
|
|
|
5904 If N is negative, this is a more recent kill.
|
|
|
5905
|
|
|
5906 The sequence of kills wraps around, so that after the oldest one
|
|
|
5907 comes the newest one.
|
|
|
5908
|
|
|
5909 @findex kotl-mode:zap-to-char
|
|
|
5910 @item kotl-mode:zap-to-char @{@kbd{M-z}@}
|
|
|
5911 Kill up to and including prefix ARG'th occurrence of CHAR.
|
|
|
5912 Goes backward if ARG is negative; error if CHAR not found.
|
|
|
5913
|
|
|
5914 @findex kview:set-label-type
|
|
|
5915 @item kview:set-label-type @{@kbd{C-c C-l}@}
|
|
|
5916 Change kview's label display type to NEW-TYPE, updating all displayed labels.
|
|
|
5917 See documentation for variable, kview:default-label-type, for
|
|
|
5918 valid values of NEW-TYPE.
|
|
|
5919
|
|
|
5920 @findex kvspec:activate
|
|
|
5921 @item kvspec:activate @{@kbd{C-c C-v}@}
|
|
|
5922 Activate optional VIEW-SPEC or existing view spec in the current koutline.
|
|
|
5923 VIEW-SPEC is a string. See <$@{hyperb:dir@}/kotl/EXAMPLE.kotl, 2b17=048> for
|
|
|
5924 details on valid view specs.
|
|
|
5925
|
|
|
5926 @findex kvspec:toggle-blank-lines
|
|
|
5927 @item kvspec:toggle-blank-lines @{@kbd{C-c b}@}
|
|
|
5928 Toggle blank lines between cells on or off.
|
|
|
5929
|
|
|
5930 @end table
|
|
|
5931
|
|
|
5932 @node Suggestion or Bug Reporting, Questions and Answers, Outliner Keys, Top
|
|
|
5933 @appendix Suggestion or Bug Reporting
|
|
|
5934
|
|
|
5935 @xref{Mail Lists}, for complete details on Hyperbole mailing lists and
|
|
|
5936 how to subscribe.
|
|
|
5937
|
|
|
5938 @cindex version description
|
|
|
5939 @cindex Hyperbole version
|
|
|
5940 If you find any errors in Hyperbole's operation or documentation, feel
|
|
|
5941 free to report them to the Hyperbole discussion list:
|
|
24
|
5942 <hyperbole@@infodock.com>. Be sure to use the Msg/Compose-Hypb-Mail
|
|
0
|
5943 minibuffer menu item whenever you send a message to the mail list since
|
|
|
5944 it will insert important system version information for you.
|
|
|
5945
|
|
|
5946 If you use Hyperbole mail or news support, @ref{Buttons in Mail}, a
|
|
|
5947 click with your Action Key on the Hyperbole mail list address
|
|
|
5948 will insert a description of your Hyperbole configuration information
|
|
|
5949 into your outgoing message, so that you do not have to type it. This is
|
|
|
5950 useful when composing a reply for the Hyperbole mail list. Otherwise,
|
|
|
5951 be sure to include your Emacs, Hyperbole and window system versions in
|
|
|
5952 your message. Your Hyperbole version number can be found in the
|
|
|
5953 top-level Hyperbole menu.
|
|
|
5954
|
|
|
5955 Please use your subject line to state the position that your message
|
|
|
5956 takes on the topic that it addresses, e.g@. send "Subject: Basic bug in
|
|
|
5957 top-level Hyperbole menu." rather than "Subject: Hyperbole bug". This
|
|
|
5958 simple rule makes all e-mail communication much easier.
|
|
|
5959
|
|
|
5960 If you have suggestions on how to improve Hyperbole, send them to the
|
|
|
5961 same address. Here are some issues you might address:
|
|
|
5962
|
|
|
5963 @itemize @bullet
|
|
|
5964 @item
|
|
|
5965 What did you like and dislike about the system?
|
|
|
5966 @item
|
|
|
5967 What kinds of tasks, if any, does it seem to help you with?
|
|
|
5968 @item
|
|
|
5969 What did you think of the Emacs-based user interface?
|
|
|
5970 @item
|
|
|
5971 How was the Hyperbole Manual and other documentation?
|
|
|
5972 @item
|
|
|
5973 Was the setup trivial, average or hard?
|
|
|
5974 @item
|
|
|
5975 What areas of Hyperbole would you like to see expanded/added?
|
|
|
5976 @item
|
|
|
5977 How does it compare to other hypertext tools you have used?
|
|
|
5978 @item
|
|
|
5979 Was it easy or difficult to create your own types? Why?
|
|
|
5980 @item
|
|
|
5981 Did you get any use out of the external system encapsulations?
|
|
|
5982 @end itemize
|
|
|
5983
|
|
|
5984 @node Questions and Answers, Future Work, Suggestion or Bug Reporting, Top
|
|
|
5985 @appendix Questions and Answers
|
|
|
5986
|
|
|
5987 @table @emph
|
|
|
5988 @cindex Smart Key
|
|
|
5989 @cindex mouse key bindings
|
|
|
5990 @findex hmouse-setup
|
|
|
5991 @findex hmouse-get-bindings
|
|
|
5992 @vindex file, hmouse-sh.el
|
|
|
5993 @vindex file, hmouse-reg.el
|
|
|
5994 @item How can I change the Smart Mouse Key bindings?
|
|
|
5995 @findex hmouse-shift-buttons
|
|
|
5996 Since the Smart Mouse Keys are set up for use under five different Emacs
|
|
|
5997 configurations, there is no easy way to provide user level
|
|
|
5998 customization. The command, @code{hmouse-shift-buttons}, can be used to
|
|
|
5999 select between shifted and unshifted Smart Mouse Keys. Any other mouse
|
|
|
6000 key binding changes must be done by editing the @code{hmouse-setup} and
|
|
|
6001 @code{hmouse-get-bindings} functions in the @file{hmouse-sh.el} and
|
|
|
6002 @file{hmouse-reg.el} files.
|
|
|
6003
|
|
|
6004 @vindex file, hmouse-key.el
|
|
|
6005 @vindex file, hui-window.el
|
|
|
6006 @vindex hkey-alist
|
|
|
6007 @vindex hmouse-alist
|
|
|
6008 The @var{hkey-alist} and @var{hmouse-alist} variable
|
|
|
6009 settings in @file{hui-mouse.el} and @file{hui-window.el} must be altered
|
|
|
6010 if you want to change what the Smart Keys do in particular contexts.
|
|
|
6011 You should then update the Smart Key summary documentation in the file,
|
|
|
6012 @file{hypb-mouse.txt}, and potentially the same summary in this manual.
|
|
|
6013
|
|
|
6014
|
|
|
6015 @item Missing Action Types
|
|
|
6016
|
|
|
6017 What if someone sends a mail message with a button for which I do
|
|
|
6018 not have the action type? Or a button whose link referent I can't access?
|
|
|
6019
|
|
|
6020 You receive an error that an action type is not defined or a link
|
|
|
6021 referent is not accessible/readable if you try to use the button. This
|
|
|
6022 is hardly different than trying to get through a locked door without a
|
|
|
6023 key; you try the doorknob, find that it is locked, and then realize that
|
|
|
6024 you need to take a different approach or else give up.
|
|
|
6025
|
|
|
6026 Like all communication, people need to coordinate, which usually
|
|
|
6027 requires an iterative process. If you get a mail message with a button
|
|
|
6028 for which you don't have the action type, you mail the sender and
|
|
|
6029 request it.
|
|
|
6030
|
|
|
6031 @cindex global button, modify
|
|
|
6032 @item How can I modify a number of global buttons in succession?
|
|
|
6033
|
|
|
6034 Rather than typing the name for each, it is quicker to jump to the
|
|
|
6035 global button file and edit the buttons there as you would any explicit
|
|
|
6036 buttons. By default, the ButFile/PersonalFile menu item takes you to
|
|
|
6037 the file where global buttons are saved.
|
|
|
6038
|
|
|
6039 @item Why is all the button data scattered across directories?
|
|
|
6040
|
|
|
6041 When you think of a hyper-space that you depend on every day, you don't
|
|
|
6042 want to have a single point of failure make you incapable of doing work.
|
|
|
6043 With Hyperbole, if some directories become unavailable for a particular
|
|
|
6044 time (e.g@. the filesystems on which they reside are dismounted) you can
|
|
|
6045 still work elsewhere with minimal effect. We believe this to be a
|
|
|
6046 compelling factor to leave the design with external button data storage.
|
|
|
6047
|
|
|
6048 This design also permits the potential addition of buttons to read-only
|
|
|
6049 media.
|
|
|
6050
|
|
|
6051 @item Why are action types defined separately from their implicit button types?
|
|
|
6052
|
|
|
6053 Any category of button can make use of an action type. Some action types
|
|
|
6054 are useful as behavior definitions for a variety of button categories,
|
|
|
6055 so all action types are defined separately to give them independence
|
|
|
6056 from those types which apply them.
|
|
|
6057
|
|
|
6058 For implicit button types that require a lot of code, it is useful to
|
|
|
6059 add a module that includes the implicit button type definition, its
|
|
|
6060 action type definition and supporting code.
|
|
|
6061
|
|
|
6062 @end table
|
|
|
6063
|
|
|
6064
|
|
|
6065 @node Future Work, References, Questions and Answers, Top
|
|
|
6066 @appendix Future Work
|
|
|
6067
|
|
|
6068 @noindent
|
|
|
6069 This appendix is included for a number of reasons:
|
|
|
6070
|
|
|
6071 @itemize @bullet
|
|
|
6072 @item
|
|
|
6073 to better allow you to assess whether to work with Hyperbole by
|
|
|
6074 providing sketches of possible additions:
|
|
|
6075 @item
|
|
|
6076 to direct further development effort towards known needs;
|
|
|
6077 @item
|
|
|
6078 and to acknowledge known weaknesses in the current system.
|
|
|
6079 @end itemize
|
|
|
6080
|
|
|
6081 @table @asis
|
|
|
6082
|
|
|
6083 Note that due to a lack of volunteers to further develop Hyperbole, much
|
|
|
6084 of this work may not be done. So if you want to see these features,
|
|
|
6085 encourage qualified people to volunteer.
|
|
|
6086
|
|
|
6087 @item Button Copying, Killing, and Yanking
|
|
|
6088 There is as yet no means of transferring explicit buttons among buffers.
|
|
|
6089 We realize this is a critical need. Users should be able to manipulate
|
|
|
6090 text with embedded buttons in ordinary ways. This will probably be
|
|
|
6091 implemented only for versions of Emacs 19 and higher. It will store the
|
|
|
6092 button attributes as text attributes within the buffers so that if a
|
|
|
6093 button is copied, its attributes follow. When a buffer is saved, the
|
|
|
6094 attributes also will be saved.
|
|
|
6095
|
|
|
6096 @item Trails
|
|
|
6097 Trails are an extension to the basic history mechanism presently offered
|
|
|
6098 by Hyperbole. Trails will allow a user to capture, edit and store a
|
|
|
6099 specific sequence and set of views of information for later replay by
|
|
|
6100 other users. Conditional branching may also be supported.
|
|
|
6101
|
|
|
6102 @item Outliner View Mode
|
|
|
6103 This will complement the outliner editing mode by using simple one
|
|
|
6104 character keys that normally insert characters to instead modify the
|
|
|
6105 view of an outline and to move around in it, for ease of study.
|
|
|
6106 Switching between view and edit modes will also be simple.
|
|
|
6107
|
|
|
6108 @item Storage of button data within button source files
|
|
|
6109 The current design choice of storing buttons external to the source file
|
|
|
6110 was made under the assumption that people should be able to look at
|
|
|
6111 files that contain Hyperbole buttons with any standard editor or tool
|
|
|
6112 and not be bothered by the ugly button data (since they won't be able to
|
|
|
6113 utilize the buttons anyway, they don't need to see or have access to
|
|
|
6114 them).
|
|
|
6115
|
|
|
6116 In many contexts, embedding the button data within the source files may
|
|
|
6117 be a better choice, so a provision which would allow selection of either
|
|
|
6118 configuration may be added. Here are some of the PROs and CONs of both
|
|
|
6119 design choices:
|
|
|
6120 @sp 1
|
|
|
6121
|
|
|
6122 @example
|
|
|
6123 @group
|
|
|
6124 POSITIVE NEGATIVE
|
|
|
6125
|
|
|
6126 Button data in source file
|
|
|
6127 Documents can stand alone. All edit operators have
|
|
|
6128 Normal file operations apply. to account for file
|
|
|
6129 structure and hide
|
|
|
6130 Simplifies creation and internal components.
|
|
|
6131 facility expansion for
|
|
|
6132 structured and multi-media
|
|
|
6133 files.
|
|
|
6134
|
|
|
6135 Button data external to source file
|
|
|
6136 Files can be displayed and Currently, bdata for
|
|
|
6137 printed exactly as they look. whole directory is
|
|
|
6138 No special display formatting locked when any bdata
|
|
|
6139 is necessary. entry is locked.
|
|
|
6140
|
|
|
6141 Button-based searches and
|
|
|
6142 database-type lookup operations
|
|
|
6143 need only search one file
|
|
|
6144 per directory.
|
|
|
6145 @end group
|
|
|
6146 @end example
|
|
|
6147 @sp 2
|
|
|
6148
|
|
|
6149 @item Forms-based Interfaces
|
|
|
6150
|
|
|
6151 This will allow one to create buttons more flexibly. For example, button
|
|
|
6152 attributes could be given in any order. Entry of long code sequences,
|
|
|
6153 quick note taking and cross-referencing would also be made easier.
|
|
|
6154
|
|
|
6155 @item Collaboration Support
|
|
|
6156
|
|
|
6157 From the early stages of Hyperbole design, collaborative work
|
|
|
6158 environments have been considered. A simple facility has demonstrated
|
|
|
6159 broadcast of button activations to a number of workstations on a local
|
|
|
6160 area network, so that one user can lead others around an information
|
|
|
6161 space, as during an online design review. (This facility was never
|
|
|
6162 adapted to the current Hyperbole release, however.) We shall do some
|
|
|
6163 work in specific collaborative mechanisms, but we also expect that
|
|
|
6164 others who concentrate in collaborative work will provide more extensive
|
|
|
6165 capabilities.
|
|
|
6166
|
|
|
6167 @end table
|
|
|
6168
|
|
|
6169 @node References, Key Binding Index, Future Work, Top
|
|
|
6170 @appendix References
|
|
|
6171
|
|
|
6172 @table @b
|
|
|
6173 @item [AkMcYo88]
|
|
|
6174 Akscyn, R. M., D. L. McCracken and E. A. Yoder. KMS: A
|
|
|
6175 Distributed Hypermedia System for Managing Knowledge in Organizations.
|
|
|
6176 @emph{Communications of the ACM}, Vol. 31, No. 7, July 1988, pp. 820-835.
|
|
|
6177
|
|
|
6178 @item [Bro87]
|
|
|
6179 Brown, P. J. Turning Ideas into Products: The Guide System.
|
|
|
6180 @emph{Proceedings of Hypertext '87}, November 13-15, 1987, Chapel Hill, NC.
|
|
|
6181 ACM: NY, NY, pp. 33-40.
|
|
|
6182
|
|
|
6183 @item [Con87]
|
|
|
6184 Conklin, Jeff. Hypertext: An Introduction and Survey. @emph{IEEE
|
|
|
6185 Computer}, Vol. 20, No. 9, September 1987, pp. 17-41.
|
|
|
6186
|
|
|
6187 @item [Eng68]
|
|
|
6188 Engelbart, D., and W. English. A research center for augmenting
|
|
|
6189 human intellect. @emph{Proceedings of the Fall Joint Computer Conference},
|
|
|
6190 33, 1, AFIPS Press: Montvale, NJ, 1968, pp. 395-410.
|
|
|
6191
|
|
|
6192 @item [Eng84a]
|
|
|
6193 Engelbart, D. C. Authorship Provisions in Augment.
|
|
|
6194 @emph{Proceedings of the 1984 COMPCON Conference (COMPCON '84 Digest)},
|
|
|
6195 February 27-March 1, 1984, San Francisco, CA. IEEE Computer Society Press,
|
|
|
6196 Spring, 1984. 465-472. (OAD,2250,)
|
|
|
6197
|
|
|
6198 @item [Eng84b]
|
|
|
6199 Engelbart, D. C. Collaboration Support Provisions in Augment.
|
|
|
6200 @emph{Proceedings of the AFIPS Office Automation Conference (OAC '84 Digest)},
|
|
|
6201 February, 1984, Los Angeles, CA, 1984. 51-58. (OAD,2221,)
|
|
|
6202
|
|
|
6203 @item [Fos88]
|
|
|
6204 Foss, C. L. Effective Browsing in Hypertext Systems.
|
|
|
6205 @emph{Proceedings of the Conference on User-Oriented Content-Based Text and
|
|
|
6206 Image Handling (RIAO 88)}, March 21-24, MIT, Cambridge MA. Centre de Hautes
|
|
|
6207 Etudes Internationales d'Informatique Documentaire, 1988, pp. 82-98.
|
|
|
6208
|
|
|
6209 @item [GaSmMe86]
|
|
|
6210 Garrett, N., K. E. Smith and N. Meyrowitz. Intermedia: Issues,
|
|
|
6211 Strategies, and Tactics in the Design of a Hypermedia Document System.
|
|
|
6212 @emph{Computer-Supported Cooperative Work (CSCW '86) Proceedings}, December
|
|
|
6213 3-5, Austin, TX, 1986, pp. 163-174.
|
|
|
6214
|
|
|
6215 @item [HaMoTr87]
|
|
|
6216 Halasz, F. G., T. P. Moran and R. H. Trigg. NoteCards in a
|
|
|
6217 Nutshell. @emph{Proceedings of the CHI and GI '87 Conference on Human Factors
|
|
|
6218 in Computing Systems}, Toronto, J. M. Carroll and P. P. Tanner, (editors),
|
|
|
6219 ACM: NY, NY, April 1987, pp. 45-52.
|
|
|
6220
|
|
|
6221 @item [Har88]
|
|
|
6222 Harvey, G. @emph{Understanding HyperCard.} Alameda, CA: SYBEX, Inc.,
|
|
|
6223 1988.
|
|
|
6224
|
|
|
6225 @item [KaCaLoLa92]
|
|
|
6226 Kaplan, S., A. M. Carroll, C. Love and D. M. LaLiberte.
|
|
|
6227 @emph{Epoch 4.0 Manual.} Department of Computer Science, University of
|
|
|
6228 Illinois, Urbana, March 1992.
|
|
|
6229
|
|
|
6230 @item [KaKaBeLaDr90]
|
|
|
6231 Kaplan, S. J., M. D. Kapor, E. J. Belove, R. A. Landsman, and
|
|
|
6232 T. R. Drake. AGENDA: A personal Information Manager. @emph{Communications
|
|
|
6233 of the ACM}, No. 33, July 1990, pp. 105-116.
|
|
|
6234
|
|
|
6235 @item [Nel87a]
|
|
|
6236 Nelson, T. H. @emph{Computer Lib/Dream Machines.} MicroSoft Press,
|
|
|
6237 Redmond, WA, 1987.
|
|
|
6238
|
|
|
6239 @item [Nel87b]
|
|
|
6240 Nelson, T. H. @emph{Literary Machines, Edition 87.1}. Available
|
|
|
6241 from the Distributors, 702 South Michigan, South Bend, IN 46618, 1987.
|
|
|
6242
|
|
|
6243 @item [NoDr86]
|
|
|
6244 Norman, D. A. and S. W. Draper, editors. @emph{User Centered System
|
|
|
6245 Design.} Lawrence Erlbaum Associates: Hillsdale, New Jersey, 1986.
|
|
|
6246
|
|
|
6247 @item [Shn82]
|
|
|
6248 Shneiderman, B. The future of interactive systems and the emergence
|
|
|
6249 of direct manipulation. @emph{Behavior and Information Technology}, Vol. 1,
|
|
|
6250 1982, pp. 237-256.
|
|
|
6251
|
|
|
6252 @item [Sta87]
|
|
|
6253 Stallman, R. @emph{GNU Emacs Manual.} Free Software Foundation,
|
|
|
6254 Cambridge: MA, March 1987.
|
|
|
6255
|
|
|
6256 @item [Tri86]
|
|
|
6257 Trigg, R., L. Suchman, and F. Halasz. Supporting collaboration in
|
|
|
6258 NoteCards. @emph{Proceedings of the CSCW '86 Conference}, Austin, TX,
|
|
|
6259 December 1986, pp. 147-153.
|
|
|
6260
|
|
|
6261 @item [TrMoHa87]
|
|
|
6262 Trigg, R. H., T. P. Moran and F. G. Halasz. Adaptability and
|
|
|
6263 Tailorability in NoteCards. @emph{Proceedings of INTERACT '87}, Stuttgart,
|
|
|
6264 West Germany, September 1987.
|
|
|
6265
|
|
|
6266 @item [Wei92]
|
|
|
6267 Weiner, B. @emph{PIEmail: A Personalized Information Environment
|
|
|
6268 Mail Tool.} Department of Computer Science Masters Project, Brown
|
|
|
6269 University: Providence, RI, May 10, 1992.
|
|
|
6270
|
|
|
6271 @item [YaHaMeDr88]
|
|
|
6272 Yankelovich, N., B. J. Haan, N. Meyrowitz and S. M. Drucker.
|
|
|
6273 Intermedia: The Concept and the Construction of a Seamless Information
|
|
|
6274 Environment. @emph{IEEE Computer}, Vol. 21, No. 1, January 1988, pp. 81-96.
|
|
|
6275
|
|
|
6276 @item [YoAkMc89]
|
|
|
6277 Yoder, E. A., R. M. Akscyn and D. L. McCracken. Collaboration in
|
|
|
6278 KMS, A Shared Hypermedia System. @emph{Proceedings of the 1989 ACM Conference
|
|
|
6279 on Human Factors in Computer Systems (CHI '89)}, April 30-May 4, 1989,
|
|
|
6280 Austin, TX, ACM: NY,NY, 1989, pp. 37-42.
|
|
|
6281
|
|
|
6282 @end table
|
|
|
6283
|
|
|
6284
|
|
|
6285 @c ***************************
|
|
|
6286 @c Indices
|
|
|
6287 @c ***************************
|
|
|
6288
|
|
|
6289 @node Key Binding Index, Code and File Index, References, Top
|
|
|
6290 @unnumbered Key Binding Index
|
|
|
6291
|
|
|
6292 @printindex ky
|
|
|
6293
|
|
|
6294 @node Code and File Index, Concept Index, Key Binding Index, Top
|
|
|
6295 @unnumbered Code and File Index
|
|
|
6296
|
|
|
6297 @printindex fn
|
|
|
6298
|
|
|
6299 @node Concept Index, , Code and File Index, Top
|
|
|
6300 @unnumbered Concept Index
|
|
|
6301
|
|
|
6302 @printindex cp
|
|
|
6303
|
|
|
6304 @page
|
|
|
6305 @summarycontents
|
|
|
6306 @contents
|
|
|
6307 @bye
|
