Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume1/8711/13

Internet Message Format | 1990-07-13 | 50KB

Path: uunet!husc6!necntc!ncoast!allbery
From: [e-mail] (Daniel Lawrence)
Newsgroups: comp.sources.misc
Subject: MicroEmacs 3.9 Manual (2 of 6)
Message-ID: <[e-mail]>
Date: 26 Nov 87 04:14:19 GMT
Sender: [e-mail]
Lines: 1189
Approved: [e-mail]
X-Archive: comp.sources.misc/8711/13

Xvalue used to reset $ACOUNT after a save occurs.
X
X@section(CMODE mode)@index(CMODE mode)
X
X    CMODE is useful to C programmers.  When CMODE is active, EMACS
Xwill try to assist the user in a number of ways.  This mode is set
Xautomatically with files that have a .c or .h extension.
X
X    The <NL> key will normally attempt to return the user to the next
Xline at the same level of indentation as the current line, unless the
Xcurrent line ends with a open brace ({) in which case the new line will
Xbe further indented by one tab position.
X
X    A close brace (}) will delete one tab position preceeding itself
Xas it is typed.  This should line up the close brace with its matching
XIF, FOR or WHILE statement.
X
X    A pound sign (#) with only leading whitespace will delete all
Xthe whitespace preceeding itself. This will always bring preprocessor
Xdirectives flush to the left margin.
X
X    Whenever any close fence is typed, ie )]>}, if the matching open
Xfence is on screen in the current window, the cursor will briefly flash
Xto it, and then back. This makes balancing expressions, and matching
Xblocks much easier.
X
X@section(CRYPT mode)@index(CRYPT mode)
X
X    When a buffer is in CRYPT mode, @index(encryption) it is
Xencrypted whenever it is written to a file, and decrypted when it is
Xread from the file.  The encryption key can be specified on the command
Xline with the -k switch, or with the @b(M-E) @i(set-encryption-key)
X@index(set-encryption-key) command.  If you attempt to read or write a
Xbuffer in crypt mode and now key has not been set, EMACS will execute
X@i(set-encryption-key) automatically, prompting you for the needed key.
XWhenever EMACS prompts you for a key, it will not echo the key to your
Xscreen as you type it (ie make SURE you get it right when you set it
Xoriginally).
X
X    The encryption algorithm used changes all characters into normal
Xprinting characters, thus the resulting file is suitable for sending via
Xelectronic mail.  All version of MicroEMACS should be able decrypt the
Xresulting file regardless of what machine encrypted it.  Also available
Xwith EMACS is the stand alone program, MicroCRYPT, which can en/decrypt
Xthe files produced by CRYPT mode in EMACS.
X
X@section(EXACT mode)@index(EXACT mode)
X
X    All string searches and replacements will take upper/lower case
Xinto account. Normally the case of a string during a search or replace
Xis not taken into account.
X
X@section(MAGIC mode)@index(MAGIC mode)
X
X     In the MAGIC mode certain characters gain special meanings when
Xused in a search pattern.  Collectively they are know as regular
Xexpressions, and a limited number of them are supported in MicroEmacs.
XThey grant greater flexibility when using the search command.  However,
Xthey do not affect the incremental search command.
X
X     The symbols that have special meaning in MAGIC mode are
X^, $, ., &, *, [ (and ], used with it), and \.
X
X     The characters ^ and $ fix the search pattern to the beginning and
Xend of line, respectively.  The ^ character must appear at the beginning
Xof the search string, and the $ must appear at the end, otherwise they
Xloose their meaning and are treated just like any other character.  For
Xexample, in MAGIC mode, searching for the pattern "t$" would put the
Xcursor at the end of any line that ended with the letter 't'.  Note that
Xthis is different than searching for "t<NL>", that is, 't' followed by a
Xnewline character.  The character $ (and ^, for that matter) matches a
Xposition, not a character, so the cursor remains at the end of the line.
XBut a newline is a character that must be matched, just like any other
Xcharacter, which means that the cursor is placed just after it - on the
Xbeginning of the next line.
X
X     The character .  has a very simple meaning -- it matches any single
Xcharacter, except the newline.  Thus a search for "bad.er" could match
X"badger", "badder" (slang), or up to the 'r' of "bad error".
X
X     The character * is known as closure, and means that zero or more of
Xthe preceding character will match.  If there is no character preceding,
X* has no special meaning, and since it will not match with a newline, *
Xwill have no special meaning if preceded by the beginning of line symbol
X^ or the literal newline character <NL>.
X
X     The notion of zero or more characters is important.  If, for
Xexample, your cursor was on the line
X
X@quotation(This line is missing two vowels.)
X
Xand a search was made for "a*", the cursor would not move, because it is
Xguaranteed to match no letter 'a' , which satifies the search
Xconditions.  If you wanted to search for one or more of the letter 'a',
Xyou would search for "aa*", which would match the letter a, then zero or
Xmore of them.
X
X     The character [ indicates the beginning of a character class.  It
Xis similar to the 'any' character ., but you get to choose which
Xcharacters you want to match.  The character class is ended with the
Xcharacter ].  So, while a search for "ba.e" will match "bane", "bade",
X"bale", "bate", et cetera, you can limit it to matching "babe" and
X"bake" by searching for "ba[bk]e".  Only one of the characters inside
Xthe [ and ] will match a character.  If in fact you want to match any
Xcharacter except those in the character class, you can put a ^ as the
Xfirst character.  It must be the first character of the class, or else
Xit has no special meaning.  So, a search for [^aeiou] will match any
Xcharacter except a vowel, but a search for [aeiou^] will match any vowel
Xor a ^.
X
XIf you have a lot of characters in order that you want to put in the
Xcharacter class, you may use a dash (-) as a range character.  So, [a-z]
Xwill match any letter (or any lower case letter if EXACT mode is on),
Xand [0-9a-f] will match any digit or any letter 'a' through 'f', which
Xhappen to be the characters for hexadecimal numbers.  If the dash is at
Xthe beginning or end of a character class, it is taken to be just a
Xdash.
X
X     The character & (ampersand) is a replacement character, and
Xrepresents the characters which matched the search string.  When used in
Xthe @b[M-R] @i(replace-string) @index(replace-string) or the @b[M-^R]
X@i(query-replace-string) @index(query-replace-string) commands, the &
Xwill be substituted for the search string.
X
X     The escape character \ is for those times when you want to be in
XMAGIC mode, but also want to use a regular expression character
Xto be just a character.  It turns off the special meaning of the
Xcharacter.  So a search for "it\." will search for a line with "it.",
Xand not "it" followed by any other character.  The escape character
Xwill also let you put ^, -, or ] inside a character class with no
Xspecial side effects.
X
X@section(OVER mode)@index(OVER mode)
X
X    OVER mode stands for overwrite mode.  When in this mode, when
Xcharacters are typed, instead of simply inserting them into the file,
XEMACS will attempt to overwrite an existing character past the point.
XThis is very useful for adjusting tables and diagrams.
X
X@section(WRAP mode)@index(WRAP mode)
X
X    Wrap mode is used when typing in continuous text.  Whenever the
Xcursor is past the currently set fill column @index(fill column) (72 by
Xdefault) and the user types a space or a <NL>, the last word of the line
Xis brought down to the beginning of the next line.  Using this, one just
Xtypes a continuous stream of words and EMACS automatically inserts <NL>s
Xat appropriate places.
X
X@center(NOTE to programmers:)
X
X@quotation{EMACS actually calls up the function bound to the illegal
Xkeystroke M-FNW.  This is bound to the function @i(wrap-word)
X@index(wrap-word) by default, but can be re-bound to activate different
Xfunctions and macros at wrap time.}
X
X@section(VIEW mode)@index(VIEW mode)
X
X    VIEW mode disables all commands which can change the current
Xbuffer.  EMACS will display an error message and ring the bell every
Xtime you attempt to change a buffer in VIEW mode.
X@newpage
X@heading(Chapter @value(chapter) Summary)
X
XIn Chapter @value(chapter) you learned about modes and their effects.
X
X@begin{verbatim}
X@u(Key Binding        Keystroke               Effect)
XAdd-Mode        @b(^X-M)    Add a mode to the current buffer
X
XDelete-Mode        @b(^X-^M)    Delete a mode from the current buffer
X
XAdd-Global-Mode        @b(M-M)        Add a global mode to the
X                    current buffer
X
XDelete-Global-Mode    @b(M-^M)    Delete a global mode from the
X                    current buffer
X@end(verbatim)
X@chapter(Files)
X
XA file is simply a collection of related data.  In EMACS we are dealing
Xwith text files -- named collections of text residing on a disk (or some
Xother storage medium).  You will recall that the major entities EMACS
Xdeals with are buffers.  Disk-based versions of files are only active in
XEMACS when you are reading into or writing out of buffers.  As we have
Xalready seen, buffers and physical files are linked by associated
Xfile names.  For example, the buffer "ch7.txt" which is associated with
Xthe physical disk file "ch7.txt." You will notice that the file is
Xusually specified by the drive name or (in the case of a hard drive) a
Xpath.  Thus you can specify full file names in EMACS,
X
Xe.g. disk:\directories\filename.extension
X
XIf you do not specify a disk and directories, the default disk is used.
X
XIMPORTANT -- If you do not explicitly save your buffer to a file, all your
Xedits will be lost when you leave EMACS (although EMACS will prompt you
Xwhen you are about to lose edits by exiting).  In addition, EMACS does
Xnot protect your disk-based files from overwriting when it saves files.
XThus when you instruct EMACS to save a file to disk, it will create a
Xfile if the specified file doesn't exist, or it will overwrite the
Xpreviously saved version of the file thus replacing it.  Your old
Xversion is gone forever.
X
XIf you are at all unsure about your edits, or if (for any reason) you
Xwish to keep previous versions of a file, you can change the name of the
Xassociated file with the command @b{^X-N}.  When this file is saved
Xto disk, EMACS will create a new physical file under the new name.  The
Xearlier disk file will be preserved.
X
XFor example, let's load the file @b{fang.txt} into EMACS.  Now, type
X@b{^X-N}.  The EMACS command line prompts "name:".  Enter a new name
Xfor the file -- say @b(new.txt) and press <NL>.  The file will be
Xsaved under the new filename, and your disk directory will show both
X@b(fang.txt) and @b(new.txt).
X
XAn alternative method is to write the file directly to disk under a new
Xfilename.  Let's pull our "publish.txt" file into EMACS.  To write this
Xfile under another filename, type @b{^X-^W}.  EMACS will prompt
Xyou "write file:".  Enter an alternate filename -- @b{desktop.txt}.
XYour file will be saved as the physical file "desktop.txt".
X
XNote that in the examples above, although you have changed the names of
Xthe related files, the buffer names remain the same.  However, when you
Xpull the physical file back into EMACS, you will find that the buffer
Xname now relates to the filename.
X
XFor example -- You are working with a buffer "fang.txt" with the related
Xfile "fang.txt".  You change the name of the file to "new.txt".  EMACS
Xnow shows you working with the buffer "fang.txt" and the related file
X"new.txt".  Now pull the file "new.txt" into EMACS.  Notice that the
Xbuffer name has now changed to "new.txt".
X
XIf for any reason a conflict of buffer names occurs,(if you have files
Xof the same name on different drives for example) EMACS will prompt
Xyou "use buffer:".  Enter an alternative buffer name if you need to.
X
XFor a list of file related commands (including some we`ve already
Xseen), see the summary page.
X@newpage
X@heading(Chapter @value(chapter) Summary)
X
XIn Chapter @value(chapter) you learned some of the more advanced
Xconcepts of file naming and manipulation.  The relationship between
Xfiles and buffers was discussed in some detail.
X
X@begin(verbatim)
X@u(Key Binding    Keystroke    Effect)
X
XSave-file    @b{^X-^S}    Saves contents of current buffer with
X                associated filename on default disk/
X                directory (if not specified)
X
XWrite-File    @b{^X-^W}    Current buffer contents will be
X                saved under specified name
X
XChange-File-name
X        @b{^X-N}    The associated filename is changed
X                (or associated if not previously
X                specified) as specified
X
XFind-File    @b{^X-^F}    Reads specified file into buffer and
X                switches you to that buffer, or switches
X                to buffer in which the file has previously
X                been read
X
XRead-File    @b{^X-^R}    Reads file into buffer thus overwriting
X                buffer contents.  If file has already
X                been read into another buffer, you will
X                be switched to it
X
XView-File    @b{^X-^V}    The same as read-file except the buffer
X                is automatically put into VIEW mode thus
X                preventing any changes from being made
X@end{verbatim}
X@chapter(Screen Formatting)
X
X@section<Wrapping Text>
X
XAs we learned in the introduction, EMACS is not a word processor, but an
Xeditor.  Some simple formatting options are available however, although
Xin most cases they will not affect the appearence of the finished text
X@index(wrapping text) when it is run through the formatter.  We have
Xalready encountered WRAP mode which wraps lines longer than a certain
Xlength (default is 75 characters).  You will recall that WRAP is enabled
Xby entering @b{^X-M} and responding to the command line prompt with
X@b{wrap}.
X
XYou can also set your own wrap margin with the command @b{^X-F}
X@i(set-fill-column) @index(set-fill-column).  Notice EMACS responds
X"[Fill column is 1]." Now try typing some text.  You'll notice some very
Xstrange things happening -- your text wraps at every word!! This effect
Xoccurs because the set wrap margin command must be preceeded by a
Xnumeric argument or EMACS sets it to the first column.  Thus any text
Xyou type that extends past the first column will wrap at the most
Xconvenient line break.
X
XTo reset the wrap column to 72 characters, press the @b{<META>} key and
Xenter 72.  EMACS will respond "Arg: 72".  Now press @b<^X-F>.  EMACS
Xwill respond "[Fill column is 72]".  Your text will again wrap at the
Xmargin you've been using up to this point.
X
X@section<Reformatting Paragraphs>
X
XAfter an intensive editing session, you may find that you have
Xparagraphs containing lines of differing lengths.  Although this
Xdisparity will not affect the formatted text, aesthetic and technical
Xconcerns may make it desirable to have consistent paragraph blocks on
Xthe screen.  If you are in WRAP mode, you can reformat a paragraph with
Xthe command @b{M-Q} @i(fill-paragraph) @index(fill-paragraph).  This
Xcommand 'fills' the current paragraph reformatting it so all the lines
Xare filled and wrap logically.  The process is complex, and (especially
Xwith longer paragraphs) may take a little time.
X
X@section<Changing Case>
X
XThere may be occasions when you find it necessary to change the case of
Xthe text you've entered.  EMACS allows you to change the case of even
Xlarge amounts of text with ease.  Let's try and convert a few of the
Xoffice traditionalists to the joy of word processing.  Type in the
Xfollowing text:
X
X@quotation{Throw away your typewriter and learn to use a word processor.
XWord processing is relatively easy to learn and will increase your
Xproductivity enormously.  Enter the Computer Age and find out just how
Xmuch fun it can be!!}
X
XLet's give it a little more impact by capitalizing the first four words.
XThe first step is to define the region of text just as you would if you
Xwere doing an extensive deletion.  Set the mark at the beginning of the
Xparagraph with @b{M-<space>} @i(set-mark) and move the cursor to the
Xspace beyond "typewriter." Now enter @b{^X-^U} @i(case-region-upper).
XYour text should now look like this:
X
X@quotation{THROW AWAY YOUR TYPEWRITER and learn to use a word processor.
XWord processing is relatively easy to learn and will increase your
Xproductivity enormously.  Enter the Computer Age and find out just how
Xmuch fun it can be!!}
X
XIf you want to change the text back to lower case, type @b{^X-^L}
X@i(case-region-lower) @index(case-region-lower).  You can also
Xcapitalize individual words.  To capitalize the word "fun", position the
Xcursor in front of the word and type @b{M-U} @i(case-word-upper)
X@index(case-word-upper).  The word is now capitalized.  To change it
Xback to lower case, move the cursor back to the beginning of the word
Xand type @b{M-L} @i(case-word-lower) @index(case-word-lower).
X
XYou may also capitalize individual letters in EMACS.  The command
X@b{M-C} @i(case-word-capitalize) @index(case-word-capitalize)
Xcapitalizes the first letter after the point.  This command would
Xnormally be issued with the cursor positioned in front of the first
Xletter of the word you wish to capitalize.  If you issue it in the
Xmiddle of a word, you can end up with some strAnge looking text.
X
X@section<Tabs>
X
XUnless your formatter is instructed to take screen text literally (as
XMicroSCRIBE does in the 'verbatim' environment for example), tabs in
XEMACS generally affect screen formatting only.
X
XWhen EMACS is first started, it sets the default tab to every eighth
Xcolumn.  As long as you stay with default, every time you press the tab
Xkey a tab character, @b(^I) is inserted.  This character, like other
Xcontrol characters, is invisible -- but it makes a subtle and
Xsignificant difference to your file and editing.
X
XFor example, in default mode, press the tab key and then type the word
X@b{Test}.  "Test" appears at the eighth column.  Move your cursor to the
Xbeginning of the word and delete the backward character.  The word
Xdoesn't move back just one character, but flushes to the left margin.
XThe reason for this behavior is easily explained.  In tab default, EMACS
Xinserts a 'real' tab character when you press the tab key.  This
Xcharacter is inserted at the default position, but NO SPACES are
Xinserted between the tab character and the margin (or previous tab
Xcharacter).  As you will recall, EMACS only recognizes characters (such
Xas spaces or letters) and thus when the tab character is removed, the
Xtext beyond the tab is flushed back to the margin or previous tab mark.
X
XThis situation changes if you alter the default configuration.  The
Xdefault value may be changed by entering a numeric argument before
Xpressing the tab key.  As we saw earlier, pressing the @b{META} key and
Xentering a number allows you to specify how EMACS performs a given
Xaction.  In this case, let's specify an argument of 10 and hit the tab
Xkey.
X
XNow hit the tab key again and type @b{Test}.  Notice the word now
Xappears at the tenth column.  Now move to the beginning of the word and
Xdelete the backward character.    "Test" moves back by one character.
X
XEMACS behaves differently in these circumstances because the @b(^I)
X@index(tab handling) @i(handle-tab) @index(handle-tab) function deals
Xwith tabbing in two distinct ways.  In default conditions, or if the
Xnumeric argument of zero is used, @i(handle-tab) inserts a true tab
Xcharacter.  If, however, a non-zero numeric argument is specified,
X@i(handle-tab) inserts the correct number of spaces needed to position
Xthe cursor at the next specified tab position.  It does NOT insert the
Xsingle tab character and hence any editing functions should take account
Xof the number of spaces between tabbed columns.
X
XMany times you would like to take a line which has been created using
Xthe tab character and change it to use just spaces.  The command
X@b(^X-^D) @i(detab-line) @index(detab-line) changes any tabs from the
Xpoint to the end of the current line into the right number of spaces so
Xthe line does not change.  This is very useful for times when the file
Xmust be printed or transfered to a machine which does not understand
Xtabs.
X
XAlso, the inverse command, @b(^X-^E) @i(entab-lines) @index(entab-lines)
Xchanges multiple spaces to tabs where possible.  This is a good way to
Xshrink the size of large documents, especially with data tables.  Both
Xof these commands can take a numeric argument which will be interpeted
Xas the number of lines to en/detab.
X@newpage
X@heading(Chapter @value(chapter) Summary)
X
XIn Chapter @value(chapter) introduced some of the formatting features of
XEMACS. Text-wrap, paragraph reformatting, and tabs were discussed in
Xsome detail.  The commands in the following table were covered in the
Xchapter.
X
X@begin{verbatim}
X
X@u(Key Binding        Keystroke            Effect)
XAdd-Mode/WRAP        @b{^X-M}[WRAP]    Add wrap mode to current buffer
X
XDelete-Mode/WRAP    @b{^X-^M}[WRAP]    Remove wrap mode from current buffer
X
XSet-Fill-Column        @b{^X-F}     Set fill column to given numeric
X                    argument
X
XFill-Paragraph        @b{M-Q}        Logically reformats the current
X                    paragraph
X
XCase-Word-Upper     @b{M-U}        Text from point to end of the
X                    current word is changed to uppercase
X
XCase-Word-Lower     @b{M-L}        Text from point to end of the
X                    current word is changed to lowercase
X
XCase-Word-Capitalize    @b{M-C}        First word (or letter) after the
X                    point is capitalized
X
XCase-Region-Upper    @b{^X-^U}    The current region is uppercased
X
XCase-Region-Lower    @b{^X-^L}    The current region is lowercased
X
XHandle-Tab        @b{^I}        Tab interval is set to the given
X                    numeric argument
XEntab-Line        @b(^X-^E)    Changes multiple spaces to tabs
X                    characters where possible
XDetab-Line        @b(^X-^D)    Changes tab characters to the
X                    appropriate number of spaces
X@end{verbatim}
X@chapter(Access to the Outside World)
X
X    EMACS has the ability to interface to other programs and the
Xenvironment of the computer outside of itself.  It does this through a
Xseries of commands that allow it to talk to the computer's @b(command
Xprocessor) @index(command processor) or @b(shell) @index(shell).  Just
Xwhat this is varies between different computers.  Under MSDOS or PCDOS
Xthis is the @b(command.com) @index(command.com) command processor.
XUnder UNIX it is the @b(csh) @index(cshell) shell.  On the Atari ST is
Xcan be the Mark Williams @b(MSH) or the Beckmeyer shell.  In each case,
Xit is the part of the computer's operating system that is responcable
Xfor determining what programs are executed, and when.
X
X    The @b(^X-!) @i(shell-command) @index(shell-command) command
Xprompts the user for a command line to send out to the shell to execute.
XThis can be very useful for doing file listings and changing the
Xcurrent directory or folder.  EMACS gives control to the shell, which
Xexecuted the command, and then types @b([END]) and waits for the user to
Xtype a character before redrawing the screen and resuming editing. If
Xthe @i(shell-command) command is used from within the macro language,
Xthere is no pause.
X
X    @b(^X-@@) @i(pipe-command) @index(pipe-command) command allows
XEMACS to execute a shell command, and if the particular computer allows
Xit, send the results into a buffer which is automatically displayed on
Xthe screen. The resulting buffer, called "command" can be manipulated
Xjust like any other editing buffer. Text can be copied out of it or
Xrearanged as needed. This buffer is originally created in @b(VIEW) mode,
Xso remember to @b(^X-^Mview<NL>) in order to change it.
X
X    Many computers provide tools which will allow you to @b(filter)
X@index(filter) text, making some modifications to it along the way. A
Xvery common tool is the @b(SORT) program which accepts a file, sorts it,
Xand prints the result out.  The EMACS command, @b(^X-#) @i(filter-buffer)
Xsends the current buffer through such a filter.  Therefore, if you
Xwished to sort the current buffer on a system which supplied a sort
Xfilter, you would type @b(^X-#sort<NL>).  You can also create your own
Xfilters by writing programs and utilities which read text from the
Xkeyboard and display the results.  EMACS will use any of these which
Xwould normally be available from the current shell.
X
X    If you would like to execute another program directly, without
Xthe overhead of an intervening shell, you can use the @b(^X-$)
X@i(execute-program) @index(execute-program) command. It will prompt you
Xfor an external program and its arguments and attempt to execute it.
XLike when EMACS looks for command files, EMACS will look first in the
XHOME directory, then down the execute PATH, and finally in the current
Xdirectory for the named program. On some systems, it will automatically
Xtack the proper extension on the file name to indicate it is a program.
XOn some systems that don't support this function, @b(^X-$) will be
Xequivalent to @b(^X-!) @i(shell-command).
X
X    Sometimes, you would like to get back to the shell and execute
Xother commands, without losing the current contents of EMACS.  The
X@b(^X-C) @i(i-shell) @index(i-shell) command shells out of EMACS,
Xleaving EMACS in the computer and executing another command shell.  Most
Xsystems would allow you to return to EMACS with the "exit" command.
X
X@i(    On some systems, mainly advanced versions of UNIX, you can
Xdirect EMACS to "go into the background" with the @b(^X-D) suspend-emacs
X@index(suspend-emacs) command.  This places EMACS in the background
Xreturning you to the original command shell. EMACS can then be returned
Xto at any time with the "fg" foreground command.)
X@newpage
X@heading(Chapter @value(chapter) Summary)
X
XIn Chapter @value(chapter) introduced different ways to access the
Xcomputers shell or command processor from within EMACS.  The commands
Xin the following table were covered in the chapter.
X
X@begin{verbatim}
X
X@u(Key Binding        Keystroke            Effect)
XExecute-program        @b(^X-$)    Execute an external program
X                    directly
X
XFilter-command        @b(^X-#)    Send the current buffer through
X                    a shell filter
X
XI-shell            @b(^X-C)    Escape to a new shell
X
XPipe-command        @b(^X-@@)    Send the results of an external
X                    shell command to a buffer
X
XShell-command        @b(^X-!)    Execute one shell command
X
XSuspend-emacs        @b(^X-D)    Place EMACS in the background
X                    (some UNIX systems only)
X@end{verbatim}
X@chapter(Keyboard Macros)
X
XIn many applications, it may be necessary to repeat a series of
Xcharacters or commands frequently.  For example, a paper may require the
Xfrequent repetition of a complex formula or a long name.  You may also
Xhave a series of EMACS commands that you invoke frequently.  Keyboard
Xmacros offer a convenient method of recording and repeating these
Xcommands.
X
XImagine, for example, you are writing a scholarly paper on @i{Asplenium
Xplatyneuron}, the spleenwort fern.  Even the dedicated botanist would
Xprobably find it a task bordering on the agonizing to type
X@i{Asplenium platyneuron} frequently throughout the paper.  An
Xalternative method is 'record' the name in a keyboard macro.  Try it
Xyourself.
X
XThe command @b{^X-(} @i(begin-macro) @index(begin-macro) starts
Xrecording the all the keystrokes and commands you input.  After you've
Xtyped it, enter @b{Asplenium platyneuron}.  To stop recording, type
X@b{^X-)} @i(end-macro) @index(end-macro).  EMACS has stored all the
Xkeystrokes between the two commands.  To repeat the name you've stored,
Xjust enter @b{^X-E} @i(execute-macro) @index(execute-macro), and the
Xname "Asplenium platyneuron" appears.  You can repeat this action as
Xoften as you want, and of course as with any EMACS command, you may
Xprecede it with a numerical argument.
X
XBecause EMACS records keystrokes, you may freely intermix commands and
Xtext.  Unfortunately, you can only store one macro at a time.  Thus, if
Xyou begin to record another macro, the previously defined macro is
Xlost. Be careful to ensure that you've finished with one macro before
Xdefining another.  If you have a series of commands that you would like
Xto 'record' for future use, use the macro or procedure facilities
Xdetailed in chapter <X>.
X@newpage
X@heading(Chapter @value(chapter) Summary)
X
XChapter @value(chapter) covered keyboard macros.  You learned how to
Xrecord keystrokes and how to repeat the stored sequence.
X
X@begin{verbatim}
X@u(Key Binding        Keystroke        Effect)
X
XStart-Macro        @b{^X-(}    Starts recording all keyboard input
X
XEnd-Macro        @b{^X-)}    Stops recording keystrokes for macro
X
XExecute-Macro        @b{^X-E}    Entire sequence of recorded
X                    keystrokes is replayed
X@end{verbatim}
X@chapter(MicroEMACS Macros)
X
X    Macros are programs that are used to customize the editor and to
Xperform complicated editing tasks.  They may be stored in files or
Xbuffers and may be executed using an appropriate command, or bound to a
Xparticular keystroke.  Portions of the standard start-up file are
Ximplemented via macros, as well as the example menu system.  The
X@i(execute-macro-<n>) @index(execute-macro-<n>) commands cause the
Xmacro, numbered from 1 to 40, to be executed.  The @i(execute-file)
X@index(execute-file) command allows you to execute a macro stored in a
Xdisk file, and the @i(execute-buffer) @index(execute-buffer) command
Xallows you to execute a macro stored in a buffer.  Macros are stored for
Xeasy execution by executing files that contain the store-macro command.
X
X    If you need more than 40 macros, named macroes, called
X@b(procedures), @index(procedures) can be used.  The @i(store-procedure)
X@index(store-procedure) command takes a string argument which is the
Xname of a procedure to store.  These procedures than can be executed
Xwith the @b(M-^E) @i(execute-procedure) @index(execute-procedure) or the
X@i(run) @index(run) commands.
X
X    There are many different aspects to the macro language within
XMicroEMACS.  Editor commands are the various commands that manipulate
Xtext, buffers, windows, etc, within the editor.  Directives are commands
Xwhich control what lines get executed within a macro.  Also there are
Xvarious types of variables.  Environmental variables both control and
Xreport on different aspects of the editor.  User variables hold string
Xvalues which may be changed and inspected.  Buffer variables allow text
Xto be placed into variables.  Interactive variable allow the program to
Xprompt the user for information.  Functions can be used to manipulate
Xall these variables.
X
X@section(Constants)
X
X    All constants and variable contents in EMACS are stored as
Xstrings of characters. Numbers are stored digit by digit as characters.
XThis allows EMACS to be "typeless", not having different variables types
Xbe legal in different contexts. This has the disadvantage of forcing the
Xuser to be more carefull about the context of the statements variables
Xare placed in, but in turn gives them more flexibility in where they
Xcan place variables. Needless to say, this also allows EMACS's expression
Xevaluator to be both consice and quick.
X
X    Wherever statements need to have arguments, it is legal to place
Xconstants.  A constant is a double quote character, followed by a string
Xof characters, and terminated by another double quote character. To
Xrepresent various special characters within a constant, the tilde (~)
Xcharacter is used. The character following the tilde is interpeted
Xaccording to the following table:
X
X@begin(verbatim)
X@u(Sequence    Result)
X~n        ^J    linefeed/newline, (EMACS newline character)
X~r        ^M    carraige return
X~~        ~
X~b        ^H    backspace
X~f        ^L    formfeed
X~t        ^I    tab
X~"        "
X@end(verbatim)
X
X    Any character not in the table which follows a tilde will be
Xpassed unmodified.  This action is similar to the @b(^Q)
X@i(quote-character) command available from the keyboard.
X
X    The double quotes around constants are not needed if the
Xconstant contains no internal whitespace and it also does not happen to
Xmeet the rules for any other EMACS commands, directives, variables, or
Xfunctions. This is reasonable useful for numeric constants.
X
X@section(Variables)
X
X    Variables in MicroEMACS can be used to return values within
Xexpressions, as repeat counts to editing commands, or as text to be
Xinserted into buffers and messages.  The value of these variables is set
Xusing the set (^X-A) command.  For example, to set the current fill
Xcolumn to 64 characters, the following macro line would be used:
X
X    set $fillcol 64
X
X    or to have the contents of @b(%name) inserted at the point in the
Xcurrent buffer, the command to use would be:
X
X    insert-string %name
X@newpage
X@subsection(Environmental Variables)
X
X    "What good is a quote if you can't change it?"
X
X    These variables are used to change different aspects of the way
Xthe editor works.  Also they will return the current settings if used as
Xpart of an expression.  All environmental variable names begin with a
Xdollar sign ($) and are in lower case.
X
X@begin(description)
X$acount@\The countdown of inserted characters until the next save-file.
X
X$asave@\The number of inserted characters between automatic file-saves
Xin ASAVE mode.
X
X$cbufname@\Name of the current buffer
X
X$cfname@\File name of the current buffer
X
X$cmode@\Integer containing the mode of the current buffer. (See Appendix F
Xfor values)
X
X$curchar@\Character currently at the point
X
X$curcol@\Current column of point in current buffer
X
X$curline@\Current line of point in current buffer
X
X$curwidth@\Number of columns used currently
X
X$cwline@\Current display line in current window
X
X$debug@\Flag to trigger macro debugging (try it... you'll like it!)
X
X$discmd@\Flag to disable the echoing of messages on the command line
X
X$disinp@\Flag to disable the echoing of characters during command line input
X
X$fillcol@\Current fill column
X
X$flicker@\Flicker Flag set to TRUE if IBM CGA set to FALSE for most others
X
X$gflags@\Global flags controlling some EMACS internal functions (See
Xappendix G for details)
X
X$gmode@\Global mode flags. (See Appendix F for values)
X
X$lastkey@\[READ ONLY]Last keyboard character typed
X
X$line@\The current line in the current buffer can be retrieved and
Xset with this environment variable
X
X$lwidth@\[READ ONLY]Returns the number of characters in the current line
X
X$match@\[READ ONLY]Last string matched in a magic mode search
X
X$pagelen@\Number of screen lines used currently
X
X$palette@\string used to control the palette register settings on
Xgraphics versions.  The usually form consists of groups of three octal
Xdigits setting the red, green, and blue levels.
X
X$pending@\[READ ONLY]Flag to determine if there are user keystrokes
Xwaiting to be processed.
X
X$progname@\[READ ONLY]Always contains the string "MicroEMACS" for
Xstandard MicroEMACS.  Could be something else if EMACS is incorporated
Xas part of someone else's program
X
X$replace@\Current default replace string
X
X$rval@\This contains the return value from the last subprocess which was
Xinvoked from EMACS
X
X$search@\Current default search string
X
X$seed@\Integer seed of the random number generator
X
X$sres@\Current screen resolution (CGA, MONO or EGA on the IBM-PC driver.
XLOW, MEDIUM, HIGH or DENSE on the Atari ST1040, NORMAL on all others)
X
X$status@\[READ ONLY]Status of the success of the last command (TRUE or
XFALSE).  This is usually used with !force to check on the success of a
Xsearch, or a file operation.
X
X$target@\Current target for line moves (setting this fool's EMACS into
Xbelieving the last command was a line move)
X
X$tpause@\Controls the length of the pause to display a matched fence
Xwhen the current buffer is in CMODE and a close fence has been typed
X
X$version@\[READ ONLY]Contains the current MicroEMACS version number
X
X$wline@\Number of display lines in current window
X@end(description)
X
X    Obviously, many more of these variables will be availible in
Xfuture releases of MicroEMACS. (Yes, send a vote for your favorite new
Xenvironmental variables today).
X
X@subsection(User variables)
X
X    User variables allow you, the user, to store strings and
Xmanipulate them.  These strings can be pieces of text, numbers (in text
Xform), or the logical values @b(TRUE) and @b(FALSE).  These variables
Xcan be combined, tested, inserted into buffers, and otherwise used to
Xcontrol the way your macros execute.  At the moment, up to 255 user
Xvariables may be in use in one editing session.  All users variable
Xnames must begin with a percent sign (%) and may contain any printing
Xcharacters.  Only the first 10 characters are significant (ie
Xdifferences beyond the tenth character are ignored).  Most operators
Xwill truncate strings to a length of 128 characters.
X
X@subsection(Buffer Variables)
X
X    Buffer variables are special in that they can only be queried
Xand cannot be set.  What buffer variables are is a way to take text from
Xa buffer and place it in a variable. For example, if I have a buffer by
Xthe name of RIGEL2, and it contains the text:
X
X@begin(verbatim)
X@begin(group)
X    Richmond
X    Lafayette
X    <*>Bloomington        (where <*> is the current point)
X    Indianapolis
X    Gary
X    =* MicroEMACS 3.9e (WRAP) == rigel2 == File: /data/rigel2.txt =====
X@end(group)
X@end(verbatim)
X
X    and within a command I reference #rigel2, like:
X
X    insert-string #rigel2
X
X    MicroEMACS would start at the current point in the RIGEL2
Xbuffer and grab all the text up to the end of that line and pass that
Xback.  Then it would advance the point to the beginning of the next line.
XThus, after our last command executes, the string "Bloomington" gets
Xinserted into the current buffer, and the buffer RIGEL2 now looks like
Xthis:
X
X@begin(verbatim)
X@begin(group)
X    Richmond
X    Lafayette
X    Bloomington
X    <*>Indianapolis        (where <*> is the current point)
X    Gary
X    =* MicroEMACS 3.9e (WRAP) == rigel2 == File: /data/rigel2.txt =====
X@end(group)
X@end(verbatim)
X
X    as you have probably noticed, a buffer variable consists of the
Xbuffer name, preceded by a pound sign (#).
X
X@subsection(Interactive variables)
X
X    Interactive variables are actually a method to prompt the user
Xfor a string.  This is done by using an at sign (@@) followed either with
Xa quoted string, or a variable containing a string.  The string is the
Xplaced on the bottom line, and the editor waits for the user to type in
Xa string.  Then the string typed in by the users is returned as the
Xvalue of the interactive variable.  For example:
X
X@begin(verbatim)
X    set %quest "What file? "
X    find-file @@%quest
X@end(verbatim)
X
X    will ask the user for a file name, and then attempt to find it.
XNote also that complex expressions can be built up with these
Xoperators, such as:
X
X@verbatim(@@&cat &cat "File to decode[" %default "]: ")
X
X    which prompts the user with the concatinated string.
X
X@section(Functions)
X
X    Functions can be used to manipulate variables in various ways.
XFunctions can have one, two, or three arguments.  These arguments will
Xalways be placed after the function on the current command line.  For
Xexample, if we wanted to increase the current fill column by two, using
Xemacs's set (^X-A) command, we would write:
X
X@begin(group)
X@begin(verbatim)
X    set $fillcol &add $fillcol 2
X     \    \      \      \     \____second operand
X      \     \    \      \_________first operand
X       \      \     \_______________function to execute
X        \      \_____________________variable to set
X         \___________________________set (^X-A) command
X@end(verbatim)
X@end(group)
X
X    Function names always begin with the ampersand (&) character,
Xand are only significant to the first three characters after the
Xampersand.  Functions will normal expect one of three types of
Xarguments, and will automatically convert types when needed.
X
X@begin(description)
X<num>@\an ascii string of digits which is interpeted as a numeric value.
XAny string which does not start with a digit or a minus sign (-) will be
Xconsidered zero.
X
X<str>@\An arbitrary string of characters.  At the moment, strings are
Xlimited to 128 characters in length.
X
X<log>@\A logical value consisting of the string "TRUE" or "FALSE".
XNumeric strings will also evaluate to "FALSE" if they are equal to zero,
Xand "TRUE" if they are non-zero.  Arbitrary text strings will have the
Xvalue of "FALSE".
X@end(description)
X
X    A list of the currently availible functions follows: (Once
Xagain, send in those votes on what kind of functions you would like to
Xsee added!) Functions are always used in lower case, the uppercase
Xletters in the function table are the short form of the function (ie
X&div for ÷).
X
X@begin(verbatim)
XNumeric Functions:    (returns <num>)
X
X&ADD        <num> <num>    Add two numbers
X&SUB        <num> <num>    Subtract the second number from the first
X&TIMes        <num> <num>    Multiply two numbers
X&DIVide        <num> <num>    Divide the first number by the second
X                giving an integer result
X&MOD        <num> <num>    Return the reminder of dividing the
X                first number by the second
X&NEGate        <neg>        Multiply the arg by -1
X&LENgth        <str>        Returns length of string
X&SINdex        <str1> <str2>    Finds the position of <str2> within
X                <str1>. Returns zero if not found.
X&ASCii        <str>        Return the ascii code of the first
X                character in <str>
X&RND        <num>        Returns a random integer between 1 and <num>
X&ABS        <num>        Returns the absolute value of <num>
X&BANd        <num> <num>    Bitwise AND function
X&BOR        <num> <num>    Bitwise OR function
X&BXOr        <num> <num>    Bitwise XOR function
X&BNOt        <num>        Bitwise NOT function
X
XString manipulation functions:    (returns <str>)
X
X&CAT        <str> <str>    Concatinate the two strings to form one
X&LEFt        <str> <num>    return the <num> leftmost characters
X                from <str>
X&RIGht        <str> <num>    return the <num> rightmost characters
X                from <str>
X&MID        <str> <num1> <num2>
X                Starting from <num1> position in <str>,
X                return <num2> characters.
X&UPPer        <str>        Uppercase <str>
X&LOWer        <str>        lowercase <str>
X&CHR        <num>        return a string with the character
X                represented by ascii code <num>
X>K                return a string containing a single
X                keystroke from the user
X&ENV        <str>        If the operating system is capable, this
X                returns the environment string associated
X                with <str>
X&BIND        <str>        return the function name bound to the
X                keystroke <str>
X&ENV        <str>        Returns the operating system value
X                attached to environmental variable <str>
X&FINd        <str>        Find the named file <str> along the
X                path and return its full file specification
X                or an empty string if none exists
X
XLogical Testing functions:    (returns <log>)
X
X&NOT        <log>        Return the opposite logical value
X&AND        <log1> <log2>    Returns TRUE if BOTH logical arguments
X                are TRUE
X&OR        <log1> <log2>    Returns TRUE if either argument
X                is TRUE
X&EQUal        <num> <num>    If <num> and <num> are numerically
X                equal, return TRUE
X&LESs        <num1> <num2>    If <num1> is less than <num2>, return
X                TRUE.
X&GREater    <num1> <num2>    If <num1> is greater than, or equal to
X                <num2>, return TRUE.
X&SEQual        <str1> <str2>    If the two strings are the same, return
X                TRUE.
X&SLEss        <str1> <str2>    If <str1> is less alphabetically than
X                <str2>, return TRUE.
X&SGReater    <str1> <str2>    If <str1> is alphabetically greater than
X                or equal to <str2>, return TRUE.
X&FINd        <str>        Does the named file <str> exist?
X
XSpecial Functions:
X
X&INDirect    <str>        Evaluate <str> as a variable.
X@end(verbatim)
X
X    This last function deserves more explanation. The &IND function
Xevaluates its argument, takes the resulting string, and then uses it as
Xa variable name.  For example, given the following code sequence:
X
X@begin(verbatim)
X    ; set up reference table
X
X    set %one    "elephant"
X    set %two    "giraffe"
X    set %three    "donkey"
X
X    set %index "two"
X    insert-string &ind %index
X@end(verbatim)
X
X    the string "giraffe" would have been inserted at the point in
Xthe current buffer.  This indirection can be safely nested up to about
X10 levels.
X
X@section(Directives)
X
X    Directives are commands which only operate within an executing
Xmacro, ie they do not make sense as a single command. As such, they
Xcannot be called up singly or bound to keystroke. Used within macros,
Xthey control what lines are executed and in what order.
X
X    Directives always start with the exclamation mark (!) character
Xand must be the first thing placed on a line.  Directives executed
Xinteractively (via the execute-command-line command) will be ignored.
X
X@subsection(!ENDM Directive)
X
X    This directive is used to terminate a macro being stored. For
Xexample, if a file is being executed contains the text:
X
X@begin(verbatim)
X    ;    Read in a file in view mode, and make the window red
X
X    26    store-macro
X        find-file @@"File to view: "
X        add-mode "view"
X        add-mode "red"
X    !endm
X
X    write-message "[Consult macro has been loaded]"
X@end(verbatim)
X
X    only the lines between the store-macro command and the !ENDM
Xdirective are stored in macro 26.  Both numbered macroes and named
Xprocedures (via the @i(store-procedure) command) should be terminated with
Xthis directive.
X
X@subsection(!FORCE Directive)
X
X    When MicroEMACS executes a macro, if any command fails, the
Xmacro is terminated at that point. If a line is preceeded by a !FORCE
Xdirective, execution continues weather the command succeeds or not. For
Xexample:
X
X@begin(verbatim)
X    ;    Merge the top two windows
X
X    save-window        ;remember what window we are at
X    1 next-window        ;go to the top window
X    delete-window        ;merge it with the second window
X    !force restore-window    ;This will continue regardless
X    add-mode "red"
X@end(verbatim)
X
X@subsection(!IF, !ELSE, and !ENDIF Directives)
X
X    This directive allows statements only to be executed if a
Xcondition specified in the directive is met.  Every line following the
X!IF directive, until the first !ELSE or !ENDIF directive, is only
Xexecuted if the expression following the !IF directive evaluates to a
XTRUE value.  For example, the following macro segment creates the
Xportion of a text file automatically.  (yes believe me, this will be
Xeasier to understand then that last explanation....)
X
X@begin(verbatim)
X    !if &sequal %curplace "timespace vortex"
X        insert-string "First, rematerialize~n"
X    !endif
X    !if &sequal %planet "earth"    ;If we have landed on earth...
X        !if &sequal %time "late 20th century"  ;and we are then
X            write-message "Contact U.N.I.T."
X        !else
X            insert-string "Investigate the situation....~n"
X            insert-string "(SAY 'stay here Sara')~n"
X        !endif
X    !else
X        set %conditions @@"Atmosphere conditions outside? "
X        !if &sequal %conditions "safe"
X            insert-string &cat "Go outside......" "~n"
X            insert-string "lock the door~n"
X        !else
X            insert-string "Dematerialize..try somewhen else"
X            newline
X        !endif
X    !endif
X@end(verbatim)
X
X@subsection(!GOTO Directive)
X
X    Flow can be controlled within a MicroEMACS macro using the !GOTO
Xdirective. It takes as an argument a label. A label consists of a line
Xstarting with an asterisk (*) and then an alphanumeric label.  Only
Xlabels in the currently executing macro can be jumped to, and trying to
Xjump to a non-existing label terminates execution of a macro.  For
Xexample..
X
X@begin(verbatim)
X    ;Create a block of DATA statements for a BASIC program
X
X        insert-string "1000 DATA "
X        set %linenum 1000
X
X    *nxtin
X        update-screen        ;make sure we see the changes
X        set %data @@"Next number: "
X        !if &equal %data 0
X            !goto finish
X        !endif
X
X        !if &greater $curcol 60
X            2 delete-previous-character
X            newline
X            set %linenum &add %linenum 10
X            insert-string &cat %linenum " DATA "
X        !endif
X
X        insert-string &cat %data ", "
X        !goto nxtin
X
X    *finish
X
X        2 delete-previous-character
X        newline
X@end(verbatim)
X
X@subsection(!WHILE and !ENDWHILE Directives)
X
X    This directive allows you to set up repetitive tasks easily and
Xefficiently. If a group of statements need to be executed while a
Xcertain condition is true, enclose them with a while loop. For example,
X
X@begin(verbatim)
X    !while &less $curcol 70
X        insert-string &cat &cat "[" #stuff "]"
X    !endwhile
X@end(verbatim)
X
X    places items from buffer "item" in the current line until the
Xcursor is at or past column 70.  While loops may be nested and can
Xcontain and be the targets of !GOTOs with no ill effects. Using a while
Xloop to enclose a repeated task will run much faster than the
Xcorresponding construct using !IFs.
X
X@subsection(!BREAK Directive)
X
X    This directive allows the user to abort out of the currently
Xmost inner while loop, regardless of the condition.  It is often used
Xto abort processing for error conditions.  For example:
X
X@begin(verbatim)
X;    Read in files and substitute "begining" with "beginning"
X
X    set %filename #list
X    !while ¬ &seq %filename "<end>"
X!force        find-file %filename
X        !if &seq $status FALSE
X            write-message "[File read error]"
X            !break
X        !endif
X        beginning-of-file
X        replace-string "begining" "beginning"
X        save-file
X        set %filename #list
X    !endwhile
X@end(verbatim)
X
X    This while loop will process files until the list is exhausted
Xor there is an error while reading a file.
X
X@subsection(!RETURN Directive)
X
X    The !RETURN Directive causes the current macro to exit, either
Xreturning to the caller (if any) or to interactive mode.  For example:
X
X@begin(verbatim)
X    ;    Check the monitor type and set %mtyp
X
X    !if &sres "CGA"
X        set %mtyp 1
X        !return
X    !else
X        set %mtyp 2
X    !endif
X
X    insert-string "You are on a MONOCHROME machine!~n"
X@end(verbatim)
X@appendix(MicroEMACS Command Line Switches and Startup Files)
X
X@index(startup files)
X    When EMACS first executes, it always searches for a file,
Xcalled @b(.emacsrc) @i(under most UNIX systems) or @b(emacs.rc) @i(on
Xmost other systems) @index(emacs.rc) @index(.emacsrc) which it will
Xexecute as EMACS macros before it reads in the named source files. This
Xfile normally contains EMACS macroes to bind the function keys to
Xuseful functions and load various usefull macros.  The contents of this
Xfile will probably vary from system to system and can be modified by the
Xuser as desired.
X
X    When searching for this file, EMACS looks for it in this order.
XFirst, it attempts to find a definition for "@b(HOME)" in the
Xenvironment.  It will look in that directory first.  Then it searches