#  help file for tm----   D. Woodruff
#
#  used by help.c
#
#  This file is used to create a help tree by help.c (see init_help).
#  The tree is scanned to provide help information.
#
1 tm
  turing machine interpreter
2 exit
      at tm> prompt, quit from the TM program.  Else quit the current
      request for a command stream completion.  ^Z may be used by VMS users.
      This is the same as 'quit'.
2 quit
      at tm> prompt, quit from the TM program.  Else quit the current
      request for a command stream completion.  This is the same as 'exit'.
2 add
      add a new quintuple to the quintuple list.
         e.g.,  'add quint 0110r'
2 enter
      add a number of quintuples to the list.  Brief information on how
      to add quintuples is given when you 'enter'.
2 delete
      delete a quintuple or delete the entire quintuple list.

      usage:  'delete quintuple (string)',  where (string) is two characters.
              'delete all', deletes all quintuples on the list.
              'delete list', deletes all quintuples and removes the list.

      enter 'exit' or 'quit' to delete nothing.
2 #
      Everything from this character to the end of the input line
      is ignored.  Example:

           tm> # this is a comment
           tm>set tape ((      # this sets a tape to '(('

      There must be a space between '#' and the rest of the line.  Namely
      'tm>#this is a comment' is erroneous.
2 show      
3 debug
      'show debug' tells whether or not debug mode is 'on' or 'off'.
      See 'debug_mode', 'set watch', 'set break', etc.
3 state
      shows the current machine state.
3 count
      shows how many machine executions have been executed so far.  
      the 'count' is reset when a new tape is entered.
3 tape
      shows the current tape and the position of the tape head.
3 length
      shows the length of the tape.
3 last
      shows the last quintuple that was executed.
3 list
      shows the quintuple list.
3 next
      shows the next quintple to be executed.
3 filename
      shows the name of the last quintuple file to be read.
3 header
      If it exists, shows the comment block at the top of the last 
      quintuple file to be read.
3 macro
      shows the currently available macro stream.  See 'set macro' and
      'using_macros' for more information.
3 max_step
      shows the current value of 'max_step', which is the maximum number 
      of steps executed by the machine when 'go' is entered.

      When that number of steps have been taken the user is giving the 
      opportunity of either halting or continuing the machine execution.
3 quint
      display a quintuple from the quintuple list.  E.g., 'show quint 01' 
      displays the quintuple starting with the characters '01', if it exists.
3 watch
      shows any watch points that are set.
3 break
      shows any break points that are set.
2 list
      Displays the current quintuple list.  Displays also the comments if 
      'set display comments on' was entered .  Displays also the number of 
      executions for each quintuple if 'set display iterations on' was entered.
2 edmacro
      A simple editor mode which allows the current contents of the macro
      buffer to be edited.
3 list
      List the macro.  Each macro word is numbered and displayed on a new
      line.  E.g., 'l 5' lists the macro words starting with the fifth.
      'l' lists all the macro words.

      usage:  'list [(integer)]'   --- abbreviated 'l'
3 find
      Find 'word' on the macro stream.  'find (word)' finds the first 
      occurrence of (word) in the macro.  To find later instances, enter
      'find' alone.

      usage: 'find [(word)]'    ---- abbreviated 'f'
3 delete 
      Delete macro word (num).  If two numbers are entered, e.g., d 3 5,
      delete words 3 through 5.

      usage: 'delete (num) [(num)]'   --- abbreviated 'd'
3 insert 
      Insert a word or words after (num).

      usage: 'insert (num) (word) [(word) ....]'  ---- abbreviated 'i'
3 exit
      Exit from the editor.  A single '.' in column one will cause an
      exit, as well as ^Z for VMS users.
2 go
      Execute the turing machine until it halts, or until 'max_step' is
      reached.  In the later case, you are given a choice to continue the
      calculation, or to halt.  You can 'set max_step' if you are not
      satisfied with its current value.  (See 'show max_step')

      'run' applies to running macros.
2 move
      Move the tape head a given number of cells.

      Usage:  'move left (number)'    if (number) not given, move 1
              'move right (number)'   if (number) not given, move 1
              'move left end'      move to the left end of tape
              'move right end'     move to the right end of tape
3 number
      Move (number) of cells to the left or right.  If (number) is not given,
      1 is assumed.  If the tape head is at the end of the tape, extra
      blanks are added.
3 examples

    1)
      tm> move right 30 show tape

      Moves the tape head 30 cells to the right, then displays the tape.  
      Blank cells are added if needed.

    2)
      tm> move right show tape

      Moves the tape head 1 cell to the right, then displays the tape.  A 
      blank cell is added if necessary.

    3)
      tm> move left end move left show tape

      Moves the tape head to the left end of the tape, then adds a single
      blank.  The tape head is left on the blank.  Finally, the tape is 
      displayed.
2 read
      Read a file.  'read macro (filename)' or 'read tm (filename)'.  
      Default extension for macro file is .mac, for tm file is .tm.

      If a macro is read, any contents of the macro buffer is replaced.  In
      the case of tm files, the quintuples are appended to the current list.
2 write
      Write a file.  'write macro (filename)' or 'write tm (filename)'.  
      The current contents of the macro buffer, or of the quintuple list
      is what is written.  The default extension for macro files is '.mac' 
      and for tm files is '.tm'.
2 run
      Run the macro if one exists.  'go' applies to executing machine 
      instructions.
2 say
      Print out the next word or quoted string to be entered.  
      Useful in macros.  The same as 'echo'.
2 echo
      Print out the next word or quoted string to be entered.  
      Useful in macros.  The same as 'say'.
3 example
   If you enter

      tm> say "This is how to enter a string."

   then TM's output is:

      This is how to enter a string. 
      tm>
2 step
      Perform turing machine executions.
      Usage 'step (number)'.  If (number) is not entered, one step is taken.
3 examples

      1)
        tm> step, show tape

      One machine instruction is executed and the tape is show.  The 
      comma is not required.

      2)
        tm> step 5, show tape

      Five instructions are executed and the tape is shown.
2 set
      Set a machine characteristic.
3 trace
      'set trace tape'  ---  display the tape and tape head at each step.
      'set trace descriptor' -- display machine descriptor at each step.
      'set trace off'   ---  stops the displaying of data.
  'Trace off' is default at program startup.   The output when trace is 'tape'
  is affected by whether or not debug mode is 'on'.
4 tape
      'set trace tape' causes the tape and tape head location to be displayed 
      at each machine step execution.  If debug is 'on' the machine state is
      also shown along with the last and the next quintuples to be executed.
4 descriptor
      The instantaneous descriptor notation shows the machine operation 
      using the following notation:
               (x1,y1,z1) -> (x2,y2,z2) -> (x3,y3,z3)
      where each successive parenthesis shows the successive machine
      configuration after each step.  
             xi  =  the tape to the left of the tape head
             yi  =  the machine state
             zi  =  the tape to the right of the tape head, where
                    the first symbol is the current symbol being read
      'set trace off' stop the display
4 off
      'set trace off' stops the displaying of the tape and machine state.
3 debug
      'set debug on' or 'set debug off'.  'Debug on' is the default at
      program startup.
4 on
      When debug is 'on', the turing machine execution is halted at 
      break or watch points for the 'go' command, or for the 'step' command
      when more than one step is being executed.  
4 off
      When debug is set 'off', the turing machine doesn't halt at any
      break or watch points.
3 display
    Usage:
      'set display comments on(off)'      -- display comments
      'set display iterations on(off)'    -- display number of executions
      'set display none'                  -- display neither
    'set display commments', 'iterations' and 'none' alters the format in 
    which quintuples are shown when they are 'list'ed.
4 comments
      If display is set on for comments, then the comments that are associated
      with each quintuple are displayed when the quntuples are listed.  
      Comments are associated with quintuples in quintuple files and with
      the command 'set comment'.
4 iterations
      if 'iterations' are set 'on', then the number of times that a
      quintuple was used is shown when the quintuples are listed.
4 none
      if 'none' is entered, then display for both comments and iterations is
      turned off.
3 macro
      'set macro' causes macro input mode to be entered.  All commands entered
      until 'exit' or '.' (or ^Z for VMS users) are put into a buffer, and 
      can be executed by entering 'run'.
3 max_step
      'set max_step' sets the maximum number of steps that will be executed
      during the 'go' command.  When that number of steps have been taken
      the user is giving the opportunity to halt or to continue execution.
3 tape
      'set tape' causes the next word or string to be input as a tape.  The
       machine state is set to 0, the initial state.
4 examples

      1)
        tm> set tape 11111
        Sets the tape to a sequence of five 1's.

      2)
        tm> set tape "aaa  aaa"
        Sets the tape to two sequences of a's separated by two spaces.

      3)
        tm> set tape ",,,,,"
        Sets the tape to a sequence of five commas.

      4)
        tm> set tape ,,,,,       (tape is not set in this case)
        The commas are ignored, since they are treated as white-space.
3 state
      'set state' followed by a character sets the machine state to that
      character.  
3 symbol
      'set symbol' followed by a character causes the character to be written
      on the tape at the current location of the tape head.
3 comment
      'set comment' allows the user to enter a comment for a quintuple.

      For example:  setting a comment on quintuple 21x2r
           tm> set comment 21 "Rewrite all 1's as x's"
3 watch
      Usage: 'set watch state (character)' or 'set watch symbol (character)'
4 character
      'state (character)' or 'symbol (character)'.  (character) is in the 
      first case a state, and in the second a symbol on the tape.  These set
      a watch point.  
4 watch_point
      The turing machine will stop if either the watch symbol state is 
      about to be entered, or if the watch symbol is about to be written 
      on the tape.

      To move past a watch point, 'step' a single step, or 'set debug off'.
3 break
          Usage:  'set break (quintuple)', where (quintuple) is a two-symbol
      string designating a quintuple.  The turing machine will stop if the
      next instruction will use this quintuple.
          To move past a break point, 'step' a single time, or 'set debug off'
3 exit
      set nothing.  Return to tm> prompt.
3 quit
      set nothing.  Return to tm> prompt.
2 cancel
      cancel watch points or break points.  Usage: 
       'cancel break (string)'      -- string is two characters
   or  'cancel watch state(or 'symbol') (character)'
3 break
      the two characters in (string) must be the first two characters in the
      quintuple for which the break is being canceled.  For example,
      'set break 21' would set a break point on quintuple 21x2r
3 watch
      'watch' can be set for states or symbols.
4 state
      'cancel watch state (character)' will cancel the watch on the state of
      the machine which is designated by (character).
4 symbol
      'cancel watch symbol (character)' will cancel the watch on the symbol
      of the tape which is designated by (character).
2 quintuple_lists
      A 'quintuple' is a turing machine instruction. It has the following
      format:
                            (x,i,o,y,m)
      where
          x = current state of the machine
          i = symbol on the tape that is currently being read by the machine.
      This is the quintuple that would be executed if the machine were in 
      state x with the tape head reading symbol i.  Then when the quintuple
      is executed,
          o = symbol that is written on the tape (replacing i)
          y = state that the machine enters
          m = movement of the tape head after the new symbol is written
              and the new state is entered into.
      A list of quintuples is a turing machine program.
3 format
      This programs supports only one quintuple list at a time
      
      In this program each machine state and each tape mark consists of
      a single character.  State symbols and tape mark symbols must be unique, 
      but the same character may be used both as a state and a tape mark in 
      the same turing machine program.

      Quintuple notations for this program:
             (xioym      in .tm files.  The '(' in the first column
                            signals an input quintuple.
             xioym       for input to 'add' or 'enter' functions,
                            or shown in 'list' function
3 commands
      This program supports only one quintuple list at a time.  Some useful 
      quintuple commands are:
        'list'     ---     show the list of quintuples
        'add'      ---     add a new quintple to the list
        'enter'    ---     start up a simple quintuple editor
        'delete'   ---     delete a quintuple, or the entire list
        'show'     ---     show individual quintuples
      see other help items for more commands, for syntaxes and for details.
2 entering_commands
      TM commands are entered as streams of words.  Most of the words may be
      abbreviated.  For example,
          tm> set tape 1111
          tm> sh t              
      causes the tape to be set and then displayed.  Abbreviations are used
      to 'show tape' in the second line.  The streams may be concatenated.
      For example,
          tm> set tape 1111 show tape 
      has the same effect as the last example.  If an input stream is not
      sufficient to cause an action, the user is prompted for more input.
      For example,
          tm> set
          set what? tape
          enter tape (as a string): 1111
          tm>
      Words are separated by spaces, commas and semicolons.  If it is necessary
      to enter these, use double quotes.  For example:
          tm> set tape "aaa aaa"
2 using_macros
      A 'macro' is a command stream (See 'help entering_commands') stored in 
      memory that may be played back at any time.  

      Macros may be entered interactively
           (e.g., 'set macro set tape 111 show tape')
      or from a file 
           ('read macro (filename)'),
      and may be edited
           ('edmacro')

      Macros may be written to files
           ('write macro (filename)').
3 sample_file
          #  Sample macro file      
          #  (lines starting with '#' are comments)
          say "simple sample macro file...."
              set tape 1111
              show tape
          #  End of file  (you need not end with a comment, though !)
4 format
      lines that start with '#' or '!' are comment lines and are ignored  
      by the program.  Indentation is not required, and may be used to 
      improve the appearance of macro files.  the example macro file could 
      have been written as:

          #  Sample macro file      
          #  (lines starting with '#' are comments)
          say "simple sample macro file...." set tape 1111 show tape
          #  End of file  (you need not end with a comment, though !)

      When macro files are written from tm (see 'help write') all 
      comments and indentation is lost.  If the sample macro file were 
      written to disk, the result would be a file with the just the 
      following line:
          say "simple sample macro file...." set tape 1111 show tape
2 debug_mode
Break and watch points cause the machine execution to halt if any are
encountered.  This allows the user to examine the condition of the machine to
check for any problems in his turing machine program.

Break points are set for quintuples, and cause the machine to halt just before
the quintuple is executed.  

Watch points may be set for either states or tape symbols.  The machine will
halt just before a transition is made to a watched state or just before a 
watched symbol is written to tape.

The user has two ways in which he can continue past a watch or break point:
enter 'step' (or 'step 1'), or 'set debug off'.  Break and watch points are
ignored if debug is set off or if a single step is taken.
3 show
      'show debug' tells whether or not debug mode is on.
      'show break' shows the currently set break points.
      'show watch' shows the currently set watch points.
3 set
      'set debug' either 'on' or 'off'.
      'set trace' either 'tape' or 'off'.
      'set watch state (char)' sets watch for state (char).
      'set watch symbol (char)' sets watch for symbol (char).
      'set break (quintuple)' set break at a quintuple.  (quintuple) is a
            two character string giving the first two symbols of the
            quintuple.
3 cancel
      'cancel watch state (char)' cancels watch for state (char).
      'cancel watch symbol (char)' cancels watch for symbol (char).
      'cancel break (quintuple)' cancel break at a quintuple.  (quintuple) 
            is a two character string giving the first two symbols of the
            quintuple.
2 break_points
      A break point causes processing to halt just before a designated 
      quintuple is executed.  Break point operations:  set, cancel, show
2 watch_points
      A watch point causes processing to halt just before a designated
      symbol is about to be written to the tape or just before a designated
      state is about to be entered.  Watch point operations:  set, cancel,
      show
3 trace_with_debug
      When trace is 'tape' and debug is 'off' the tape is displayed showing
      the location of the tape head at each machine execution.  If debug
      is 'on' the machine state and the last and next quintuples to be 
      executed is also displayed.
2 written_by
            David S. Woodruff                        davewoodr@aol.com
            Suffolk University, Math and Computer Science
                         and
            MIT Lab for Nuclear Science
            77 Massachusetts Ave.
            Cambridge, MA.    02139
