Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!husc6!hao!ames!necntc!ncoast!allbery
From: nwd@j.cc.purdue.edu (Daniel Lawrence)
Newsgroups: comp.sources.misc
Subject: MicroEmacs 3.9 Manual (5 of 6)
Message-ID: <5818@ncoast.UUCP>
Date: Wed, 25-Nov-87 23:17:24 EST
Article-I.D.: ncoast.5818
Posted: Wed Nov 25 23:17:24 1987
Date-Received: Mon, 30-Nov-87 01:08:14 EST
Sender: allbery@ncoast.UUCP
Lines: 1424
Approved: allbery@ncoast.UUCP
X-Archive: comp.sources.misc/8711/16


X          Modes                                 MicroEMACS Reference Manual
X
X
X          7.7  WRAP mode
X
X
X                  Wrap  mode  is  used  when  typing  in  continuous  text.
X          Whenever the cursor is past the currently set fill column  (72 by
X          default) and the user types a space or a <NL>,  the  last word of
X          the line  is  brought  down  to  the  beginning of the next line.
X          Using this, one just types a continuous stream of words and EMACS
X          automatically inserts <NL>s at appropriate places.
X
X                                NOTE to programmers:
X
X               EMACS actually  calls  up  the  function  bound  to the
X               illegal keystroke M-FNW.  This is bound to the function
X               wrap-word by default, but can be  re-bound  to activate
X               different functions and macros at wrap time.
X
X
X          7.8  VIEW mode
X
X
X                  VIEW mode disables  all  commands  which  can  change the
X          current buffer.  EMACS will display an error message and ring the
X          bell every time you attempt to change a buffer in VIEW mode.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X          31
X
X
X
X
X
X
X          MicroEMACS Reference Manual                                 Modes
X
X
X
X
X
X
X                                  Chapter 7 Summary
X
X
X                  In Chapter 7 you learned about modes and their effects.
X
X          Key Binding             Keystroke                      Effect
X          Add-Mode                ^X-M            Add a mode to the current buffer
X
X          Delete-Mode             ^X-^M           Delete a mode from the current
X                                                  buffer
X
X          Add-Global-Mode         M-M             Add a global mode to the
X                                                  current buffer
X
X          Delete-Global-Mode      M-^M            Delete a global mode from the
X                                                  current buffer
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X                                                                         32
X
X
X
X
X
X
X          Files                                 MicroEMACS Reference Manual
X
X
X
X
X
X
X
X
X                                      Chapter 8
X
X                                        Files
X
X
X                  A file is simply a collection of related data.   In EMACS
X          we  are  dealing  with  text  files -- named collections of  text
X          residing  on a disk (or some other storage  medium).    You  will
X          recall  that the major entities EMACS  deals  with  are  buffers.
X          Disk-based  versions  of  files are only active in EMACS when you
X          are reading into or writing out  of  buffers.  As we have already
X          seen, buffers and physical  files  are  linked by associated file
X          names.  For example, the  buffer  "ch7.txt"  which  is associated
X          with the physical disk file "ch7.txt." You will  notice  that the
X          file  is usually specified by the drive name or (in the case of a
X          hard drive) a  path.    Thus  you  can specify full file names in
X          EMACS,
X
X                  e.g. disk:\directories\filename.extension
X
X                  If you do not specify a disk and directories, the default
X          disk is used.
X
X                  IMPORTANT -- If you do not explicitly save your buffer to
X          a  file,  all  your edits will  be  lost  when  you  leave  EMACS
X          (although EMACS will prompt you when you are about to  lose edits
X          by exiting).  In addition, EMACS does not protect your disk-based
X          files from overwriting  when  it  saves  files.    Thus  when you
X          instruct EMACS to save a file to disk, it will  create  a file if
X          the  specified  file  doesn't  exist,  or it will  overwrite  the
X          previously saved version of the file thus replacing it.  Your old
X          version is gone forever.
X
X                  If you are at all unsure about your edits, or if (for any
X          reason) you wish  to  keep  previous  versions of a file, you can
X          change the name of  the  associated  file  with the command ^X-N.
X          When this file is saved to disk, EMACS will create a new physical
X          file  under  the  new  name.    The  earlier  disk  file will  be
X          preserved.
X
X                  For example, let's load  the  file  fang.txt  into EMACS.
X          Now, type ^X-N.  The EMACS command line prompts "name:".  Enter a
X          new name for the file --  say  new.txt  and press <NL>.  The file
X          will be saved under  the  new  filename,  and your disk directory
X          will show both fang.txt and new.txt.
X
X                  An alternative method is  to  write  the file directly to
X          disk under a new  filename.    Let's  pull our "publish.txt" file
X
X
X          33
X
X
X
X
X
X
X          MicroEMACS Reference Manual                                 Files
X
X
X          into EMACS.  To write this file under another filename,  type ^X-
X          ^W.  EMACS  will  prompt  you  "write file:".  Enter an alternate
X          filename -- desktop.txt.  Your file will be saved as the physical
X          file "desktop.txt".
X
X                  Note  that  in  the  examples  above,  although  you have
X          changed the names of the related files, the  buffer  names remain
X          the same.   However,  when  you  pull the physical file back into
X          EMACS,  you will find that the buffer name  now  relates  to  the
X          filename.
X
X                  For example --  You  are working with a buffer "fang.txt"
X          with the related  file  "fang.txt".    You change the name of the
X          file to "new.txt".   EMACS  now shows you working with the buffer
X          "fang.txt" and the related  file  "new.txt".    Now pull the file
X          "new.txt" into EMACS.    Notice  that  the  buffer  name  has now
X          changed to "new.txt".
X
X                  If for any  reason  a conflict of buffer names occurs,(if
X          you have files of the same name on different drives  for example)
X          EMACS will prompt you "use buffer:".  Enter an alternative buffer
X          name if you need to.
X
X                  For a list of file related commands (including some we`ve
X          already seen), see the summary page.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X                                                                         34
X
X
X
X
X
X
X          Files                                 MicroEMACS Reference Manual
X
X
X
X
X
X
X                                  Chapter 8 Summary
X
X
X                  In  Chapter  8  you  learned  some of the  more  advanced
X          concepts of  file  naming  and  manipulation.    The relationship
X          between files and buffers was discussed in some detail.
X
X          Key Binding     Keystroke       Effect
X
X          Save-file       ^X-^S           Saves contents of current buffer with
X                                          associated filename on default disk/
X                                          directory (if not specified)
X
X          Write-File      ^X-^W           Current buffer contents will be
X                                          saved under specified name
X
X          Change-File-name
X                          ^X-N            The associated filename is changed
X                                          (or associated if not previously
X                                          specified) as specified
X
X          Find-File       ^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
X          Read-File       ^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
X          View-File       ^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
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X          35
X
X
X
X
X
X
X          MicroEMACS Reference Manual                     Screen Formatting
X
X
X
X
X
X
X
X
X                                      Chapter 9
X
X                                  Screen Formatting
X
X
X          9.1  Wrapping Text
X
X
X                  As  we  learned  in the introduction, EMACS is not a word
X          processor, but an editor.   Some  simple  formatting  options are
X          available however, although in  most  cases  they will not affect
X          the appearence of the finished text when it is  run  through  the
X          formatter.  We have already  encountered  WRAP  mode  which wraps
X          lines longer than a  certain  length  (default is 75 characters).
X          You  will  recall  that WRAP is  enabled  by  entering  ^X-M  and
X          responding to the command line prompt with wrap.
X
X                  You  can  also  set your own wrap margin with the command
X          ^X-F set-fill-column.  Notice  EMACS  responds  "[Fill  column is
X          1]." Now try typing  some  text.  You'll notice some very strange
X          things happening -- your text wraps at every  word!!  This effect
X          occurs because the set wrap margin command must be preceeded by a
X          numeric argument or EMACS sets it to the first column.   Thus any
X          text you type that extends past the first column will wrap at the
X          most convenient line break.
X
X                  To  reset the wrap column to  72  characters,  press  the
X          <META> key and  enter  72.    EMACS  will respond "Arg: 72".  Now
X          press ^X-F.  EMACS will respond "[Fill column is 72]".  Your text
X          will again wrap at the margin you've been using up to this point.
X
X
X          9.2  Reformatting Paragraphs
X
X
X                  After an intensive editing session, you may find that you
X          have paragraphs containing lines of differing lengths.   Although
X          this disparity  will not affect the formatted text, aesthetic and
X          technical concerns  may  make  it  desirable  to  have consistent
X          paragraph blocks on the screen.  If you are in WRAP mode, you can
X          reformat a paragraph  with  the command M-Q fill-paragraph.  This
X          command 'fills'  the current paragraph reformatting it so all the
X          lines are filled and wrap logically.  The process is complex, and
X          (especially with longer paragraphs) may take a little time.
X
X
X
X
X
X
X                                                                         36
X
X
X
X
X
X
X          Screen Formatting                     MicroEMACS Reference Manual
X
X
X          9.3  Changing Case
X
X
X                  There  may be occasions when you  find  it  necessary  to
X          change the case of the text you've entered.  EMACS allows  you to
X          change the case of even large  amounts  of text with ease.  Let's
X          try and convert a few of the office traditionalists to the joy of
X          word processing.  Type in the following text:
X
X               Throw  away your typewriter and learn  to  use  a  word
X               processor.  Word processing is relatively easy to learn
X               and will increase  your productivity enormously.  Enter
X               the Computer Age and find out just how much fun  it can
X               be!!
X
X                  Let's give it a  little  more  impact by capitalizing the
X          first four words.  The first step is to define the region of text
X          just as you would if you  were  doing an extensive deletion.  Set
X          the  mark  at  the beginning of the paragraph with M-<space> set-
X          mark  and  move  the cursor to the space beyond "typewriter." Now
X          enter ^X-^U case-region-upper.   Your  text  should now look like
X          this:
X
X               THROW  AWAY YOUR TYPEWRITER and learn  to  use  a  word
X               processor.  Word processing is relatively easy to learn
X               and will increase  your productivity enormously.  Enter
X               the Computer Age and find out just how much fun  it can
X               be!!
X
X                  If you want to  change  the text back to lower case, type
X          ^X-^L  case-region-lower.   You can  also  capitalize  individual
X          words.   To capitalize the word "fun",  position  the  cursor  in
X          front of the word and type M-U case-word-upper.  The word  is now
X          capitalized.  To change it back to lower case,  move  the  cursor
X          back to the beginning of the word and type M-L case-word-lower.
X
X                  You may also capitalize individual letters in EMACS.  The
X          command M-C  case-word-capitalize  capitalizes  the  first letter
X          after the point.  This command would normally be issued  with the
X          cursor positioned in front of the first letter of  the  word  you
X          wish to capitalize.  If you issue it in the middle of a word, you
X          can end up with some strAnge looking text.
X
X
X          9.4  Tabs
X
X
X                  Unless your formatter is instructed to  take  screen text
X          literally (as MicroSCRIBE does in the 'verbatim'  environment for
X          example), tabs in EMACS generally affect screen formatting only.
X
X                  When EMACS is first started, it sets the  default  tab to
X          every eighth column.    As  long  as you stay with default, every
X          time you press the tab key a tab character, ^I is inserted.  This
X
X
X          37
X
X
X
X
X
X
X          MicroEMACS Reference Manual                     Screen Formatting
X
X
X          character, like  other control characters, is invisible -- but it
X          makes  a  subtle  and  significant  difference to your  file  and
X          editing.
X
X                  For example, in default mode,  press the tab key and then
X          type the word Test.  "Test"  appears  at the eighth column.  Move
X          your cursor to the beginning of the word and delete  the backward
X          character.    The  word doesn't move back just one character, but
X          flushes  to the left margin.  The reason  for  this  behavior  is
X          easily explained.  In  tab  default,  EMACS  inserts a 'real' tab
X          character when you press the tab key.  This character is inserted
X          at the default position, but NO SPACES are  inserted  between the
X          tab character and the margin (or previous tab character).  As you
X          will recall,  EMACS only recognizes characters (such as spaces or
X          letters) and thus when  the  tab  character  is removed, the text
X          beyond  the tab is flushed back to the  margin  or  previous  tab
X          mark.
X
X                  This  situation  changes  if   you   alter   the  default
X          configuration.    The  default value may be changed by entering a
X          numeric argument before pressing the tab key.  As we saw earlier,
X          pressing the META key and entering a number allows you to specify
X          how EMACS performs a  given  action.  In this case, let's specify
X          an argument of 10 and hit the tab key.
X
X                  Now hit the tab key again and type Test.  Notice the word
X          now  appears  at  the tenth column.  Now move to the beginning of
X          the word and delete the  backward character. "Test" moves back by
X          one character.
X
X                  EMACS behaves differently in these  circumstances because
X          the ^I handle-tab function deals  with  tabbing  in  two distinct
X          ways.  In default conditions, or if the numeric argument  of zero
X          is used, handle-tab inserts a true tab character.  If, however, a
X          non-zero numeric argument is  specified,  handle-tab  inserts the
X          correct number of spaces  needed  to  position  the cursor at the
X          next specified tab position.    It does NOT insert the single tab
X          character and  hence any editing functions should take account of
X          the number of spaces between tabbed columns.
X
X                  Many times you would  like  to take a line which has been
X          created using the tab character and change it to use just spaces.
X          The command ^X-^D detab-line changes any tabs from  the  point to
X          the  end  of  the current line into the right number of spaces so
X          the line does not change.  This is very useful for times when the
X          file must be printed or transfered to a machine  which  does  not
X          understand tabs.
X
X                  Also,  the inverse  command,  ^X-^E  entab-lines  changes
X          multiple  spaces  to  tabs where possible.  This is a good way to
X          shrink the  size of large documents, especially with data tables.
X          Both of these commands can take a numeric argument which  will be
X          interpeted as the number of lines to en/detab.
X
X
X
X                                                                         38
X
X
X
X
X
X
X          Screen Formatting                     MicroEMACS Reference Manual
X
X
X
X
X
X
X                                  Chapter 9 Summary
X
X
X                  In Chapter 9 introduced some of  the  formatting features
X          of  EMACS.  Text-wrap,  paragraph  reformatting,  and  tabs  were
X          discussed  in  some  detail.  The commands in the following table
X          were covered in the chapter.
X
X
X          Key Binding             Keystroke                   Effect
X          Add-Mode/WRAP           ^X-M[WRAP]      Add wrap mode to current buffer
X
X          Delete-Mode/WRAP        ^X-^M[WRAP]     Remove wrap mode from current
X                                                  buffer
X
X          Set-Fill-Column         ^X-F            Set fill column to given numeric
X                                                  argument
X
X          Fill-Paragraph          M-Q             Logically reformats the current
X                                                  paragraph
X
X          Case-Word-Upper         M-U             Text from point to end of the
X                                                  current word is changed to
X          uppercase
X
X          Case-Word-Lower         M-L             Text from point to end of the
X                                                  current word is changed to
X          lowercase
X
X          Case-Word-Capitalize    M-C             First word (or letter) after the
X                                                  point is capitalized
X
X          Case-Region-Upper       ^X-^U           The current region is uppercased
X
X          Case-Region-Lower       ^X-^L           The current region is lowercased
X
X          Handle-Tab              ^I              Tab interval is set to the given
X                                                  numeric argument
X          Entab-Line              ^X-^E           Changes multiple spaces to tabs
X                                                  characters where possible
X          Detab-Line              ^X-^D           Changes tab characters to the
X                                                  appropriate number of spaces
X
X
X
X
X
X
X
X
X
X
X          39
X
X
X
X
X
X
X          MicroEMACS Reference Manual           Access to the Outside World
X
X
X
X
X
X
X
X
X                                     Chapter 10
X
X                             Access to the Outside World
X
X
X                  EMACS has  the ability to interface to other programs and
X          the environment of the computer outside of itself.  It  does this
X          through  a  series  of  commands  that  allow  it  to talk to the
X          computer's command processor or shell.   Just what this is varies
X          between  different  computers.   Under MSDOS or PCDOS this is the
X          command.com command processor.  Under UNIX it is  the  csh shell.
X          On  the Atari ST is can be the Mark Williams MSH or the Beckmeyer
X          shell.  In each case, it is the part of the  computer's operating
X          system that is  responcable  for  determining  what  programs are
X          executed, and when.
X
X                  The ^X-! shell-command command  prompts  the  user  for a
X          command line to send out to the shell  to  execute.  This  can be
X          very  useful for doing file listings  and  changing  the  current
X          directory or folder.   EMACS  gives  control  to the shell, which
X          executed the command, and then types [END] and waits for the user
X          to  type a character before redrawing  the  screen  and  resuming
X          editing. If the shell-command command  is  used  from  within the
X          macro language, there is no pause.
X
X                  ^X-@ pipe-command command allows EMACS to execute a shell
X          command,  and  if  the particular computer allows  it,  send  the
X          results into a buffer which  is  automatically  displayed  on the
X          screen. The resulting buffer, called "command" can be manipulated
X          just like any other editing buffer. Text can be copied out  of it
X          or rearanged as needed. This buffer is originally created in VIEW
X          mode, so remember to ^X-^Mview<NL> in order to change it.
X
X                  Many computers provide  tools  which  will  allow  you to
X          filter text, making some  modifications  to  it  along the way. A
X          very common tool is the SORT program which accepts a  file, sorts
X          it, and prints the  result  out.  The EMACS command, ^X-# filter-
X          buffer  sends  the  current  buffer   through   such   a  filter.
X          Therefore, if you wished  to  sort the current buffer on a system
X          which supplied a sort filter, you would type  ^X-#sort<NL>.   You
X          can  also  create  your  own  filters  by  writing  programs  and
X          utilities  which  read  text from the keyboard  and  display  the
X          results.  EMACS  will  use  any  of these which would normally be
X          available from the current shell.
X
X                  If you would like to  execute  another  program directly,
X          without the overhead of  an  intervening  shell,  you can use the
X          ^X-$ execute-program  command. It will prompt you for an external
X
X
X                                                                         40
X
X
X
X
X
X
X          Access to the Outside World           MicroEMACS Reference Manual
X
X
X          program and its arguments  and  attempt to execute it.  Like when
X          EMACS looks for command files, EMACS will look first in  the HOME
X          directory, then down the execute PATH, and finally in the current
X          directory  for  the  named  program.  On  some  systems, it  will
X          automatically  tack  the  proper extension on the  file  name  to
X          indicate it is a program. On some systems that don't support this
X          function, ^X-$ will be equivalent to ^X-! shell-command.
X
X                  Sometimes,  you  would  like to get back to the shell and
X          execute other commands, without losing  the  current  contents of
X          EMACS.  The ^X-C  i-shell  command  shells  out of EMACS, leaving
X          EMACS in the computer and  executing another command shell.  Most
X          systems would allow  you  to  return  to  EMACS  with  the "exit"
X          command.
X
X                  On some systems, mainly advanced  versions  of  UNIX, you
X                  can
X          direct EMACS to "go into the background" with  the  ^X-D suspend-
X          emacs command.  This places EMACS in the background returning you
X          to the original command  shell.  EMACS can then be returned to at
X          any time with the "fg" foreground command.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X          41
X
X
X
X
X
X
X          MicroEMACS Reference Manual           Access to the Outside World
X
X
X
X
X
X
X                                 Chapter 10 Summary
X
X
X                  In Chapter 10 introduced  different  ways  to  access the
X          computers  shell or command processor from  within  EMACS.    The
X          commands in the following table were covered in the chapter.
X
X
X          Key Binding             Keystroke                   Effect
X          Execute-program         ^X-$            Execute an external program
X                                                  directly
X
X          Filter-command          ^X-#            Send the current buffer through
X                                                  a shell filter
X
X          I-shell                 ^X-C            Escape to a new shell
X
X          Pipe-command            ^X-@            Send the results of an external
X                                                  shell command to a buffer
X
X          Shell-command           ^X-!            Execute one shell command
X
X          Suspend-emacs           ^X-D            Place EMACS in the background
X                                                  (some UNIX systems only)
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X                                                                         42
X
X
X
X
X
X
X          Keyboard Macros                       MicroEMACS Reference Manual
X
X
X
X
X
X
X
X
X                                     Chapter 11
X
X                                   Keyboard Macros
X
X
X                  In many applications, it may  be  necessary  to  repeat a
X          series  of characters or commands frequently.    For  example,  a
X          paper may require the frequent repetition of a complex formula or
X          a long name.  You may also have a series  of  EMACS commands that
X          you invoke frequently.  Keyboard macros offer a convenient method
X          of recording and repeating these commands.
X
X                  Imagine, for example, you are writing  a  scholarly paper
X          on  Asplenium  platyneuron,  the  spleenwort  fern.     Even  the
X          dedicated botanist would probably find it a task bordering on the
X          agonizing to type Asplenium platyneuron frequently throughout the
X          paper.  An alternative method is 'record' the name in  a keyboard
X          macro.  Try it yourself.
X
X                  The command ^X-( begin-macro starts recording the all the
X          keystrokes and commands you input.   After you've typed it, enter
X          Asplenium platyneuron.  To stop recording,  type  ^X-) end-macro.
X          EMACS has stored all the keystrokes between the two commands.  To
X          repeat the name you've stored, just enter ^X-E execute-macro, and
X          the name "Asplenium platyneuron"  appears.    You can repeat this
X          action as often  as  you  want,  and  of course as with any EMACS
X          command, you may precede it with a numerical argument.
X
X                  Because EMACS records keystrokes, you may freely intermix
X          commands and text.  Unfortunately, you can only  store  one macro
X          at  a  time.   Thus, if you begin to record  another  macro,  the
X          previously  defined  macro  is lost. Be careful  to  ensure  that
X          you've finished with one macro before defining another.    If you
X          have a series  of  commands  that  you would like to 'record' for
X          future use, use the macro  or  procedure  facilities  detailed in
X          chapter <X>.
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X          43
X
X
X
X
X
X
X          MicroEMACS Reference Manual                       Keyboard Macros
X
X
X
X
X
X
X                                 Chapter 11 Summary
X
X
X                  Chapter 11 covered  keyboard  macros.  You learned how to
X          record keystrokes and how to repeat the stored sequence.
X
X          Key Binding             Keystroke               Effect
X
X          Start-Macro             ^X-(            Starts recording all keyboard input
X
X          End-Macro               ^X-)            Stops recording keystrokes for
X                                                  macro
X
X          Execute-Macro           ^X-E            Entire sequence of recorded
X                                                  keystrokes is replayed
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X                                                                         44
X
X
X
X
X
X
X          MicroEMACS Macros                     MicroEMACS Reference Manual
X
X
X
X
X
X
X
X
X                                     Chapter 12
X
X                                  MicroEMACS Macros
X
X
X                  Macros are programs that are used to customize the editor
X          and to perform complicated editing tasks.  They may be  stored in
X          files  or  buffers  and  may  be  executed  using an  appropriate
X          command, or bound to  a  particular  keystroke.   Portions of the
X          standard start-up file are implemented via macros, as well as the
X          example menu system.  The  execute-macro-<n>  commands  cause the
X          macro, numbered from 1  to  40, to be executed.  The execute-file
X          command allows you to execute a macro stored in a disk  file, and
X          the execute-buffer command  allows  you to execute a macro stored
X          in a buffer.   Macros  are stored for easy execution by executing
X          files that contain the store-macro command.
X
X                  If you need more  than  40  macros, named macroes, called
X          procedures, can be used.   The  store-procedure  command  takes a
X          string argument which is the name of a procedure to store.  These
X          procedures than can be executed with  the  M-^E execute-procedure
X          or the run commands.
X
X                  There are many different aspects  to  the  macro language
X          within MicroEMACS.  Editor commands are the various commands that
X          manipulate  text,  buffers,  windows,  etc,  within  the  editor.
X          Directives are commands which  control  what  lines  get executed
X          within  a  macro.    Also  there are various types of  variables.
X          Environmental  variables  both control and  report  on  different
X          aspects of the editor.  User variables hold  string  values which
X          may be changed and inspected.  Buffer variables allow text  to be
X          placed into variables.  Interactive variable allow the program to
X          prompt the user  for  information.    Functions  can  be  used to
X          manipulate all these variables.
X
X
X          12.1  Constants
X
X
X                  All constants and variable contents in  EMACS  are stored
X          as  strings  of  characters. Numbers are stored digit by digit as
X          characters.  This  allows  EMACS  to  be  "typeless",  not having
X          different variables types be legal  in  different  contexts. This
X          has  the disadvantage of forcing the user  to  be  more  carefull
X          about the context of the  statements variables are placed in, but
X          in  turn  gives  them  more  flexibility in where they can  place
X          variables. Needless to say, this also  allows  EMACS's expression
X          evaluator to be both consice and quick.
X
X
X          45
X
X
X
X
X
X
X          MicroEMACS Reference Manual                     MicroEMACS Macros
X
X
X                  Wherever statements need to have arguments,  it  is legal
X          to  place constants.  A constant is  a  double  quote  character,
X          followed by a string of  characters,  and  terminated  by another
X          double  quote character. To represent various special  characters
X          within a constant, the tilde (~) character is used. The character
X          following the tilde  is  interpeted  according  to  the following
X          table:
X
X          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
X                  Any character not in the table which follows a tilde will
X          be passed unmodified.  This action is similar to  the  ^Q  quote-
X          character command available from the keyboard.
X
X                  The double  quotes around constants are not needed if the
X          constant contains no internal whitespace  and  it  also  does not
X          happen  to  meet   the   rules  for  any  other  EMACS  commands,
X          directives, variables, or functions.  This  is  reasonable useful
X          for numeric constants.
X
X
X          12.2  Variables
X
X
X                  Variables in MicroEMACS  can  be  used  to  return values
X          within expressions, as  repeat  counts to editing commands, or as
X          text  to be inserted into buffers and messages.    The  value  of
X          these  variables  is  set using the  set  (^X-A)  command.    For
X          example, to set the  current  fill  column  to 64 characters, the
X          following macro line would be used:
X
X                  set $fillcol 64
X
X                  or to have the contents of %name inserted at the point in
X          the current buffer, the command to use would be:
X
X                  insert-string %name
X
X
X
X
X
X
X
X
X
X
X
X
X                                                                         46
X
X
X
X
X
X
X          MicroEMACS Macros                     MicroEMACS Reference Manual
X
X
X
X          12.2.1  Environmental Variables
X
X
X                  "What good is a quote if you can't change it?"
X
X                  These variables are used to change  different  aspects of
X          the  way the editor works.  Also they  will  return  the  current
X          settings if used as  part  of  an  expression.  All environmental
X          variable  names begin with a dollar sign ($)  and  are  in  lower
X          case.
X
X          $acount        The countdown  of  inserted  characters  until the
X                         next save-file.
X
X          $asave         The   number   of  inserted   characters   between
X                         automatic file-saves in 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.
X                         (See Appendix F for 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
X                         like it!)
X
X          $discmd        Flag to disable the  echoing  of  messages  on the
X                         command line
X
X          $disinp        Flag  to disable the echoing of characters  during
X                         command line input
X
X          $fillcol       Current fill column
X
X          $flicker       Flicker Flag set to TRUE if IBM CGA  set  to FALSE
X                         for most others
X
X          $gflags        Global  flags  controlling  some  EMACS   internal
X                         functions (See appendix G for details)
X
X          $gmode         Global mode flags. (See Appendix F for values)
X
X
X
X          47
X
X
X
X
X
X
X          MicroEMACS Reference Manual                     MicroEMACS Macros
X
X
X          $lastkey       [READ ONLY]Last keyboard character typed
X
X          $line          The current line  in  the  current  buffer  can be
X                         retrieved and set with this environment variable
X
X          $lwidth        [READ ONLY]Returns the number of characters in the
X                         current line
X
X          $match         [READ  ONLY]Last  string  matched  in a magic mode
X                         search
X
X          $pagelen       Number of screen lines used currently
X
X          $palette       string  used  to  control  the   palette  register
X                         settings  on graphics versions.  The usually  form
X                         consists  of groups of three octal digits  setting
X                         the red, green, and blue levels.
X
X          $pending       [READ  ONLY]Flag  to  determine  if there are user
X                         keystrokes waiting to be processed.
X
X          $progname      [READ ONLY]Always contains the string "MicroEMACS"
X                         for standard MicroEMACS.   Could be something else
X                         if EMACS is incorporated as part of someone else's
X                         program
X
X          $replace       Current default replace string
X
X          $rval          This contains  the  return  value  from  the  last
X                         subprocess which was invoked 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
X                         IBM-PC driver.   LOW, MEDIUM, HIGH or DENSE on the
X                         Atari ST1040, NORMAL on all others)
X
X          $status        [READ ONLY]Status  of  the  success  of  the  last
X                         command (TRUE or FALSE).    This  is  usually used
X                         with !force to  check  on the success of a search,
X                         or a file operation.
X
X          $target        Current target for line moves (setting this fool's
X                         EMACS into believing the last command  was  a line
X                         move)
X
X          $tpause        Controls the length  of  the  pause  to  display a
X                         matched fence when the current buffer is  in CMODE
X                         and a close fence has been typed
X
X          $version       [READ ONLY]Contains the current MicroEMACS version
X                         number
X
X
X                                                                         48
X
X
X
X
X
X
X          MicroEMACS Macros                     MicroEMACS Reference Manual
X
X
X          $wline         Number of display lines in current window
X
X                  Obviously, many more of these variables will be availible
X          in  future releases of MicroEMACS. (Yes, send  a  vote  for  your
X          favorite new environmental variables today).
X
X
X          12.2.2  User variables
X
X
X                  User variables  allow you, the user, to store strings and
X          manipulate  them.    These strings can be pieces of text, numbers
X          (in  text form), or the logical values TRUE  and  FALSE.    These
X          variables can be combined,  tested,  inserted  into  buffers, and
X          otherwise used to control the way your macros execute.    At  the
X          moment, up to 255 user variables may be  in  use  in  one editing
X          session.  All users variable names must begin with a percent sign
X          (%) and may contain  any  printing characters.  Only the first 10
X          characters are  significant  (ie  differences  beyond  the  tenth
X          character are  ignored).  Most operators will truncate strings to
X          a length of 128 characters.
X
X
X          12.2.3  Buffer Variables
X
X
X                  Buffer variables are special in  that  they  can  only be
X          queried and cannot be set.  What buffer variables are is a way to
X          take text from a buffer and place it in a variable.  For example,
X          if I  have  a  buffer  by the name of RIGEL2, and it contains the
X          text:
X
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
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
X          buffer and grab  all the text up to the end of that line and pass
X          that back.  Then it would  advance  the point to the beginning of
X          the next line. Thus, after  our last command executes, the string
X          "Bloomington" gets inserted  into  the  current  buffer,  and the
X          buffer RIGEL2 now looks like this:
X
X
X
X
X
X
X
X          49
X
X
X
X
X
X
X          MicroEMACS Reference Manual                     MicroEMACS Macros
X
X
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
X                  as you have probably noticed, a buffer  variable consists
X          of the buffer name, preceded by a pound sign (#).
X
X
X          12.2.4  Interactive variables
X
X
X                  Interactive variables are actually a method to prompt the
X          user for a string.  This is done by using an at sign (@) followed
X          either with a quoted string, or a variable  containing  a string.
X          The string is the placed on the bottom line, and the editor waits
X          for the user to type in a string.  Then the  string  typed  in by
X          the users is returned as the value of  the  interactive variable.
X          For example:
X
X                  set %quest "What file? "
X                  find-file @%quest
X
X                  will ask the user for a file name, and  then  attempt  to
X          find it. Note also that complex expressions can be built  up with
X          these operators, such as:
X
X          @&cat &cat "File to decode[" %default "]: "
X
X                  which prompts the user with the concatinated string.
X
X
X          12.3  Functions
X
X
X                  Functions can be used to manipulate variables  in various
X          ways.  Functions can have one, two, or three  arguments.    These
X          arguments will always be placed after the function on the current
X          command line.  For example, if we wanted to increase  the current
X          fill  column  by  two, using emacs's set (^X-A) command, we would
X          write:
X
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
X                  Function  names  always  begin  with  the  ampersand  (&)
X          character, and are only significant to the first three characters
X          after the ampersand.  Functions will normal expect  one  of three
X
X
X                                                                         50
X
X
X
X
X
X
X          MicroEMACS Macros                     MicroEMACS Reference Manual
X
X
X          types of arguments, and  will  automatically  convert  types when
X          needed.
X
X          <num>          an ascii string of digits which is interpeted as a
X                         numeric value.  Any string  which  does  not start
X                         with  a   digit  or  a  minus  sign  (-)  will  be
X                         considered zero.
X
X          <str>          An arbitrary string of characters.  At the moment,
X                         strings are limited to 128 characters in length.
X
X          <log>          A logical value consisting of the string "TRUE" or
X                         "FALSE".  Numeric strings  will  also  evaluate to
X                         "FALSE" if they  are  equal to zero, and "TRUE" if
X                         they are non-zero.   Arbitrary  text  strings will
X                         have the value of "FALSE".
X
X                  A  list  of the currently  availible  functions  follows:
X          (Once again, send in those votes on what kind  of  functions  you
X          would  like to see added!) Functions are  always  used  in  lower
X          case, the uppercase letters in the function table  are  the short
X          form of the function (ie &div for &divide).
X
X          Numeric 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
X                                          <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
X          String 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
X
X
X          51
X
X
X
X
X
X
X          MicroEMACS Reference Manual                     MicroEMACS Macros
X
X
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          &GTK                            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
X          Logical 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.