\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}
