Customization & Programming Guide by Tony Woozley Revised for Nota Bene 8.0 by Mary Bernard This revised edition is dedicated to Tony Woozley, mentor and friend, and to the memory of Dorothy Day Preface to the Revised Edition i Preface to the Revised Edition of the CPG The Customization and Programming Guide is not the work of one person or even of two people. Some of it has been around since Nota Bene 1, such as the examples using ‘WEBER.DOC’ in Chapter 4. Some of it may have come from a XyWrite manual. XyWrite is the word-processing program from which Nota Bene derived. Like NB it crossed the DOS barrier and became a Windows program; unlike NB, it is no longer commercially available. (Nota Bene and XyWrite are extremely similar; they both use the XyWrite Programming Language—XPL. NB uses it less in Windows than in DOS versions, but there are current examples in the *.AUX files in the main NB program folder. All but a few XyWrite codes (mostly DOS-related) work in NBWin.) The first three versions of Nota Bene had a terse XPL programming section, the Customiza- tion and Programming Guide (CPG). NB 4, released in 1993, had a superb manual, the Big Black Book, but no programming guide. However, the company asked Tony Woozley, a retired professor of philosophy at the University of Virginia, to revise and update the old Guide. Tony rewrote and expanded it. In his hands it became lucid, elegant and informative, a true guide for the beginner as well as a work of reference for more advanced XPL program- mers. Nota Bene became a Windows program in 1998, with version 5.0 of the program. There was still no programming section in the manual, now called Help, and online rather than printed. XPL still worked (and works) in NBWin, though some user programs written for NB DOS needed minor revision. Tony’s version of the CPG needed revising, too. Almost all the information about XPL was still valid, but a few older codes weren’t, and it had whole chap- ters on NB DOS features that didn’t work in NBWin, such as function OV. Eight years late, here is a revision of the CPG manual for NBWin, up to date for version 8. It is still largely Tony’s Guide; I have tried to match the tone and spirit of his version, insofar as possible. I want to thank Carl Distefano for letting me include excerpts from his end of our email cor- respondence as Chapter 10, a ‘Miscellany of XPL Information,’ and Robert Holmgren for letting me include his ‘Compendium of XyWrite/NB Variables’ as Chapter 9. I owe them both thanks for their illuminating answers to my XPL questions over the past several years; and I especially want to thank Robert for debugging and hastily editing this file at the last moment. I am grateful to the many members of the Nota Bene Users’ list whose answers to my ques- tions have helped me to make the Guide as accurate as possible. Particular thanks are due to Jukka-Pekka Takala, Joel Lidov, Michael Norman Jannik Lindquist and Rick Penticoff; and ii Preface to the Revised Edition to Steve Siebert, creator and chief programmer of Nota Bene, who answered questions about codes while getting NB8 out of beta. I’d like to thank him and Anne Putnam, president of Nota Bene, for letting me add information about customization and programming, and links to this Guide and other XPL resources, to NB8 online Help. Printing the CPG The Guide is carefully formatted for printing on both European A4 and American 8½" x 11" paper. Each page therefore ends with a hard page break. If you change them, pages and tables may break in awkward places. If you have downloaded only the PDF version of the CPG, you may want to download CPG.NB as well. A few pages contain actual XPL code, which you can view in CPG.NB by changing to Codes View—which of course you can't do with the PDF. Notes on the text of the CPG I have not changed Tony Woozley’s prefatory note to the DOS version except to update his email address and add a footnote about files. Italicised notes in the text. These are brief supplements to information that has survived otherwise unchanged from the DOS version of the Guide. Faux program codes in the text Since the CPG is formatted to be printable, function codes are represented by uppercase character in boldface (e.g., BX) and command brackets by Euroquotes (e.g., «SV01,Y»). You cannot copy and paste these characters into a file and run the file as a program. You can copy/paste them, but you must then change to Show Codes View, eliminate the strings that look (for instance) like: «MB+BO»BX«MDNM», and enter a BX code by doing ‘pfunc bx’. You can then do a global change of all « and » characters to command brackets (on Ctrl+, [Ctrl + comma] and Ctrl+. [Ctrl + period/full stop]). It is actually much easier simply to rewrite the program in real code, using the pfunc key and the keys that enter true command brackets. Updates to the newGuide With luck, the information in this version will be valid for a good while. I maintain an unofficial list of all the keyboard and programming codes (or all that I can find) that are valid in Nota Bene for Windows. As of July 2006, the entire list is included in Chap- ter 8 of the CPG. I shall update the list whenever an update of NB includes a significant amount of new code, send it to Rick Penticoff for posting on his NB Users’ website, and notify the NB List (see below) that it is available. You will be able to download it from: http://www.penticoff.com/nb/programming/nb-codes.zip. I shall list new codes at the head of the file as well as incorporating them into the alphabetical ordering, so that you can quickly check what is new. Preface to the Revised Edition iii Troubleshooting Errors in the CPG Please send corrections to [email protected] Back Up Before Customizing Before you do any customization whatever, back up. Back up your data files before running programs on them; back up your keyboard file before editing it. This is of paramount impor- tance. It is very easy to make a slip while customizing a keyboard. NB may then load an ancient default keyboard with important keys in bewildering places. If you have a backup, you can open Windows Explorer and restore your original keyboard file to the c:\nbwin\users\default folder. It is even more important to back up your data files before running a user program, whether you’ve written it yourself or downloaded it from another user or the users’ website. Programs that work on one system don’t always work on another. Programs you write yourself almost always have mistakes at first. Usually they simply don’t run. But some mistakes can swallow data, such as the file on which you want the user program to work, or possibly some other file or files. And mistakes often cause NB to lock up. So save and back up before you begin trying out programs. Disclaimer These notes are provided by me, not by Nota Bene Associates, Inc. They have kindly allowed me to include them in the Help file, but Nota Bene Technical support cannot help with user programs or keyboard definitions that aren’t working. If you try your hand at programming, you should have enough experience with computers not to be too fazed by program and/or computer crashes. They will almost certainly happen as you write and test XPL programs—they happen to everyone who tinkers with programming. If you are stymied, ask for help on the users’ list (for how to join, see p. iv). If you ask for help It is hard to read someone else’s XPL program if it is not broken up into lines and commented—it is even hard to read one’s own programs a while after writing them. If you send a program to the NB user list in hopes of getting help with it, you must comment it—in the program, not just in your message. You need to include the purpose of the program, what is going wrong with it. You should break it up into lines, and precede each with a description of what you intend the line of code to do, e.g., ;*; Label 3. Move cursor Left one character. Backdelete previous character. Insert para- graph marker «lb3»«CL BD ¿ ;*; Go to Label E «glLE» See p 90 for information on how to comment a program. iv Preface to the Revised Edition Online Customization and Programming Resources Rick Penticoff’s NB Users’ website This is a major source of tips, manuals, user programs and useful links. It is at: http://www.penticoff.com/nb/index.htm NBKEY.KEY—the Keyboard Table This table shows the key assignments of all keys in all the shift states (Unshifted, Shift, Ctrl, etc.) in NB.KBD as delivered. You should print it out if you are doing keyboard customizing. It is in C:\NBWIN\DOCUMENT\SAMPLES. Greg Polly’s Tutorial Greg Polly has written a basic tutorial on how to write a program in Nota Bene for Windows. It’s at: http://www.penticoff.com/nb/help/howtorun.htm. You should use the codes lists in Chapters 2 and 8 rather than his appendix of command codes, which are taken from the DOS edition of the CPG.