/usr/share/doc/ne/html/Basic-Macros.html is in ne-doc 2.5-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | <html lang="en">
<head>
<title>Basic Macros - ne's manual</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="ne's manual">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Basics.html#Basics" title="Basics">
<link rel="prev" href="Basic-Preferences.html#Basic-Preferences" title="Basic Preferences">
<link rel="next" href="More-Advanced-Features.html#More-Advanced-Features" title="More Advanced Features">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Basic-Macros"></a>
<p>
Next: <a rel="next" accesskey="n" href="More-Advanced-Features.html#More-Advanced-Features">More Advanced Features</a>,
Previous: <a rel="previous" accesskey="p" href="Basic-Preferences.html#Basic-Preferences">Basic Preferences</a>,
Up: <a rel="up" accesskey="u" href="Basics.html#Basics">Basics</a>
<hr>
</div>
<h3 class="section">2.6 Basic Macros</h3>
<p><a name="index-Macro-definition-36"></a><a name="index-Recording-a-macro-37"></a><a name="index-Saving-a-macro-38"></a><a name="index-Interrupting-a-macro-39"></a><a name="index-Interrupt-character-40"></a><a name="index-Caching-a-macro-41"></a><a name="index-Unloading-macros-42"></a><a name="index-Executing-a-macro-43"></a><a name="index-Comments-in-a-macro-44"></a>
Very often, the programmer or the text writer has to repeat some complex
editing action over a series of similar blocks of text. This is where
<dfn>macros</dfn> come in.
<p>A <dfn>macro</dfn> is a stored sequence of commands. Any sequence of commands
you find yourself repeating is an excellent candidate for being made
into a macro. You could create a macro by editing a document that only
contains valid <code>ne</code> commands and saving it, but by far the easiest way to create
a macro is to have <code>ne</code> record your actions. <code>ne</code> allows you
to record macros and then play them (execute the commands they contain)
many times. You can save them on disk for future use, edit them, or bind
them to any key. You could even reconfigure each key of your keyboard to
play a complex macro if you wanted to.
<p><code>ne</code> can have any number of named macros loaded at the same time.
It can also have one unnamed macro in its <dfn>current macro</dfn> buffer.
The named macros are typically loaded from disk files, while the
current macro buffer is where your recorded macro is held before you
save it or record over it.
<p>Recording a macro is very simple. The keystroke <kbd><Control>-T</kbd>
starts and stops recording a macro. When you start recording a macro,
<code>ne</code> clears the <dfn>current macro</dfn> buffer and starts recording all
your actions (with a few exceptions). You can see that you are recording
a macro if an ‘<samp><span class="samp">R</span></samp>’ appears on the status bar. When you stop the
recording process (again using <kbd><Control>-T</kbd>), you can play the
macro with the ‘<samp><span class="samp">Play Once</span></samp>’ item of the ‘<samp><span class="samp">Macros</span></samp>’ menu or with
the <f9> key. If you want to repeat the action many times, the
<code>Play</code> command allows you to specify a number of times to repeat
the macro. You can always interrupt the macro's execution with
<kbd><Control>-\</kbd>.
<p>A recorded macro has no name. It's just an anonymous sequence of
commands in the <dfn>current macro</dfn> buffer, and it will go away when you
exit <code>ne</code> or record another macro. If you want to save your
recorded macro for future use, you can give it a name and save it with
the ‘<samp><span class="samp">Save Macro...</span></samp>’ menu item or the <code>SaveMacro</code> command. The
macro is saved as a file in your current directory by default or
whatever directory you specify when prompted for the macro's name. If
you save it in your <samp><span class="file">~/.ne</span></samp> directory then it will be easy to
access it later from any other directory. The ‘<samp><span class="samp">Open Macro...</span></samp>’ menu item
and the <code>OpenMacro</code> command load a macro from a file into the
current macro buffer just as if you just <code>Record</code>ed it.
<p>Any macro can be loaded from a file and played with the ‘<samp><span class="samp">Play Macro...</span></samp>’
menu item or the <code>Macro</code> command. (This won't modify any recorded
anonymous macro that may be in the <dfn>current macro</dfn> buffer;
<code>OpenMacro</code> does that.) Useful macros can be permanently bound to a
keystroke as explained in <a href="Key-Bindings.html#Key-Bindings">Key Bindings</a>. Moreover, whenever a
command line does not specify one of <code>ne</code>'s built in commands, it is
assumed to specify the name of a macro to execute. Thus, you can execute
macros just by typing their file names. Include a path if the macro
file's directory is different from your current directory or your
<samp><span class="file">~/.ne</span></samp> directory.
<p>If the first attempt to open a macro fails, <code>ne</code> checks for a macro
with the given name in your <samp><span class="file">~/.ne</span></samp> directory. This allows you
to program simple extensions to <code>ne</code>'s language. For instance, all
automatic preferences macros—which are just specially named macros
that contain only commands to set preferences flags—can be executed
just by typing their names. For example, if you have an automatic
preference for the ‘<samp><span class="samp">doc</span></samp>’ extension for example, you can set
<code>ne</code>'s flags exactly as if you loaded a file ending with
‘<samp><span class="samp">.doc</span></samp>’ by typing the command <code>doc#ap</code>.
<p>In general, it is a good idea to save frequently used macros in
<samp><span class="file">~/.ne</span></samp> so that you can invoke them by name without specifying
a path regardless of your current directory. On the other hand, if you
have a macro that is customized for one document or a set of documents
that you store in one directory, then you might want to save the
macro in that directory as well. If you do, then you would want to
<code>cd</code> to that directory before you start <code>ne</code> so that you can
access that macro without specifying a path.
<p>If your macro has the same name as one of <code>ne</code>'s built-in commands,
you can only access it with the <code>Macro </code><var>name</var> command.
Built-in command names are always found first before <code>ne</code> command
interpreter looks for macros.
<p>The system administrator may make some macros available from
<code>ne</code>'s global directory. See <a href="Arguments.html#Arguments">Arguments</a>.
<p>Since loading a macro each time it is invoked would be a rather slow and
expensive process, once a macro has been executed it is cached internally.
Subsequent invocations of the macro will used the cached version.
<p class="noindent"><strong>Warning:</strong> while path and file names are case sensitive
when initially loading macros, loaded macro names are <em>not</em> case
sensitive or path sensitive. <code>ne</code> only caches the file name of an
already loaded macro, not the path name, and uses a case insensitive
comparison. That is, if you invoke <samp><span class="file">~/foobar/MyMacro</span></samp>, <code>ne</code>
remembers it with the case-insensitive name <samp><span class="file">mymacro</span></samp>; a subsequent
call for <samp><span class="file">/usr/MYMACRO</span></samp> will instead find and use the cached version
of <samp><span class="file">~/foobar/MyMacro</span></samp>. You can clear the cache by using the
<code>UnloadMacros</code> command. See <a href="UnloadMacros.html#UnloadMacros">UnloadMacros</a>.
<p>The behaviour of macros may vary with different preferences. If the user
changes the AutoIndent and WordWrap flags, for example, new lines and new
text may not appear in the same way they would have when a macro was
recorded. Good general purpose macros avoid such problems by using the
<code>PushPrefs</code> command first. This preserves the user's preferences.
Then they set any preferences that could affect their behaviour. Once
that is taken care of they get on with the actual work for which they
were intended. Finally, they use the <code>PopPrefs</code> command to restore
the user's preferences. Note that if a macro is stopped before it
restores the preferences (either by the user pressing
<kbd><Control>-\</kbd> or by a command failing) then that responsibility
falls on the user.
<p>Any changes made to a document by a macro are recorded just as if you had
entered the commands yourself. Therefore you can use the <code>Undo</code> command
to roll back those changes one at a time. This can be useful especially when
developing macros, but you may want to be able to undo all the changes made
by a macro with a single <code>Undo</code> command. The <code>AtomicUndo</code> command
makes this possible. If you add <code>AtomicUndo +</code> at the start of your
macro and <code>AtomicUndo -</code> at the end, then the <code>Undo</code> and
<code>Redo</code> commands will handle all changes made by your macro atomically,
i.e., as if they had been made by a single command. See <a href="AtomicUndo.html#AtomicUndo">AtomicUndo</a>.
<p>Finally, any line in a macro that starts with a non-alphabetical character
is considered a comment, so you can add comments to a macro by starting
a line with ‘<samp><span class="samp">#</span></samp>’.
</body></html>
|