|
Setting Up and Using Initialization Files
This help document contains information that is intended for advanced and knowledgeable users of the Andrew System. It describes how you can customize ATK (Andrew Tool Kit) programs through the use of initialization files (also called "initfiles"). Initfiles let you:
add menu options and keybindings to procedures, or procs,
map file extensions to insets or templates and other parameter settings, and
include other initfiles.
Important Information
There are two potential problems you need to be aware of when you create your own initfiles: knowing which initfile a program will use, and keeping styles out of initfiles.
Are styles OK? No. Formatting styles in an initfile will cause Startup Errors, and the commands in the file will not take effect. Whenever you add anything to an initfile, select the entire file and choose Plainest to remove any styles that may be present. This is especially crucial when you copy commands from help files, because example commands may have indenting styles on them.
The spacing in command lines is also important, and there can be no line breaks (carriage returns) in a single command. Note that choosing Plainest does not correct spacing or remove extra line breaks.
Which initfile does a program use? An ATK program can only use one initfile (in addition to a site initfile that always is used, if defined at your site). It finds an initfile to use by looking in three different places, using the first file it finds. First, it looks to see if it has its own initialization file in your home directory, called
~/.programinit
In the case of EZ, the file would be called .ezinit. Note the dot in front of the name. If this file exists, EZ looks no further and uses whatever is specified in this file. If ~/.ezinit doesn't exist, EZ looks to see if there is an init file that specifies behavior for all ATK programs in your home directory called
~/.atkinit
This file can also be called .be2init. If this file exists, EZ looks no further and uses whatever is specified in this file. If ~/.atkinit doesn't exist, EZ looks to see if there is a global program init file, called
/usr/andrew/lib/global.programinit
In the case of EZ, the file is called global.ezinit. The global initfile contains default settings that provide consistent and reasonable performance for ATK programs. If none of these files exist, the program looks to see if there is a global atkinit file, called
/usr/andrew/lib/global.atkinit
If none of these files exist, the program starts without an init file. This is generally not a problem.
What does the ordering mean? The ordering means that when you create an initfile, you should make it refer to the files that it masks, by using an "include" statement. So, if you are going to make a .ezinit file, you might want to include the global ezinit. You can include the global file by placing the following on the first line in your .ezinit file:
include /usr/andrew/lib/global.ezinit
If you don't include the global file, you will not get the important default settings. Note, though, that not all programs have global init files.
The Entry Types in Initfiles
The basic types of entries you can put in an initfile are:
include commands reference other initfiles.
addmenu commands create new menu items.
addkey commands create new keybindings.
addfiletype commands create new mappings between filename extensions and inset types.
comments are lines that begin with a #
Each command entry should appear on a separate line; do not put carriage returns within an entry. Blank lines are ignored.
All command entries have one or more arguments, described below. Separate each argument with a space. Surround arguments with double quotes if they have spaces in them, as some menu item specifications do. If an argument is optional, it appears in square brackets. Do not type the brackets if you do include an optional argument.
Most of standard C backslash notation is supported in initfile entries. Notably, \n is a newline, and \### is the appropriate ASCII character (where ### are octal digits).
Include Commands
Since only one initfile can be read during startup, you can use include statements in that file to include the contents of other initfiles (and more than one, if you wish). As stressed above, you are strongly encouraged to use include statements.
The syntax of an include command is:
include filename
Filename is the complete pathname to another initfile--do not start it with a tilde (~). It can be either a global initfile or a file belonging to you or another user. Use a separate include statement for each file you wish to reference.
Addmenu Commands
Addmenu commands let you create new menu items bound to the procedures already available in an inset. You can put new items on the cards the inset provides by default, or put them on entirely new cards you create. See the help on deskey for information on how to find out what procedures are available.
Note: The WM window manager, rather than ATK programs themselves, interprets some aspects of addmenu commands. The details about priority numbers in menustring syntax are correct under WM and for the Cmenus package running under X; results with other window managers may vary.
The syntax of an addmenu command is:
addmenu procedure "menustring" [class] [load_class] [inheritp] [argument]
Example: The following line adds Dynamic Forward searching to the bottom of the Search/Spell menu card:
addmenu dynsearch-search-forward "Search/Spell,Dynamic Forward~50" textview
The addmenu command adds an extra menu item menustring that invokes the procedure procedure. See the help on ezprocs for information on how to find out what procedures are available. The menustring argument has its own internal syntax:
"[card][~cardpriority],item[~itempriority]"
You can omit any of the items show in brackets. If you do include them, do not enclose them in brackets.
Card is the name of the card on which you want the new item; this name will appear at the top of the card. If card is omitted, the item goes on the first card, which has no name. Card must be present for cardpriority to be meaningful.
Cardpriority is a number that controls in what order the cards appear in the stack; it can range from 1 to 100. The lower the number, the closer to the front of the stack, but the exact position of a given card depends on the cardpriority values of the other cards. If cardpriority is omitted, the card will be at the front of the stack. If cardpriority is the same for more than one card, the one appearing later in the set of addmenu commands will be closer to the front of the stack. However, if a card you add has the same cardpriority as a card that the inset provides by default, it will appear behind the default card.
The seven cards provided by default in EZ's text inset are numbered between 1 and 10, so if the cardpriority of an item you add is greater than 10, the card will appear behind all the default cards. If you want to interleave your cards with the text inset's default cards, you will have to experiment.
Type item exactly as you want it to appear on the card. The width of all cards in the stack will expand to accommodate the widest item on any card. Item must be present for itempriority to be meaningful.
Itempriority is a number that controls the order in which items appear on a card; it can range from 10 to 99. The first digit (ranging from 1 to 9) groups individual menu items together, separating each group with a blank line. It also determines the order in which the groups appear. That is, items with the same first itempriority digit will appear together, separated by a blank line from items with a different first digit. The smaller the first digit, the closer the group will appear to the top of the card. The second digit in itempriority (ranging from 0 to 9) determines how items are ranked within a group; the smaller the number, the higher up in the group. If itempriority is omitted, then item appears at the very top of the card. If more than one item shares the same itempriority, the one appearing later in the list of addmenu commands is higher up on the card.
The four optional arguments shown in brackets are often not needed, and you probably only need to understand them if you are programming using the ATK.
Class names the view type to which you want to add the menu item (a view is one of the program modules in an inset). If class is omitted, the program using the initfile will try to infer the desired class from the first part of procedure (the part up to the first hyphen), though this is not always possible.
Load_class is used to determine which module must be loaded to find procedure. If load_class is omitted, EZ infers the desired class from the first part of procedure (the part up to the first hyphen), if possible. The class parameter must be present for the load_class parameter to be used.
The inheritp argument determines whether the class test is an inclusion test or an equality test. It is either inherit if the class test is an inclusion test (i.e., if the menu item is to be added to subclasses of class) or noinherit if the class test is an equality test (i.e., if the menu item is to be added to class but not to its subclasses). If inheritp is omitted, the test is an inclusion test (inherit).
The argument is an optional argument to procedure.
Addkey Commands
Addkey commands let you bind procedures to particular key sequences, so that when the keys are pressed the procedure is invoked. The same procedures are available for keybinding as for menu items; see the help on deskey for information on how to find out what procedures are available.
The syntax for an addkey command entry is:
addkey procedure keysequence [class] [load_class] [inheritp] [argument]
Example. The following line binds dynamic searching to the keystroke "^S".
addkey dynsearch-search-forward ^S textview
(See ez-keys for a description of what "^S" means.)
The addkey command binds the procedure procedure to a sequence of keystrokes keysequence. Class, load_class and inheritp and argument are used the same way as with addmenu.
To indicate the Esc(ape) key in keysequence, use \e.
To indicate the Ctrl (control) key, use ^.
Addfiletype Commands
Addfiletype commands allow you to map new extensions to inset types, so that documents you create with a certain extension will get the proper inset type.
The syntax for an addfiletype command entry is:
addfiletype .extension insetname ["parameter1=value1;parameter2=value2;..."]
The addfiletype command tells EZ to use inset type insetname on files with the extension extension. The optional parameter specification lets you set parameters for that particular inset type on files with that extension. The parameter settings permitted depend on the inset type. The text inset supports the parameter template, whose value is the name of a template.
Example. The following line ensures that files with a .flames extension use the Lisp package for EZ called ltext .
addfiletype .flames ltext
Example. The following line ensures that that any file with a .help extension will be edited with the text inset and the help template.
addfiletype .help text "template=help"
Be sure to type a period before extension. If extension is an asterisk (*) then insetname will be used for files with extensions not covered by any other addfiletype command.
Related Topics
|
