print-friendly NBWin copy of the Code List (69k).Customizing the Nota Bene keyboard with "run" programs
Greg Polly
This document is designed for people who would like to take advantage of Nota Bene's facility for user-designed macros but have neither the time nor inclination to learn the nuances of XPL programming. In fact, anyone can write a run file in just a few minutes without any programming expertise (nota bene: I have none.) The brief tutorial below should allow you--in one session-- to create a number of simple macros that duplicate commandline functions. Once you've learned the basic procedure, you'll be able to apply it to commands that you'd like to automate.
These instructions are written for NB Windows. There are a few extra procedures for writing run files in NB-DOS. See section 8.
You may want to print out this file to consult as you try the examples.
1. About run files
A "run" program is a simple program that is created in a plain textfile. It contains a sequence of command codes and is saved with an .run suffix. It can be run from the command line by typing "run" followed by the filename. Better yet, the run file can be assigned to a key on the Shift + Alt tier of the keyboard (the Alt tier in NB-DOS) so that it will be executed when the key is pressed.
2. How to create a run file in NB-Windows: four examples
The best way to learn how to make a run file is simply to make one. If you're working in NB Windows, just follow the instructions for the four examples below, which take full advantage of the confidence-building power of mundane repetition.
Example #1: Creating a macro for inserting today's date
Nota Bene has a command line function that will insert the current date in a text file. Open a blank file and try it now:
Push F9
Type on the command line: today
Push F10
As you can see, today's date is deposited at the cursor in the currently open text file.
This command line sequence is very quick and convenient, but we can make it even more efficient with a one-key macro. Here's how to write a run file that contains the code for the commandline sequence you just executed.
1. Open a blank file without formatting.
2. Follow these instructions to write the run file:
Push F9
Type on the command line: pfunc BC
Push F10
(You should see BC appear in the textfile.)
Type in the textfile: today
Push F9
Type on the commandline: pfunc XC
Push F10
(You should see XC appear in the textfile.)
Your run file should now read BC today XC.
3. Save the file in the NBWIN directory as date.run.
Here's what you just did. You used the "put function" command (pfunc) to insert the command code BC into the run file. BC is the code for the F9 key--it means "Blank Command Line." You typed "today" into the file. You then used the put function command to insert the command code XC into the file. XC is the code for the F10 key--it means "Execute Command." Finally, you saved the file with an .run extension so that Nota Bene would recognize it as an executable program.
4. Now, use the loadprogram command to load this run file onto the D key:
Push F9
Type on the command line: ldpm c:\nbwin\date.run,d
Push F10
Note the syntax of this command: loadprogram (ldpm), the pathname of your file, a comma, and the key onto which you are loading the run file. If you've executed the commands correctly you should see "Done" appear on the status bar.
That's it! Press F9 once more to clear the command line. Call or create a text file and try inserting today's date by pressing Shift + Alt + D.
Example #2: Creating a macro for calling the keyboard table
Here's another macro using the same principle.
Suppose you want to create a macro that will call a frequently-used file to the screen with one keystroke. I've chosen the chart of keyboard functions chart that NB 5.0 provides.
The file is named nbkey.key and it's in the NBWIn\Users\Default subdirectory. Call it to the screen from the commandline with the "call" command.
Push F9
Type on the command line: ca c:\nbwin\users\default\nbkey.key
Push F10
(After you've examined the keyboard file, close it.)
Now write a run file that will duplicate this commandline call.
1. Open a blank file.
2. To place a command function in a run file, use the "putfunction" command (pfunc).
Push F9
Type on the command line: pfunc BC
Push F10
Type in the command to call the file: ca c:\nbwin\user\default\nb.key
Push F9
Type on the command line: pfunc XC
Push F10
Your run file should now look like this: BC ca c:\nbwin\user\default\nb.key XC.
Here's what you did: You used the putfunction (pfunc) command to place a BC command in the run file (Blank Command Line--the equivalent of F9). You typed the instruction to call (ca) the nb.key chart, using the file's pathname. You used the putfunction (pfunc) command to insert an XC command into the run file (Execute Command--the equivalent of F10). Finally, you saved the file with a .run extension, which tells Nota Bene that it's an executable program.
3. Save the file in the NBWIN directory as key.run.
4. Now assign the run file to a key with the loadprogram command.
Push F9
Type on the command line: ldpm c:\nbwin\key.run,k
Push F10
Note the syntax of this command: loadprogram (ldpm), the pathname of the run file, a comma, and the key to which you are assigning the command. If you've executed the commands correctly you should see "Done" appear on the status bar.
5. Hit F9 once to clear the command line and then try your macro. Type Shift + Alt + K, and you should see the keyboard chart pop up. You can use this same design to customize the call of any frequently-used file.
Example #3: Creating a macro for abandoning a file
You can quickly abandon a file in Nota Bene with the command line sequence F9 ab F10.
You can make a macro for this sequence with a run file.
Push F9
Type on the command line: pfunc BC
Push F10
In the textfile, type: ab
Push F9
Type on the command line: pfunc XC
Push F10
The text in the run file should read: BC ab XC
Save the file in the NBWIN directory as abandon.run. Then load it onto the A key:
Push F9
Type on the command line: ldpm c:\nbwin\abandon.run,a
Push F10
Now try calling the keyboard list with Shift + Alt + K and then closing it with Shift + Alt + A. The abandon macro is most useful in conjunction with call macros for quick peeks at a frequently-used file.
In some cases, the abandon command will call up a dialogue box asking if you want to abandon changes. You’ll usually want the default value of "yes"--if you’re abandoning a file, you don’t care about saving it--so just hit the enter key. This adds another keystroke, but this two-stroke sequence is still faster than reaching for the mouse or typing the full sequence on the command line.
You should now grasp the basic principle of creating a run file that duplicates any F9-F10 commandline sequence.
Example #4: Creating a macro to boldface the current line
The last three macros were variants of the sequence BC command XC, which duplicates F9-F10 commandline actions. You can also write runfile macros for keystroke sequences that involve key functions as well as command line actions.
Here is a macro that defines the current line of text and places it in boldface.
1. Open a blank file without formatting.
2. Create the run file:
Push F9.
Type on the command line: pfunc DL
Push F10
Push F9
Type on the command line: pfunc BC
Push F10
Type in the file: md bo+
Push F9
Type on the command line: pfunc BC
Push F10
Type in the file: md bo-
Push F9
Type on the command line: pfunc XC
Push F10
Push F9
Type on the command line: pfunc ES
Push F10
The finished macro should read:
DL BC md bo+ XC BC md bo- XC ES
Here are the keystrokes that you've duplicated in this macro. Press F12 to define the line (DL); press F9 to go to the command line (BC); type the command to turn boldface on (md bo+); press F10 to execute the command (XC); press F9 again (BC); type the command to turn boldface off (md bo-); press F10 to execute the command (XC); and press the escape key to release the highlighting (ES).
3. Save the file in the NBWIN directory as boldline.run.
4. Now load the program onto the B key with the loadprogram command:
Push F9
Type on the command line: ldpm c:\nbwin\boldline.run,b
Push F10
5. Try the macro. Place the cursor in a single line of text (like a heading) and press Shift + Alt + B. The line containing the cursor should turn to boldface.
Notice that this example uses the codes assigned to particular keys (F12, ESC). If you know the codes assigned to particular keys, you can write macros for numerous keystroke combinations--not just commandline functions.
4. "How do I find out what the command codes are?"
I've reproduced the list of command codes and commandline actions from Tony Woolzey's Customization and Programming Guide in an appendix to this text. Some of these NB-DOS commands may not work in NB-WIN or may require further knowledge of XPL that I don't have.
I'm also not sure that all of the codes are correctly listed in any one place, so be aware of other resources that you can use:
You can use search Nota Bene's help files to find command line equivalents of program functions that interest you.
The Nota Bene program itself contains a list of command codes buried rather obscurely in a file called nb.dlg. It's in the /nbwin directory. You'll have to page far down into the file to find the table.
The keyboard table (nb.kbd) contains the (unannotated) codes assigned to all the keys, but the keys are simply numbered 1-88 without other identification.
Rick Penticoff's keyboard tables will show you the code assigned to a particular key. If you want to create a run file that duplicates a series of keystrokes, simply look up the keys on Rick's charts and note the codes assigned to them.You can find the tables at http://users.moscow.com/rpenticoff/nb/kbds/index.htm. (At the same site you can find Tony Woolzey's complete and much more complicated Customization and Programming Guide.)
Try the macro recorder which is explained in the next section. It's an undocumented residue from NB-DOS, and it isn't fully functional in NB WIN. It's not reliable enough to create run files, but it can sometimes give you the correct code for a key. Even when it doesn't, it can sometimes provide clues for the correct code which you can enter manually with the pfunc command.
5. The macro recorder
NB-DOS came equipped with a macro recorder that was toggled on and off by pressing control + scroll lock. Once you toggled on "programming mode," you could press any key and deposit the command code for that key into a textfile. You could type the exact sequence that you wanted in a macro, save it as a run file, and assign it to a key.
This function seemed to be gone in NB 5.0, and it's nowhere mentioned in any of the documentation. The good news is that it's still there, assigned to a different key (control+shift+alt+colon). The bad news is that it doesn't work for all functions and occasionally deposits an older code which won't function in NB Windows. However, until NB-Windows restores it you can still use it to provide clues to the correct command codes.
To see how the macro recorder works, open a blank textfile and press control+shift+alt+colon. Then press some keys that you would use for program functions (the F keys, the keys for defining, cutting, pasting, and so on.) You'll see that most of these keys deposit their command codes in the file. If you put the cursor on a command code and click the mouse, you should see a description of the command code's function on the status bar--a helpful plus.
Toggle the programming mode off again with control+alt+shift+colon. Now the keys perform their functions rather than recording them.
Most of the commands that contain ampersands will not function in NBWin. However, they sometimes provide clues to the correct command code.
So far as I can tell, the macro recorder is not reliable for determining the codes for keys associated with Orbis, Ibid or keys that run Windows defaults (e.g., the keyboard shortcuts for bold and italic).
So far as I can tell, the macro recorder is reliable for determining the codes on the home-end-pageup-pagedown island, the arrows, and backspace and delete.
6. Assigning text to keys
In addition to assigning run files to keys as described above, you can assign plain text to any key--a word, a phrase, or a larger piece of boilerplate text. The procedure for assigning text to a Shift + Alt key is:
1. Define the text to be assigned to a key.
2. Press Alt+F1. A chart showing all of the letters and numbers will appear on your
screen.
3. Press one of the letters or numbers on the chart or type any letter or any single digit number (using the numbered keys at the top of the keyboard, not the number pad on the right of the keyboard)
4. To insert the phrase, press Shift+Alt+the letter or number you chose in step 3.
7. Phrase Libraries
The compilation of all your keyboard shortcuts is called a phrase library. The default phrase library can be found in c:\nbwin\users\default.lib. This phrase library will remain in place until you change it, reloading each time you boot Nota Bene.
Suppose you become exuberant in your runfile programming. What happens when you run out of keys? Nota Bene supports the creation of multiple phrase libraries. You can save your current phrase library to a .lib file with the "save library" command (salib), clear the current library from the keys with the "clear library" command (clrlib), and begin defining a new phrase library--perhaps one that is specific to a particular project or a particular set of files. You can then save this new library to its own file.
The "load library" command (ldlib) allows you load any library you wish at any time.
Here are some examples of the these commands in action:
F9 salib c:\nbwin\mainphrs.lib F10
F9 clrlib F10
F9 ldlib c:\nbwin\dissphrs.lib F10
If you switch phrase libraries often, you can of course create a runfile macro to execute the switch with a single keystroke!
Multiple phrase libraries provide more flexibility than hard-coding the commands to keys in a keyboard table.
8. How to create a run file in NB-DOS
The procedure for creating a run file in NB-DOS involves just a couple of variations. Files must be opened, called and saved with special commands.
Open a file from the commandline with the command "new program": F9 nep F10
Save a file from the commandline with the command "save program": F9 sap F10
If you edit a run file, call it with the command "call program": F9 cap F10
In NB-DOS, run files are executed with Alt + key rather than Shift + Alt + key.
9. A note on the BX and Q2 commands
The BC command (F9) and the XC command (F10) are a basic constituent of many run files.
In NB 5.0 (though not in NB-DOS) there is an alternative set of commands which duplicate the functions of BC and XC but bypass the commandline: BX (Blind eXecute) and Q2. According to XPL gurus on the list, these commands are faster, less problematic, and preferred by programmers. You may want to substitute BX and Q2 for BC and XC in your run files. The files should work the same way--you just won't see anything on the command line. (These commands operate as pairs, so be sure not to mix and match them.)
I've used BC and XC in the examples because this set of commands works in both NB Win and NB DOS.
10. Tips and (simple) troubleshooting
Tips
The examples above save the run files in the /NBWIN directory. If they get lost among the clutter there, you can get a list of the run files alone by using a filter in the Open File dialogue box. Just type *.run in the window labelled "Path and File Specification." The dialogue box will filter out a list of your run files.
You can also place your run files in a separate directory. Ifyou place them in a subdirectory in NBWIN, be aware that you'll be typing long pathnames every time you load a program. A directory under the root like c:\run will save you some typing. Be aware that if you move any already-created run files to a new location, you'll need to rewrite the pathnames in the run files themselves.
If you're creating and loading a lot of run files, you can save yourself some typing with a macro. Create a macro that types the first part of the loadprogram command on the command line:
BC ldpm c:\nbwin\
Then assign it to a key. Invoking the macro will leave the uncompleted commandline sequence on the command line, with the cursor waiting for you to complete it with the filename, comma, and assigned key.
A shortcut for the "put function" command--F9 pfunc-- is control + colon.
Troubleshooting
Here are a few things to keep in mind if your macros aren't working.
If a usually-operative macro seems dead, try hitting the F9 key. Clearing the command line often makes them work again. This seems to be true even for run files created with the BX and Q2 commands.
Remember that although a run file looks like a text file, it's not composed of text. Program command codes must be entered with the pfunc command. Merely typing or pasting the two-letter codes as text will not create a working program.
If a macro doesn't work, try rewriting it with BC and XC instead of BX and Q2, or vice
versa.
It's easy to mistype pathnames or to confuse the textfile with the run file and write the wrong suffix. Check the paths of your commands in both the run file itself and the loadprogram operation.
If you're working in NB-DOS, remember that you should create, call and save run files from the command line with nep, cap, and sap if you intend to use the macro recorder.
If you change a run file in any way, you must reload it onto a key before it will take effect. Until they are explicitly replaced, run file assignments remain to haunt keys like ghosts--even after the run file itself is deleted.
Long filenames in Windows 95 and 98 present a problem for run files. You should name all of your run files in the old 8.3 style. If you have filenames or directory names longer than 8 characters, use the "true" DOS name for the file, which is created with the first six letters of the file (excluding spaces), a tilde, and a number. (Thus real big chapter.nb becomes realb~1.nb and real big file.nb becomes realb~2.nb. The standard Windows directory "Program Files" becomes progra~1.)
There's a second related problem with long filenames that's specific to Nota Bene: although the tilde key in the upper left hand corner of many keyboards will write a tilde in a textfile, it does not write a tilde on Nota Bene's command line! To write a tilde on the command line, use control + hyphen.
View a list of codes discussed in this Tutorial. Or download a print-friendly NBWin copy of the Code List (69k).
Download a NBWin version of this tutorial (12k).
Comments or suggestions welcome. Write Greg at polly@denison.edu.