		MUNG - TECO Program Interface
		=============================

 MUNG is  the  form of TECO used for executing standalone TECO macros.
 It  is  invoked  simply by installing TECO with a taskname of ...MUN,
 and    the    TECO  initialization  code  distinguishes  between  the
 invocations and acts accordingly.

 The use format of a MUNG program invocation is

	MUN	progname,arguments

 though  this  may  vary  from  program  to  program.  By default MUNG
 programs have an extension of .MUN and live in LB:[1,2] though either
 or  both  of these may be overridden on the commandline.


 For a list of current MUNG programs type HELP MUNG LIST or MUNG HELP.
2	LIST

 Currently the following MUNG programs exist on the system:-

	ALIGN	- Align comments in a MACRO-11 program
	HELP	- List out all current MUNG programs
	LIGHTS	- Flicker the lights on a SYSTIME VDU
	LP	- Convert a TECO file with non-printing characters into
		  one that can be printed on the printer
	MACERR	- Find a MACRO-11 error in a MACRO-11 listing
	MUNG	- Same as HELP
	PURGE	- Delete consecutive identical lines in a file
	SEARCH	- Search one or more files for one or more strings
	SPLIT	- Split a document file into two halves
	SQU	- Squish up a TECO macro
	TYPE	- Type one or more TECO files on the terminal
	UP	- Convert all lower-case characters to upper-case
	VAXRSX	- Convert a MACRO-32 program to MACRO-11
	WHITE	- Convert non-printing characters in a file to printing ones

 For more help on a particular program type HELP MUNG <name>
 (Note that several contain more than a screenful of information.)
2	ALIGN

 ALIGN.MUN is a small program that attempts to align MACRO-11 comments
 at  tab-stop  5.   It will not alter any lines with a ; before column
 12, so as to allow header comments.
2	HELP
	#MUNG
2	LIGHTS

 LIGHTS.MUN  is a trivial program that flickers the lights on the side
 of  a  SYSTIME VDU.  The real purpose of this is to illustrate how to
 output control sequences to the terminal.
2	LP

 LP  creates  a  listing  file (extension .LIS) from a TECO-type file,
 replacing all non-printing characters with printing characters.
2	MACERR

 It is often hard, particularly in large programs, to find errors in a
 MACRO-11  listing  file,  as  they  are  indicated merely by a single
 letter  in  the left-hand margin.  MACERR.MUN will inspect a MACRO-11
 listing  file  to fins any such error lines and print them out on the
 terminal.  Be aware that it is only about 95% successful.
2	MUNG

 MUNG  on  this  system  has been subtly modified to support a feature
 whereby  the  user  can automatically see what MUN files exist on the
 system  (see  BOILER.MUN  for  details).   This is implemented by the
 MUNG.MUN file and may be invoked by

	MUN
	MUN *
	MUN HELP
	MUN MUNG

 This  will list the comments from all .MUN files in LB:[1,2] followed
 by those in the user's account.
2	PURGE

 PURGE.MUN  will  edit  the named file, delete any adjacent lines that
 are identical.
2	SEARCH

            SEARCH.MUN - the wildcard file searching macro

     SEARCH will scan one or more wildcarded sets  of  files  for  all
     occurances  of  one  or more strings.  Each match is displayed in
     the log file with the character "~" immediately after the matched
     string.  SEARCH also has a change mode (i.e., find and replace).

     You use the MUNG command to invoke SEARCH and it  enters  into  a
     dialogue with you.

     The "Output:" question directs SEARCH's log  file.   The  default
     log  file  is  to  your  terminal;  the default file extension is
     .SRH.  If you are doing a change mode run,  you  place  the  /CHA
     switch  on your answer to this question.  If the strings you wish
     to search for  (or  the  replacement  strings)  contain  embedded
     CR/LF's, you must add the /ESC switch to this question.  When you
     say /ESC, your responses to the Search:  (and Replace:) questions
     will  be  terminated  only by ESCape;  normally, either RETURN or
     ESCape is the terminator.  You can always use DELete (RUBOUT) and
     CTRL/U to edit your responses.

     The "Input:" question is asking for an optionally wildcarded file
     specification.    The   default  file  extension  is  .MAC.   You
     terminate supplying file specifications by responding with simply
     RETURN.

     The "Lines:" question determines the number of extra lines around
     the  found line to place in the log file.  An answer of 0 results
     in only the found line;  the default value is 3.

     The "Search:" question accepts the string(s) to search for.   All
     normal  TECO  search  constructs are allowed.  Terminate entering
     search strings with simply RETURN (or ESCape if you said /ESC).

     The "Replace:" question will only appear if you  specified  /CHA.
     After  each  Search:   is  responded  to, you enter a replacement
     string for the last entered search string.

     The "Detach:"  question  directs  SEARCH  to  detach  during  the
     searching.  The default is to stay attached.
2	SPLIT

 SPLIT.MUN  will  split  a document file (default extension .DOC) into
 two  files with extensions .DO1 and .DO2.  The first will contain the
 first,  third,  fifth...  pages  from  the  original document and the
 second will contain the second, fourth, sixth...  The idea of this is
 to facilitate double-sided printing of documents on the lineprinter.
2	SQU

                  SQU.MUN - the TECO macro squisher

     This macro will take a nice, readable TECO macro and squish it so
     that  it  is  as small and as fast as possible (and is completely
     unreadable).

     You invoke SQU with the MUNG command.  SQU  then  enters  into  a
     dialogue  with you as described below.  All questions contain the
     allowed legal responses enclosed in parentheses and  the  default
     you  get  if  you  just  type  RETURN  in angle brackets.  In the
     discussion below the term "lexical"  refers  to  characters  that
     TECO  would  have  interpreted  as TECO commands;  all characters
     inside string arguments are not lexical characters.  For example,
     the  ABC  of  SABC$  are not lexical characters while the S and $
     are.  Similiarly, the ABC and DEF of @FS/ABC/DEF/ are not lexical
     while the @, F, S, /'s, and $ are.

               Delete CR/LF (Y/N) <N>?

     A Y response will delete all lexical RETURNs and LINE FEEDs.   As
     this  usually  results in one very long "line", an answer of N is
     suggested (but, see the question below).

               Set line lengths (Y for 70, N, or length) <N>?

     This question is  asked  if  you  responded  N  to  the  previous
     question.   If  a  positive response is given, SQU will initially
     delete all lexical CR/LFs, then, as a  post-process,  insert  the
     CR/LF  combination wherever it's needed so that no line is longer
     than the length specified.  This neatly formats the squished TECO
     macro.   The  most  commonly used length is 70 so a response of Y
     results in a length of 70.

               Delete blank lines (Y/N) <N>?

     This question is asked only if you responded N  to  both  of  the
     questions  above.   A Y answer results in all lexical blank lines
     being deleted.

               Delete lexical TABs and FORM FEEDs (Y/N) <N>?

     Even though lexical TABs and FORM FEEDs have meaning to TECO (TAB
     starts an insert, FORM FEED outputs a FORM FEED on the terminal),
     some TECO macro writers use them simply  to  format  their  macro
     code.   Of  course,  their macros won't correctly execute without
     removing those lexical TABs and FFs.  A Y  response  will  delete
     all  lexical TABs and FORM FEEDs.  If your macro runs unsquished,
     you certainly want to answer N.

               Delete comments (Y for SP/TAB, N, or set) <N>?

     The trouble here is that both comments and labels (tags) use  the
     same  construct.   To  be  able to differentiate between the two,
     some sort of coding convention must be used.  SQU will check  the
     character  immediately  following the "!" that starts the comment
     or label.  If that character  matches  the  one  of  the  set  of
     "comment  characters"  specified,  SQU will delete the construct.

     Using a SPace or TAB immediately after  the  leading  exclamation
     point  seems to be the most flexible for formatting comments so a
     Y response results in the "comment character" set being SPace and
     TAB.

               Watch progress (Y/N) <N>?

     If your terminal is supported by the W  (scope  watch)  commands,
     this  question  will  be  asked.  At the cost of SQU running more
     slowly, you can watch its progress.  Useful  for  debugging,  not
     for production squishing...

               Automatic mode (Y for %, N, or set) <N>?

     This is the most confusing question.  The problem  here  is  that
     SQU  normally  won't  touch  characters  inside  string  argument
     strings, but the ^U command is frequently used to load TECO macro
     code  into Q-registers and, of course, you wish that code to also
     be  squished.   On  the  other  hand,  all  ^U  commands   aren't
     necessarily  loading TECO macro code.  There are two forms of the
     ^U command:  ^Uqxxx$ and @^Uq%xxx%.  The rule SQU  uses  is  that
     any ^U command that is of the @^Uq%xxx% form and whose delimiting
     character  is  a  member  of  the  "non-squishable  ^U   command"
     character   set   shouldn't  be  sub-squished;   every  other  ^U
     command's string argument is assumed to be TECO macro code and is
     sub-squished.   The  convention we've adopted is that the quoting
     character "%" is to be  used  for  textual  (i.e.,  non-code)  ^U
     command   arguments.    Therefore,   a   Y   response   sets  the
     "non-squishable ^U command" character set to %.   You  may  enter
     any  set  of  character(s) you want.  An N response places you in
     manual mode.  Whenever SQU  encounters  a  ^U  command,  it  will
     pause,  ring the terminal's bell, and await a response.  A Y says
     to go ahead and sub-squish the string arugment;  an  N  means  to
     skip  it.   Obviously,  you  want  to  start  coding  your macros
     according to some convention so that you don't need manual mode.

               Allow adjacent ESCapes (Y/N) <N>?

     The process of squishing a  macro  can  result  in  two  adjacent
     ESCape characters where there wasn't before.  For example, if the
     command @FS/ABC// was used, SQU will turn it  into  FSABC$$.   If
     the  macro  will  be read via an ER command, yanked into the text
     buffer, copied to  a  Q-register,  and  executed  this  poses  no
     problems.   On  the  other  hand, if the macro is to be EI'd, the
     adjacent ESCapes will trigger command execution prematurely.   An
     N  response  will  direct  SQU to never generate adjacent ESCapes
     where there wasn't before.

               File <.TES or .TEC>?

     SQU is now asking you for the file  specification  of  your  TECO
     macro  and  indicating the it will default the extension to .TES,
     or, if no file with a .TES extension exists, to .TEC.  After your
     reply,  SQU  will  take  off and start squishing the macro.  When
     it's done, it will simply return to TECO's * prompt.  You can now
     write out the squished macro however you want.

     If you invoke SQU as

               MUNG SQU,filnam

     it will enter its dialogue for the squishing  options,  but  will
     start  squishing  immediately after asking about adjacent ESCapes
     then return to the * prompt.

     You can invoke SQU specifying all of  the  squishing  options  as
     switches.  The switches are:

               /D       Delete CR/LF
               /L       Set line lengths
               /B       Delete blank lines
               /T       Delete lexical TAB/FFs
               /C       Delete comments
               /W       Watch progress
               /A       Automatic mode
               /E       Allow adjacent ESCapes

     Each switch should be expressed as /x:y where "x" is  the  switch
     and  "y"  is  either  Y  or N.  A non-standard line length can be
     expressed as /L:nn where "nn"  is  some  non-zero  digit  string.
     Non-standard  character  sets  can be specified for the /C and /A
     switches, but the character set is limited to a single character.
     For  example, /C:* sets the comment character set to "*" and /A:`
     sets the non-squishable ^U command character set to "`".

     You  can  also  supply  SQU  with  both  output  and  input  file
     specifications.  For example:

               MUNG SQU,outfil=infil

     SQU will enter its dialogue for the squishing options, then  will
     immediately  do  the  squishing,  write out the result, and exit.
     The output file extension always defaults to .TEC.

     If you have specified everything SQU needs  (an  input  file,  an
     output  file, and all of the options as switches), it will do the
     whole squishing operation and exit without further intervention.

     Common SQU command lines are:

     MUNG SQU,VTEDIT.TEC=VTEDIT.TES/D:N/L:Y/B:Y/T:N/C:Y/W:N/A:Y/E:N

     MUNG SQU,TECO.INI=TECOIN.TES/D:N/L:Y/B:Y/T:N/C:Y/W:N/A:Y/E:Y
2	TYPE

		 TYPE.MUN - the TYPE command responder

     TYPE.MUN  will  type  wild  carded  file   specifications.    The
     filename,  extension,  or version number (except RSTS/E) can be *
     or contains ?'s (RSTS/E only).  Under RSTS/E V7.0,  the  PPN  can
     also contain *'s.

     TYPE.MUN recognizes the following switches

          /W        Announce  the  filespecification  of  every   file
                    before it is typed.

          /H        Use VT52 hold screen mode.  /H forces  on  the  /W
                    switch.  On VT100's, the /H is turned into a /H:24
                    (see below).

          /H:n      Count n lines and  hold  the  screen.   This  also
                    forces on the /W switch.

          /-W       Turn off filespecification announcing.  Useful  if
                    /H turned announcements on.

          /V        This switch  changes  all  control  characters  to
                    visable  characters.   It  is  useful  for finding
                    funny carriage return/line  feed  sequences,  etc.
                    The  actual  output format depends on the terminal
                    you are using;  read the VTEDIT documentation.

          /T        Truncate long line.

          /S:"xxxx" Search  for  the  string  "xxxx"  before  starting
                    typing.   Any  search  string  may be used and any
                    character may  be  the  string  quoting  character
                    (this example used ").

          /A:n      Search for all occurances of the string  specified
                    with  the /S switch.  The n is the number of lines
                    around the match to display.  If just /A is  used,
                    n defaults to 3.

          /N:n      Start typing at page n or find the  nth  occurance
                    of the string specified by /S.

          /P        When the string specified by /S  is  found,  start
                    typing at the top of that page instead of the line
                    immediately before the found string.

          /I        Inspect each (wildcarded) file before it is typed.

          /F:x      Flag lower (x is L) or upper (x is  U)  case.   If
                    just /F is specified then lower case is flagged.

          /L:n      List only the first n lines of the file.  If  just
                    /L  is specified then n defaults to the terminal's
                    height (or 24 if unknown).
          /O:n      Overprint each  line  n  times.   If  just  /O  is
                    specified  then  n  defaults  to  1.   Useful  for
                    darkened copies on a hardcopy terminal.
2	UP

 UP.MUN will convert all lower-case text in the name file to upper-case.
2	VAXRSX

 VAXRSX.MUN  is  a  little program to assist in making quick and dirty
 conversions  from  a MACRO-32 program (default extension .MAR) to its
 equivalent    MACRO-11   program  (extension  .MAC).    This  program
 interrogates   the  file  [1,2]VAXRSX.SRC  and  changes  MACRO-32  to
 MACRO-11  accordingly.   The use of this macro is not recommended for
 serious  conversions,  but  can  be useful when a quick conversion is
 needed.
2	WHITE

 WHITE.MUN  simply  converts  all  'white  space'  (i.e.  non-printing
 characters like <LF>, <FF> and so on) into printable constructs.
