\begindata{text,752768}
\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 several 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 global init file, called


$ANDREWDIR/lib/global.\italic{program}init


and reads this.  Whether this exists or not, the program continues to look 
for a 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


$ANDREWDIR//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 $ANDREWDIR//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,792512}
\enddata{bp,792512}
\view{bpv,792512,0,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,752768}
