Mary Bernard's Customization and Programming Notes

XPL Programming

The following notes assume that you have NB in a folder named c:\nbwin. If your path is different, changes path/folder names accordingly. They are brief notes only; for full explanations, download the CPG.

Why write programs?

NB does so much, and so elegantly, that many users never feel the need for supplemental programs. But quite simple programs can streamline your work. I write temporary programs every day or two—any time I have several global changes to make to a file, for instance. I find it quicker to write a program that says: `Change all A to B, change all C to D, change all E to F, change all curly quotes to straight, then put `Done' on the prompt line' than to use the Find and Replace menu.

These are really just macros. Full programs use branching and conditionals, such as I use, for instance, in my program IMDB.RUN. I keep an IbidPlus database of my DVDs, using details downloaded from the Internet Movie Database. Changing the data into the format I want for Ibidem takes ages by hand. IMDB.RUN puts the details in a fixed order, reverses first and last names (Cary Grant to Grant, Cary—but only when I say Yes to a prompt), and removes extra tabs and CRs. The slowest part of the operation is now copying and pasting the standardized data into Ibidem—so I'll write a program to automate that.

If you are new to programming, Greg Polly's tutorial will provide a quick introduction to the basics. As noted on the Resources page above, you should use the codes list in Chapter 8 of the CPG, not his appendix. This tutorial is only a very basic introduction. If you want to understand XPL, you should print out the CPG.

There are simple examples of user programs on the website at:

http://www.penticoff.com/nb/utilities/mbutils.htm.

Naming programs

You can name programs anything. If you want to run them from the action line, the name should be in 8+3 form (no more than eight characters before the (optional) extension, no more than 3 after). NB users often name their programs with an extension of .RUN, but it's not necessary. When I'm writing temporary programs, I save them with a single-letter filename, e.g., R or T: it's quicker to test a single-letter file than an 8+3 one: `run t' versus `run tempfile.run'.

Running programs

You can run programs by putting them on keyboard keys, e.g.:

##=bx,r,u,n, ,c,:,\,n,b,w,i,n,\,x,p,l,\,l,h,-,q,u,o,t,e,.,r,u,n,q2

—or by loading them on phrase keys, e.g. by typing on the action line

ldpm c:\nbwin\xpl\lh-quote.run,j

For the rest of your session, striking Alt+Shift J will run the user program LH-QUOTE.RUN (assuming you have downloaded it). If you always want to run the program from this key, save the phrase library before exiting NB.

—or by typing `run' + the program name on the action line:

run c:\nbwin\xpl\lh-quote.run

This runs the program once. I run temp programs so often that I have a keyboard key defined as:

##=bc,r,u,n, ,

This puts `run ' on the action line. I just type `T' or `R' and press F10 (or Enter) to run the program.

You don't need to type the path name if you are working in the same folder as the program, but you should really keep your programs in a folder named c:\nbwin\xpl. In this case, if you are in another folder, you need to type the full path to the xpl folder—unless you put the xpl folder in your path (Control Panel, System Properties, Advanced, Environment Variables, System Variables. Highlight Path in the window, click Edit, and add c:\nbwin\xpl).

If you have downloaded and installed the XYWWWEB.U2 file, you can add programs to the bottom of the file and run them with your U2 help key.

Writing programs

Consult Greg Polly's tutorial and the `Writing XPL Programs' chapter of the CPG. You should also look at the sections Editing in Show Codes View and NB Commands in NB Help.

You should write programs in Show Codes view, so that you can see what you're doing, and so that you don't get error messages when you input opening command brackets.

Command brackets are also called format brackets, chevrons, double angled brackets or guillemets by long-standing Nota Bene or XyWrite users. You may encounter any of those names in the explanatory matter that accompanies user programs. Likewise, codes enclosed in command brackets may be called deltas.

You can enter functions (such as BC, AS, etc.) by striking your pfunc key (Ctrl + ; or Ctrl + keypad 5) and typing the two letters/numbers of the code.

Programming mode, which enters codes from the keyboard directly into your program, should be used with caution. Many of the newer keyboard functions do not work in programs (principally, keyboard codes that begin with `&+ letter', or are enclosed in square brackets). The code will be input into your program, but running the program won't execute it.)

If you do a lot of programming, it is useful to have a phrase library loaded with the pieces of code that you use over and over. My PROGRAM.LIB contains strings like:

«IF«ER»

«BX»ci ///«Q2»