\begindata{text,539040528} \textdsversion{12} \template{help} \define{global } \chapter{Setting up and using initialization files}\chapter{ } This help document contains information that is intended for advanced and knowledgeable users of the Andrew System. It describes how you can customize \italic{ATK} (Andrew Tool Kit) programs through the use of initialization files (also called "initfiles"). Initfiles let you: \leftindent{add menu options and keybindings to procedures, or \italic{procs }, } \leftindent{map file extensions to \helptopic{insets} or \helptopic{templates}\italic{ }and other parameter settings, and }\leftindent{ include other initfiles}.\leftindent{ } \section{Important Information} \leftindent{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. \bold{ 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 \bold{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 \bold{Plainest} does not correct spacing or remove extra line breaks. \bold{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 ~/.\italic{program}init 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.\italic{program}init 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. \bold{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. }\section{The entry types in initfiles} \leftindent{The basic types of entries you can put in an initfile are: \leftindent{\bold{include} commands reference other initfiles. \bold{addmenu} commands create new menu items. \bold{addkey} commands create new keybindings. \bold{addfiletype} commands create new mappings between filename extensions and inset types. \bold{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). }\section{Include commands} \leftindent{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 an include statements. The syntax of an include command is: \bold{\example{include \italic{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.\leftindent{\leftindent{ }}}\section{Addmenu commands}\leftindent{ }\leftindent{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 \helptopic{deskey} for information on how to find out what procedures are available. \bold{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: \example{\bold{addmenu \italic{procedure "menustring" }[\italic{class}] [\italic{load_class}] [\italic{inheritp}] [\italic{argument}]} } Example: The following line adds \bold{Dynamic Forward} searching to the bottom of the \italic{Search/Spell} menu card: \example{addmenu dynsearch-search-forward "Search/Spell,Dynamic Forward~50" textview } The addmenu command adds an extra menu item \italic{menustring} that invokes the procedure \italic{procedure}. See the help on \italic{\helptopic{procs}} for information on how to find out what procedures are available. The\italic{ menustring} argument has its own internal syntax: \example{\bold{"[\italic{card}][\italic{~cardpriority}],\italic{item}[~\ \italic{itempriority}]"} } You can omit any of the items show in brackets. If you do include them, do not enclose them in brackets. \italic{Card} is the name of the card on which you want the new \italic{item}; this name will appear at the top of the card. If \italic{card} is omitted, the \italic{item} goes on the first card, which has no name. \italic{Card} must be present for \italic{cardpriority} to be meaningful. \italic{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 \italic{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. \italic{Item} must be present for \italic{itempriority} to be meaningful. \italic{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. \italic{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 \italic{class} is omitted, the program using the initfile will try to infer the desired class from the first part of \italic{procedure} (the part up to the first hyphen), though this is not always possible. \italic{Load_class} is used to determine which module must be loaded to find \italic{procedure}. If \italic{load_class} is omitted, EZ infers the desired class from the first part of \italic{procedure} (the part up to the first hyphen), if possible. The \italic{class} parameter must be present for the \italic{load_class} parameter to be used. The \italic{inheritp} argument determines whether the class test is an inclusion test or an equality test. It is either \bold{inherit} if the class test is an inclusion test (i.e., if the menu item is to be added to subclasses of \italic{class}) or \bold{noinherit} if the class test is an equality test (i.e., if the menu item is to be added to \italic{class} but not to its subclasses). If \italic{inheritp} is omitted, the test is an inclusion test (\bold{inherit}). The \italic{argument} is an optional argument to \italic{procedure}. }\leftindent{ }\section{Addkey commands} \leftindent{ 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 \helptopic{deskey} for information on how to find out what procedures are available. The syntax for an addkey command entry is: \leftindent{ }\example{\bold{addkey \italic{procedure keysequence} [\italic{class}] [\italic{load_class}] [\italic{inheritp}] [\italic{argument}]} } Example. The following line binds dynamic searching to the keystroke "^S". \example{addkey dynsearch-search-forward ^S textview } (See \helptopic{ez-keys} for a description of what "^S" means.) The addkey command binds the procedure \italic{procedure} to a sequence of keystrokes \italic{keysequence}. \italic{Class}, \italic{load_class} and \italic{inheritp} and \italic{argument} are used the same way as with addmenu. To indicate the Esc(ape) key in \italic{keysequence}, use \\e. To indicate the Ctrl (control) key, use ^. }\section{Addfiletype commands}\leftindent{ 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. }\leftindent{The syntax for an addfiletype command entry is: \example{\bold{addfiletype .\italic{extension insetname }["\italic{parameter}1=\italic{value}1;parameter2=value2;..."]} } The addfiletype command tells EZ to use inset type \italic{insetname} on files with the extension \italic{extension}. The optional \italic{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 \bold{text} inset supports the parameter \bold{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 \italic{ ltext }. \example{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. \example{addfiletype .help text "template=help" } Be sure to type a period before \italic{extension}. If \italic{extension} is an asterisk (*) then \italic{insetname }will be used for files with extensions not covered by any other addfiletype command. }\description{ }\section{Related Tools} Select (highlight) one of the italicized names and choose "Show Help on Selected Word" from the pop-up menu to see the help document for: \leftindent{ \helptopic{ez} (EZ as a text editor)\italic{ }\helptopic{ez-buffers}\italic{ }(multiple windows and files in EZ)\italic{ }\helptopic{ez-keys}\italic{ } \italic{ }\helptopic{ez-extensions } (how EZ interprets extensions) \helptopic{ez-emacs} (keybindings to make EZ act more like GNU Emacs) \helptopic{insets} (non-text editing packages for EZ) \helptopic{procs}\italic{ }\helptopic{templates} \helptopic{typescript-keys}\italic{ }} \begindata{bp,537558784} \enddata{bp,537558784} \view{bpv,537558784,1247,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,539040528}