Trailing-Edge - PDP-10 Archives - steco_19840320_1er_E35 - 10,5676/teco/macros/hints.tec
There is 1 other file named hints.tec in the archive. Click here to see a list.
                              TECO HINTS
                              ---- -----

     This file contains little known features  and  general  hints  to
make living with TECO easier and more efficient.

     Note that this file can be examined at any  time  during  a  TECO
session  (without  affecting  the  text  buffer, pointer, etc.) by the
command  EPfilename.ext$Q*=$$",   which   stores   the   contents   of
filename.ext into Q-register *, and then types them.

     TECO's buffer pointer is always positioned between two characters
in the editing buffer.  It is never positioned exactly on a particular
character.  This concept is fundamental to TECO and  must  be  clearly
understood.  Make frequent use of the semicolon type-out command until
you are familiar with the  positioning  and  movement  of  the  buffer

     Disk area TED: contains many  useful  TECO  macros  that  may  be
executed with the EI command.  Of particular interest is TED:HELP.TEC.
This macro makes an interactive help facility available  at  any  time
during an editing session simply by typing "EIHELP$$".  Try it!

     The use of an TECO initialization  file  can  be  very  powerful.
TECO  commands  placed in a file named TECO.INI on your disk area will
be executed automatically each time you enter TECO.  It can be used to
specify  the  type  of  terminal  you  use, to load your favorite TECO
macros into appropriate q-registers, to  set  up  default  values  for
filenames,  type  messages,  etc.   Here  are the contents of a sample
TECO.INI file:

EVADM3A$ EPTED:LINE$ [*]L ^AWelcome to TECO!

This command string will specify the terminal  in  use  as  an  ADM3A,
store  the TECO macro LINE.TEC into Q-register L, and type a welcoming
message.  You may now type "ML=" at any time to find out what line  in
the text buffer the pointer is at.

     Q-registers can be used to recover text "lost" because you forgot
to  type  an  "I" at the beginning of an insert command.  TECO usually
types an error message like "SEARCH STRING TOO LONG" or "MISSING  TAG"
when  this happens.  A "*i" typed as the first command after the error
message will place the text you intended to insert in q-register i.  A
subsequent  "Gi" command will copy the text into the buffer.  Remember
to delete the altmode (-D$$ works fine) at the  end  of  the  restored

     TECO error messages actually consist of three parts:   1)  a  six
letter  error  code,  2) a one line description of the error, and 3) a
detailed explanation of the cause of the  error.   The  command  "nEH"
(n=1,2,3)  will  tell TECO how much of every error message you wish to
see.  Novice users  should  put  "3EH"  into  their  TECO.INI  command
string.   Advanced users may wish to use "1EH".  In any case, typing a
slash after an error message appears will cause TECO to type the  next
portion of the error message.

     The "?"  command  has  two  uses.   Immediately  after  an  error
message,  a  "?"  will  type  out the command that caused the detected
error.  At any other time, a ? puts TECO in trace  mode.   Trace  mode
displays  each  command  as  it is executed.  A subsequent ? turns off

     Q-registers can be used to save positions within the  buffer  for
use  as  arguments  to  other  commands.   You  can move around in the
buffer, saving the current value of the buffer pointer  at  places  of
interest  by  typing  ".Ui".   "Qi"  is  then used to return the value
stored  in  q-register  i.   For  example,  suppose  different  buffer
positions  have  been  saved in q-regs a, b, and c.  Then Qa,QbT types
out the text in the buffer between a and b; Qa,QbXd stores a  copy  of
the text between a and b in q-reg d; Qa,QbK deletes the text between a
and b; QcJ moves the buffer pointer to position c; Gd gets a  copy  of
the text in q-reg d and inserts it at c (our current buffer position).

     At the conclusion of any K or D command, the  buffer  pointer  is
positioned  between  the  characters  that  preceded  and followed the
deletion.  In the above example, note that this means a "QcJ" followed
by  a  "Qa,QbK" will leave you at the position of the deletion, not c.
Further, remember that the values stored in q-regs a, b, and c do  not
refer  to  particular  character  strings, but to locations within the
buffer.  Following a deletion (or insertion), they may no longer point
to the same text as before.

     Q-registers can be used to  save  and  execute  command  strings.
"*i",  when  typed  as  the  first  command of a new string, saves the
previous command string in q-reg i.  Subsequently, "Mi" can be used to
execute  the  commands  stored  in  i, much like calling a subroutine.
Saves a lot of typing if you find yourself repeatedly using  the  same
set of commands!

     If you forget what is in a q-register, simply type "Qi=".

     To copy the contents of  q-register  i  into  q-register  j,  use

     <FStext1$text2$;> is a fast way  to  change  all  occurrences  of
text1  in  the buffer (starting at the pointer) to text2.  This leaves
the pointer positioned at the last place a change was made.  Note that
<FStext1$$;>  will  NOT  cause  all occurences of text1 to be deleted,
since  the  two  adjacent  altmodes   will   terminate   the   command
prematurely.   To  make this work, we must use use a control character
which doesn't  generate  text  to  separate  the  two  altmodes  (e.g.
<FStext1$^V$;>).   Use  an  FN  search  instead  of  FS if you want to
continue beyond  the  current  page  in  the  buffer  and  change  all
occurrences  of  text1  in  the file.  At the end of an FN search, all
pages in the file have been input and output and the buffer cleared.

     It is a good idea to  exit  and  then  reenter  TECO  every  5-15
minutes  (EX$$  followed by TECO<CR> works fine).  This will keep your
source and .BAK files as current as possible as a safeguard against  a
system  crash.   If  the  system  does  crash  while  you are editing,
everything typed in the current session will be lost.

     The maximum length of a search string is 36 character  positions.
However,  the search string itself may contain up to 80 characters, if
needed, to specify special control commands (like "^E<nnn>").

     In order to insert or search for control characters, they must be
preceded  by  a ^R which "quotes" them.  ^R is preferable to ^Q, since
^Q will not allow insertion of $ (altmode) as a text  character  while
^R will.

     To save a command string (without having  to  execute  it  first)
simply  type  the command as if it were to be executed and replace the
final two altmodes ($$) at the end of the string with two  control-G's
(^G^G).   Then type *i.  This stores the command, ready for execution,
in q-reg i.

     The maximum depth of the Q-register pushdown list is 32 entries.

     The Q-register pushdown list is cleared after  the  execution  of
each  complete  command  string  (eg,  every  time  TECO types an * to
indicate readiness to accept a new command string).

     When used as a command, the two character sequence  "up-arrow  x"
is  equivalent  to  the single character "control-x" (made by pressing
the CTRL and x keys simultaneously).  This method  can  be  used  only
when the control character is typed as a command, not when it is typed
as text or as an alphanumeric argument.

     B, ., Z, and H are symbolic values often used as  arguments  with
the  K,  J, P, T, and X commands.  For example, BJ (or simply J) moves
the pointer to the beginning of the buffer.  ZJ moves the  pointer  to
the  end of the buffer.  Two letter combinations of B, ., and Z can be
used to selectively delete, page-out, type, or copy (to a  Q-register)
different  sections  of text in the buffer.  B,Z means everything from
the beginning to the end  of  the  buffer  (same  as  H).   B,.  means
everything  from the beginning of the buffer up to the current pointer
position.  .,Z means everything  from  the  current  pointer  position
through the end of the buffer.

     TECO's editing buffer normally holds about  3000  characters,  or
roughly  50  lines  of  text.   The text in the buffer is known as the
current page.  Text is read in and out of the buffer a page at a time.
Form feeds may be placed in an input file to delimit pages and control
the amount of text read by an input command.

     On input, TECO accepts text until one of  the  following  occurs:
1)  the  end of the input file is reached, 2) a form feed character is
read, 3) the buffer is two-thirds full and a line  feed  is  read  (or
filled  to  within  128  characters  of capacity), or 4) the buffer is
completely filled.  If the buffer is not large enough to accomodate at
least  3000  characters  (or  3000 more characters if appending to the
buffer), TECO automatically expands its buffer  by  1K,  if  possible,
before beginning to input.

     Except as text or numeric arguments, the  carriage  return,  line
feed,  and  space  characters  are  ignored by TECO and may be used to
improve the readability of macros and command strings.   NEVER  use  a
<TAB> (control-I) for this purpose; it is an insert command!

     If you try to exit from TECO and are told "No File  for  Output",
you  probably  typed  an  "EF"  command  by mistake during the editing
session.  This is often the result of an "EC" mistyped as "EF"  or  by
the  partial  execution  of  an insert string that was not preceded by
"I".  To recover from this error, open a new output file with the "EW"
command  (use  a  name different from the file being edited) and exit.
Your original file should contain all the text output up to the  point
where  the  "EF"  occurred and the new file you created should contain
the rest.  Then combine the two files with a copy command (it  may  be
necessary  to  delete  a  few lines duplicated in both files).  If all
else fails, you can start over with the .BAK file.

     Always try to use the FS  command  rather  than  a  delete-insert
sequence, since fewer characters need to be shuffled around.

     When saving the state of TECO with an EE command, try  to  reduce
the size of the resulting .SAV file as much as possible by making sure
there is  no  unwanted  text  stored  in  Q-registers  (put  there  by
TECO.INI,  for  example)  and by doing an EC (garbage collect) command
just before the EE.

     The ^V (translate to lower case) and ^W (translate to upper case)
commands are very powerful.  When used inside an insert or search text
argument, two successive ^V or ^W commands cause translation,  to  the
specified  case,  of  all following alphabetic characters in that text
argument.  A single ^V or ^W command causes translation  of  the  next
single  character  (if  it  is alphabetic) to the specified case.  The
single ^V or ^W in a text argument  takes  precedence  over  the  case
conversion mode defined by double ^V or ^W commands.

     When used as independent commands,  ^V  and  ^W  set  TECO  to  a
prevailing  case  conversion  mode  that affects all insert and search
text arguments (except as specified by ^V and ^W commands  within  the
text  arguments).   Thus,  you can use a terminal without a lower case
keyboard to create and edit files containing both upper and lower case
alphabetic  characters.   First,  use an independent ^V command to set
the prevailing case conversion mode so that all upper case  alphabetic
characters  are  translated  to  lower  case.  Then use the ^W command
within individual text arguments to "shift" temporarily to upper case.
An  independent  0^V  or 0^W command will reset the prevailing mode so
that no case conversion is performed (TECO default).   These  commands
provide  a  quick  method for converting the case of characters in the
buffer.  For example, HXA$HK$^V$I^GA$0^V$$ will convert all the  upper
case characters in the buffer to lower case.

     An TECO command string is not executed until you type two escapes
($$)  in  succession.  This allows you to concatenate as many commands
as desired into one command string (this is, in fact, what TECO macros
are).   Single  escapes are required within the string only to delimit
commands with variable length arguments.

     It is possible for a TECO macro stored in a Q-register to receive
and  return  arguments.   For  example,  if the string in Q-register A
contains "U1 U2 ...  Q3", then the command "5,10MA="  will  cause  the
5,10  to  be passed to the first U command, which will store the 10 in
Q-reg 1 and send the 5 on to the second U command, which will store it
in Q-reg 2.  The Q3 command at the end of the macro returns the number
in Q-register 3, and this value becomes an  argument  to  the  command
following  the  "MA", in this case an "=" which causes the value to be
typed on the terminal.  When writing TECO macros,  however,  it  is  a
good idea to save and restore the original contents of any Q-registers
needed.  This can be done with the help of the "[" and  "]"  commands.
Assuming that the macro in our above example makes use of Q-regs 1, 2,
and 3, we could rewrite the macro  as  "[1 [2 [3 ... ]3 ]2 ]1",  which
will preserve the contents around the macro call.  Arguments may still
be  passed  to  the  macro,  since  "m,n [i [j"   is   equivalent   to
"[i [j m,nUiUj".   Note  that our original macro returned the value in
Q-reg 3 by having "Q3" as the last command.  It is a little harder  to
return  a  value  from a macro if all Q-regs must be restored to their
original  contents.   The  idea   is   to   use   parentheses   in   a
non-conventional  manner:   "[1 [2 [3 ...Q3+(]3 ]2 ]1 0)".   This will
result in the return of the value Q3+0; the  trick  is  that  we  have
performed   some  non-arithmetic  functions  within  the  parentheses,
something which is perfectly legal as long as a numeric value precedes
the   closing   right  paren.   Another  example  of  this  technique:
".+(ZJ IHello$ 0)J" will allow you to go to the  end  of  the  buffer,
insert "Hello", and then restore your original pointer.

     TECO  is  really  a  programming  language  for  writing  editing
programs.   If  you  want  anybody  to understand what you've written,
remember to make extensive use of spaces and crlf's.  Each line  of  a
TECO  program should be no more complicated than a line of code in any
other programming language.

     You may insert comments in TECO programs  by  enclosing  them  in
exclamation points; in effect, making them into very long tags.

     See the TED:  area for examples of  several  well-formatted  TECO
macros.   In  particular,  see  TED:MAKTEC.TCO for an explanation of a
simple convention which makes writing TECO macros much more pleasant.