\begindata{text,538353504}
\textdsversion{12}
\template{help}
\define{global

attr:[FontSize ConstantFontSize Point 12]}
\define{itemize
menu:[Region~4,Itemize~31]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{enumerate
menu:[Region~4,Enumerate~30]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{excerptedcaption

attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[FontFace Bold Int Set]
attr:[FontFace Italic Int Set]}
\define{literal
menu:[Region~4,Literal~62]
attr:[Flags PassThru Int Set]}
\define{black
menu:[Color,Black]
attr:['color' 'Black']}
\define{red
menu:[Color,Red]
attr:['color' 'Red']}
\define{green
menu:[Color,Green]
attr:['color' 'Green']}
\define{blue
menu:[Color,Blue]
attr:['color' 'Blue']}
\define{magenta
menu:[Color,Magenta]
attr:['color' 'Magenta']}
\define{cyan
menu:[Color,Cyan]
attr:['color' 'Cyan']}
\define{yellow
menu:[Color,Yellow]
attr:['color' 'Yellow']}


\chapter{ATK Macros: User DefinedOperations

}
\section{What ATK Macros are

}\leftindent{
Macros are sequences of operations combined in a package so they can be 
executed in response to a key sequence or menu selection.  In ATK, macros are 
written in the \italic{\helptopic{Ness}} language either by coding in Ness 
directly or by performing the sequence of actions and asking to have it 
converted to Ness.

}
\section{Preparing to use ATK Macros

}\leftindent{
To be ready to use macros you should add the following three lines to the 
beginning of your ~/.XXXinit file, where XXX is any ATK application in which 
you want to use macros:


\example{load ness

call ness-load <path>/.atk.macros

addfiletype .macros ness

}
where <path> should be replaced with the path name of your home directory. 
 When application XXX starts up, your macro definitions will be read from the 
.atk.macros file.


Alternative:  You may wish to use macros in all applications.  If so, put the 
above three lines in your ~/.atkinit file and begin each ~/.XXXinit with 


\example{include <path>/.atkinit}


Other ness macro packages can be loaded with additional "call ness-load ..." 
lines.  The file names should end with ".macros".

}
\section{Creating Macros}

\leftindent{
Macros can be created by editing a Ness file or by converting from the 
"keyboard macro".  


To convert from a keyboard macro, you first have to define one: type 
control-X-left-parenthesis, then proceed with the operation which you wish to 
turn into a macro.  Finally, type control-X-right-parenthesis to mark the end 
of the macro.  The keyboard macro can be executed directly by typing 
control-X-e.  To convert the keyboard macro into Ness code,  choose the "Make 
Macro" menu option from the "Ness" menu card and you will be asked how you 
want to install it and what keys or menu item should activate it.


In editing a Ness file, a set of key or menu bindings for a given type of view 
are wrapped inside

	extend "view:textview" ...  end extend

(where textview is replaced with the type of view being extended.)

Each key bound sequence of operations is in 

	on keys "<keys>" ... end keys

and each menu binding is in 

	on menu "<menu name>" ... end menu

See the example below.


}

\section{Menu Options

}\leftindent{
"Append to file" appears on the "Ness" menu card when you are viewing a Ness 
script (a collection of one or more Ness macros and functions.)  It allows you 
to append the contents of the current script to a file.  If the current script 
has not been compiled since the last change it is recompiled; if errors are 
detected you will be informed and the append operation will be cancelled.  If 
the recompilation succeeds the contents of the script are appended to the file 
and the new contents of the file are recompiled.  If this second compilation 
succeeds the changed file contents are stored into the file.  If any ness 
script exists with the same tail filename (ie foo/.atk.macros and 
bar/.atk.macros) as the file being appended to, you will be prompted whether 
you wish it to be replaced or not.  If you want the new file to completely 
replace the old you should respond "Yes", otherwise "No."  If you answer "No" 
the new Ness script's bindings may shadow some or all of the old script's, but 
any others will still be available.  This is because both scripts are now 
active and if both try to bind the same menu option or key sequence it is not 
clear which binding will actually be effective.


"Visit existing Ness" appears on the "Ness" menu card at all times.  It allows 
you to visit an active Ness even if that Ness isn't in a buffer or otherwise 
visible.  It will bring up a new window and will display a buffer with the 
selected Ness.  Completion and help are available just like for buffer names 
or files.  Space will attempt to complete the script name, and '?' will list 
all the script names which match what has been typed so far.


"Make Macro" appears on the "Ness" menu card at all times.  It will convert to 
Ness code the current keyboard macro \{defined via control-X-( and control-X-) 
\}.  After the conversion, the code is kept in a buffer and a dialog box gives 
you options to install a keybinding, install a menu option, cancel the 
operation, or edit the script before it is modified for use as either a 
keybinding or menu option.  Once you choose how to install it you will be 
asked for the specific binding (eg ^X^L, or Menu~20,This Item.)  After 
installation you can visit the buffer containing the script and edit it, 
possibly changing it's behavior or even it's binding.


}	

\section{Warnings

}\leftindent{
This system is quite new and there may be some surprises we don't know about 
yet.


One of the pitfalls we do know about is the fact that many proctable functions 
(like textview_query_replace) prompt for input in the message line .  When 
creating a Ness script it is not possible to have the script provide the input 
in the normal way, since while the function is running the script is 
suspended.  Instead of providing answers in the normal way via keystrokes or 
menu options use the Ness function queueanswer.  \italic{QueueAnswer} takes a 
string and places it on a queue to answer a question or a series of questions, 
the first answers queued will be the first used.


If you are creating a Ness macro from a keyboard macro QueueAnswer commands 
will be generated automatically, but the  Ness macro may not have the desired 
behavior.  For example, if in the keyboard macro you answer a question by 
using ^Y to yank some text from the cut buffer the string you yanked will be 
recorded in the Ness script.  When playing back the keyboard macro the prompt 
is answered with the current value of the cut buffer.  However, the generated 
Ness function answeres the prompt with the value the cut buffer had when the 
keyboard macro was being made.  To acheive the yank behavior, the most general 
solution is to replace the call on QueueAnswer with:


	m = currentselection(defaulttext)

	textview_yank(defaulttext)

	QueueAnswer(currentselection(defaulttext))

	textview_zap_region(defaulttext)

	setcurrentselection(defaulttext, m)



}
\section{Preference

}\leftindent{
\bold{DefaultMacrosFile:} \bold{\italic{<home-directory>/.atk.macros}}

	This preference names the default file  for "Append to file."

}
\section{Example macro definitions}

\leftindent{
The macros in this example bind the key sequence  control-X-i to indent the 
current paragraph and the menu option "teh" to change all instances of " teh " 
to " the " in the current selection:


extend "view:textview"

	on keys "\\030i"

		textview_forward_character()

		textview_backward_para()

		textview_ctrl_at()

		textview_forward_para()

		textview_select_region()

		textview_indent()

	end keys

	on menu "teh"

		queueanswer(" teh ")

		queueanswer(" the" )

		queueanswer("!")  

		textview_query_replace()

	end menu

end extend}


\section{Program Author}

\leftindent{
Rob Ryan, Andrew Toolkit Consortium}



\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 file for:


\leftindent{\italic{\helptopic{initfiles}}

\italic{\helptopic{keybindings}}}


\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,538,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,538353504}
