\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 /.atk.macros addfiletype .macros ness } where 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 /.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 "" ... end keys and each menu binding is in on menu "" ... 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{/.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}