Category : Word Processors
Archive   : QREF.ZIP
Filename : README.QRF

**************** QRef - Copyright 1991 Bob Chesley **********************
Thanks for downloading or otherwise acquiring this Brief 3.1 macro package.

Release is Version 1.00A

[NOTE - Brief version 3.1 was used to build this macro]

1) To install QRef for your use.

Simply copy the self extracting archive file QREF.EXE into your
Brief macro directory and execute it to extract the compiled macro
(QREF.CM) and the sample menu file (sample.qrf).

2) To use a supplied menu (*.qrf) file.

Set the DOS environment variable QFILE with the full path to the
menu file you wish to use with QRef as in:

set QFILE=c:\bin\brief\macros\sample.qrf[ENTER]

The supplied .qrf menu file "sample.qrf" is a partial menu file
for the Vermont Views version 3.0 text interface libraries from
Vermont Creative Software.

This can be set on the fly, in a batch file by project subdirectory
if you need to customize QRef's use by project, or in your
autoexec.bat file.

You will need to load the compiled macro after setting the QFILE
variable appropriately in one of the following ways:

a) Set the macro up to load automatically by including it in
your initials macro as follows:

;** Initials macro.
;** Use this macro for additional customization.
(macro BC
(
;** Put your changes here.
(autoload "qref")
(assign_to_key "" "qref")
(return)
)
)

Note that the above macro code loads QRef and assigns it
to function key F2 for access. This is the preferred method
of use.

b) Load QRef on the fly by using to load the compiled macro
and then using or an assigned key to pop the menu up.

3) To prepare and use your own menu (*.qrf) file.

The basic layout of a line in the menu file is 1) whatever
text should appear in the popup menu (i.e. function name without
parentheses or parameters, 2) a delimiting semicolon(;), and
on the remaining portion of the line whatever should be inserted
when a given line is selected from the popup menu. Note that in
the supplied files the assumption is that we want the statement
terminating semicolon as the last character of the insertion text.
The popup menu window is set to allow display of up to 20 characters
so any display text should not exceed this. There is no such limit
for the insertion text except for the end of the line.

4) Explanation of the insertion logic/How to use QRef.

The insertion logic looks in the insertion text
for either 1) a set of parentheses without anything in between
(i.e. "()"), or no left parenthesis (i.e. "(") and if either of
these conditions are met it supplies an enter key after the
insertion string is inserted thereby moving to the next line.

If neither of these conditions are met we have an opening left
parenthesis and we do not have a function with no parameters
so the macro inserts the insertion string and moves the cursor
to the first position after the opening parenthesis to facilitate
the editting of the "dummy" or mnemonic parameters.

Note that the first case should handle any non-function call
types of text to insert.

Once the menu is popped up first character search is also enabled.
For example, if you type an "e" after popping up the menu and there
are five lines in which the display text begins with an "e" the
cursor will move to the first of these and the list in the menu
window will adjust to display this entry. Subsequent "e" characters
will cycle the cursor and the currently active line through the
other four matching entries and another "e" will move back to the
first entry. The search is not dependent on a sorted menu file and
this fact could be exploited in developing or customizing a menu
file to reflect your needs (i.e. ordering the entries in order of
frequency of use rather than in a strict alphabetical order).

The , , , and keys work as expected and
the arrow keys will scroll the displayed menu in the popup window.

5) Error handling.

QRef will yield the following error messages under the detailed
conditions:

a) "QFILE variable not set in environment" for cases where the
DOS environment variable QFILE is not set at all when QRef is
invoked.

b) "Unable to locate menu file found in QFILE" for the case where
the DOS environment variable QFILE is set but a valid file is not
found based on that setting.

Note that failing to follow the menu file formatting instructions
detailed in section #3 above will likely result in incorrect or
erratic behavior including less meaningful error returns from the
Brief back end.

6) How to contact me.

Contact Bob Chesley via Compuserve ID #75470,3677

OR write to:

15B Bay Road
Shelburne, VT 05482

NOTE - your suggestions or notice of problems are greatly
appreciated and will be considered as QRef is enhanced.

7) Shareware statement of purpose and request for consideration.

QRef was created to address the problem of using
function library products resulting in too many functions and
/or parameters to remember or look up. I don't suffer under the
illusion that this macro is any great feat of programming, but
I do believe that it has the potential, especially when combined
with a pre-formatted library product menu file, to save any
programmer using one of the supported libraries lots of
keystrokes and considerable time. It was designed to allow
you to control how it works by modifying the menu file in use
to suit your own needs. For example, you can eliminate unused
menu lines, add to the menu, and reorder the occurrence of menu
lines to put the most frequently used functions at the top of the
menu.

Let me know what library products you would like to see support for!

From my perspective I see the value that I bring to your efforts
as a Brief and library product user as serving as a clearing house
for the various library product menu files (i.e. through release
cycles of the various libraries). As such, I would request that
if you find QRef useful that you send me the modest sum of $10.00
US funds preferably in the form of a personal or company check.
If you want source code to the macro please:

a) Include your Compuserve ID so that I can send the code
via CIS.

OR

b) Include a 3.5" diskette along with return postage and
a mailer.

:-)...