8. Rolodex

Hyperbole includes a complete, advanced rolodex system, Wrolo, for convenient management of hierarchical, record-oriented information.

Hyperbole buttons may be included within rolodex records and then manually activated whenever their records are retrieved.

See the description at the top of the `wrolo.el' file for details on programmatic interfacing to the rolodex. The following subsections explain use and basic customization of the rolodex.

8.1 Rolo Concepts

The rolodex manages and searches rolodex files. A rolodex file consists of an optional header which starts and ends with a line of equal signs (at least three equal signs starting at the beginning of a line), followed by any non-negative number of rolodex records. You must manually add a header to any rolodex file if you want it to have one.

Here is an example of a simple rolodex file.

==================================================================
                        PERSONAL ROLODEX
<Last-Name>, <First>  <Email>        W<Work#>       F<Fax#>
==================================================================
*   Smith, John       <js@hiho.com> W708-555-2001  F708-321-1492
        Chief Ether Maintainer, HiHo Industries
        10/24/95

We call rolodex records, entries. Entries begin with a delimiter, some number of `*' characters at the beginning of a line. Entries may be arranged in a hierarchy, where child entries begin with one more `*' characters than do their parents. Top level entries begin with a single `*'.

Beyond this initial delimiter, entries are completely free-form text. It is best to use a "lastname, firstname" format, however, when adding contact entries into a rolodex. Then the rolodex system will automatically keep your entries alphabetized as you enter them. You'll also be able to sort them whenever you desire.

Any search done on the rolodex scans the full text of each entry. During a search, the rolodex file header separator lines and anything in between are appended to the buffer of matched entries before any entries are retrieved from the file. Whenever an entry is matched, it and all of its descendant entries are retrieved. If your Emacs version supports textual highlighting, each search match is highlighted for quick, visual location.

For example, a search on "Company" could retrieve the following:

==================================================================
                        COMPANY ROLODEX
==================================================================
*    Company
**     Manager
***      Underlings

Thus, searching for Company retrieves all listed employees. Searching for Manager turns up all Underlings.

8.2 Rolo Menu

The Rolo/ menu entry on the Hyperbole top-level menu provides the user interface to the rolodex. The rolo menu provides access to the following commands:

Menu Item       Command               Description
====================================================================
Add             rolo-add              Adds a rolodex entry
Display         rolo-display-matches  Displays last matches again
Edit            rolo-edit             Edits an existing rolodex entry
Info                                  Displays Rolodex manual entry
Kill            rolo-kill             Removes an entry from the rolodex
Mail            rolo-mail             Mail to address following point
Order           rolo-sort             Sorts all levels in rolodex
RegexFind       rolo-grep             Finds all entries containing
                                        a regular expression
StringFind      rolo-fgrep            Finds all entries containing
                                        a string
WordFind        rolo-word             Finds all entries containing
                                        a string of whole words
Yank            rolo-yank             Inserts first matching rolodex
                                        entry at point
====================================================================

A prefix argument used with either of the find commands listed above limits the search to a maximum number of matches given by the argument. The search is terminated whenever that number of matches is found.

For any of the above commands that prompt for a name, you may use the form parent/child to locate a child entry below a parent entry. So for a rolodex which looked like so:

*    Company
**     Manager
***      Underlings

You could edit the Underlings entry by identifying it as Company/Manager/Underlings. Do not use this hierarchical notation in search expressions since the whole rolodex will be searched anyway. Thus, "Underlings" as a search pattern will find an entry containing "Underlings" at any level in a hierarchy, like so:

***      Underlings

8.3 Rolo Keys

Use the {e} key to edit the entry at point within the rolodex source file.

After a rolodex search is performed, point is left in the rolodex match buffer, `*Rolodex*', which uses wrolo-mode to simplify browsing many rolodex matches. Press {?} when in the match buffer for a summary of available keys.

If your Emacs version supports textual highlighting, each search match is highlighted for quick, visual location. {TAB} moves point forward to successive spans of text which match the search expression. {M-TAB} or {r} moves point backward to earlier matches. These keys allow you to quickly find the matching entry of most interest to you if your search expression failed to narrow the matches sufficiently.

If you want to extend the match expression with some more characters to find a particular entry, use {M-s}, which performs an interactive search forward for the match expression. You can add or delete characters to this expression to find different occurences. {C-r} will reverse the direction of the search.

Single key outlining commands are also available for browsing matches. If your search matches a large number of entries, use {t} to get a top-level overview of all the entries. Each entry is collapsed so that only its first line shows. Press {s} to show (expand) the entry at point. Use {h} to hide (collapse) the entry again. Press {a} to expand all entries in the buffer.

Many other keys are defined to help you move through matching entries.

b

Move to the previous entry at the same level as the current entry.

f

Move to the next entry at the same level as the current entry.

n

Move to the next entry at any level.

p

Move to the previous entry at any level.

u

Move the the previous entry one level up.

.

<

Move to the beginning of the buffer.

,

>

Move to the end of the buffer.

DEL

Scroll backward a windowful.

SPC

Scroll forward a windowful.

Once you have found an entry of interest and you want to remove the rolodex match buffer, use {q} to quit. This will restore your current frame to its state prior to the rolodex search.

8.4 Rolo Settings

If textual highlighting is available in your Emacs on your current display type, the rolodex uses the value of rolo-highlight-face as the face to use to highlight search matches.

The buffers containing the rolodex files are not killed after a search on the assumption that another search is likely to follow within this Emacs session. You may wish to change this behavior with the following setting: (setq rolo-kill-buffers-after-use t).

After an entry is killed, the modified rolodex file is automatically saved. If you would rather always save files yourself, use this setting: (setq rolo-save-buffers-after-use nil).

When adding an entry from within a buffer containing a mail message, the rolodex add function will extract the sender's name and e-mail address and prompt you with the name as a default. If you accept it, it will enter the name and the email address using the format given by the rolo-email-format variable. See its documentation if you want to change its value.

The files used in any rolodex search are given by the rolo-file-list variable, whose default value is ("~/.rolodex.otl"), so that searches initially scan only your personal rolodex. Any entries added to this list should be file pathnames. If a file in the list does not exist or is not readable, it is skipped. Files are searched in the order in which they appear in the list. In general, you should leave your personal rolodex file as the first entry in the list, since this is the only file to which the rolo menu Add command adds entries.

The rolodex entry start delimiter is given by the regular expression variable, rolo-entry-regexp, whose default value is "^\*+".

A rolodex file may begin with an optional header section which is copied to the match display buffer whenever any matches are found during a search. The start and end lines of this header are controlled by the regular expression variable, rolo-hdr-regexp, whose default value is "^===". This allows lines of all equal signs to visually separate matching entries from multiple files retrieved from a single search.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.