#	SID	@(#)etic.txt	3.2 - 95/11/10

Character Terminal Setup -- Unix Only

     SmartWare uses an extension of the standard terminfo
     package. This allows for the use of special "monkey bar"
     graphic characters and the redefinition of key strokes.

     A utility program, named "etic" for Extended Terminal
     Information Compiler, is used to build the extended terminal
     information. TERMINFO has many of the required settings,
     however, it does not provide the ideal key combinations and
     special character display information used by SmartWare.

     The "etic" compiler is used to turn a text file source, into
     a compiled terminal information file that SmartWare
     utilizes. The "etic" program can also be used to "decompile"
     compiled terminal information files.


Editing ETIC Source File

     You may use any text editor, including the SmartWare
     Text-Editor, to modify ETIC source files. If you want to
     modify an existing ETIC file, edit the provided source file.
     These files have .tic extensions and reside in
     subdirectories below the tinfo directory (i.e. if you have
     installed the software in the recommended location,
     /usr/angoss/tinfo/a/ansi.tic).

     ETIC files are essentially TERMINFO files with additional
     capabilities. Anything that is valid for a TERMINFO file is
     also valid for an ETIC file. You may also enter special
     instructions for SmartWare. All SmartWare instructions start
     with a left brace ({).

     When SmartWare starts up it will search for both the
     TERMINFO file and ETIC file. If both are present, both will
     be read into memory. If you are designing an ETIC file to
     work in conjunction with a TERMINFO file, avoid duplication
     to obtain maximum speed and memory efficiency. If you are
     designing an ETIC file which will work on a stand alone
     basis, include everything that normally goes into the
     TERMINFO file. To view the contents of a TERMINFO file, you
     must use the "infocmp" command to decompile it.


General Information about ETIC and TERMINFO FILES

     Here are some important points to remember when you are
     editing TERMINFO or ETIC files.
     *    White Spaces, Comments, and other indentation formats
          may be used to organize the source code and increase
          readability.
     *    Comments are indicated by using the number sign `#'.
          Comments may start anywhere on a line and are
          terminated by the end of the line. Individual values
          are separated by commas. Even the last entry must end
          with a comma.
     *    To symbolize an escape character, use a backslash
          capital E (i.e. \E.)
     *    To enter control characters, use ^<capital letter>. ^A
          for example.
     *    To insert a literal ^, use \^.
     *    The first line of the ETIC source file is an identifier
          of the terminals that are supported by this ETIC
          followed by a description. Terminal names are separated
          by | characters and the description is the last item.
          For example, if the first line of the file is:

          ansi|ansic|ansi80x25|Ansi standard console

     An "ansi" file will be created as a result of the compile.
     Then "ansic" and "ansi80x25" are created by linking to the
     "ansi" file. The net result is that the "ansi" "ansic" and
     "ansi80x25" will all behave identically.

     Special command words, which are interpreted by SmartWare,
     are started with a left brace ({) followed by the keyword.
     Special Entries for SmartWare


     This section describes special entries that apply to ETIC
     files only.

     {pc
          The {pc entry is used to indicate that the PC character
          set should be used. This allows for the use of
          characters above ASCII 127. If it is absent, all
          graphic characters will be mapped to regular text
          characters.

     {cmap
          {cmap is used to remap a PC character to the
          appropriate character for the terminal in use.
          The syntax for {cmap is:
                    {cmap=\d1\d2,
          Where: d1 = PC Decimal Character d2 = Terminal
          Character to Substitute
          Note that if you do not use a `d' the characters are in
          Octal.
          Refer to the "Relevant PC Characters" table, at the
          back of this manual, to determine the PC character. For
          the terminal character to substitute, refer to the
          terminal's manual.
          A handy trick that you can use to display the character
          set of a terminal is to use the spread sheet and enter
          the formula "chr(row)" and copy it down to row 255.
          NOTE: On some terminals, ANSI for example, certain high
          characters cause the terminal to switch modes or causes
          other interesting side effects. If this occurs, just
          ignore the garbage characters that are printed on your
          screen.

     {k<key>
          The {k<key> is used to override the default keystroke
          settings.
          The syntax for {k<key> is:
                    {k<key>="label"<sequence>,
          Where: <key> = the ETIC key name (See the ETIC Key Name
          Table) label = the name of the key on the keyboard
          <sequence> = the sequence of characters that the key
          press produces which will be converted to the SmartWare
          key stroke specified by <key>
          As an example, assume that you have an F11 key and you
          want to define it to be the screen refresh key. First
          you must determine what character sequence the key
          press produces. Check the terminal's manual.
          Alternatively, a trick that sometimes works is to press
          the keystroke when you are at the Unix prompt followed
          by the Enter key. Unix will return an error message
          which contains the key sequence. Note that it displays
          ESC as ^[ so that, for an ansi terminal, the F11 key
          produces ^[[W which can be interpreted as <ESC> [ W.
          Now determine the ETIC key name by referring to the
          "ETIC Key Name Table" in this document. This reveals
          that the ETIC key name for refresh is {krefresh.
          Next, edit the .tic ETIC source file and insert the
          line:
                    {krefresh="F11"\E[W,
          Compile the .tic file. Your change should take effect
          the next time you start SmartWare.
          Another example, which instructs SmartWare to interpret
          ^J as ^J, instead of down arrow, is:
                    {kcj="\^J"^J,
          Note the use of the \ to indicate a literal character
          and the fact the J is capitalized.
          If two keystroke patterns conflict with each other only
          one will be functional or the key help will report
          incorrect instructions. In order to resolve most of
          these problems refer to the "Keystroke Conversion
          Table" so that you can remap any conflicts. For
          example, if you want to remap the Ctrl L key to be
          refresh, you could insert something similar to the
          following:
                    {krefresh="\^L"^L,
                    {kright="RIGHT"\E[C,
          The first line tells SmartWare to perform a refresh
          when it receives a Ctrl L. By scanning the "Keystroke
          Conversion Table", you will see that the Ctrl L default
          is a right arrow. The second line resolves the conflict
          by assigning the right arrow to be triggered by the
          appropriate key sequence for the terminal, which in
          this case is an AT&T 605.

     {delay
          The {delay ETIC command instructs SmartWare to change
          the default key wait time.
          In order to optimize performance when SmartWare is
          idle, it will pause for half a second while it is
          waiting for a keystroke. This avoids needless looping
          which would have an adverse affect upon other users.
          To modify the key wait time insert the following line
          in the .tic file:
                    {delay#t,
          Where: t = time in tenths of a second


Using ETIC Files

     The ETIC files need to be placed in a specific directory for
     use by SmartWare. By default, this directory is below
     "tinfo" subdirectory within angoss, using the first letter
     of the file as the directory name. For example, the vt100
     terminal ETIC would be in:

          /usr/angoss/tinfo/v

     The location for the ETIC files may be changed by setting an
     operating system variable called ETICINFO. This variable
     should contain the pathing to the ETIC files. If the
     required file is not there, SmartWare will rely on the
     TERMINFO file for setup. Note that the location of the
     TERMINFO file that should be used is specified by the
     environment variable TERM which is usually set by the login
     process. If neither the ETIC nor TERMINFO files can be
     found, SmartWare will abort to the operating system with the
     appropriate error message.

     Note that, if the tinfo directory has been moved from its
     normal location within the ANGOSS directory, the ETICINFO
     environment variable can be used to specify its location.


ETIC - Extended Terminal Information Compiler

     The ETIC compiler may be used to compile or decompile an
     ANGOSS Terminal Information file. The ETIC compiler is
     capable of processing many files in one pass and is also
     capable of using different options on each of the files. The
     ETIC compiler's command line usage is shown below:
     etic [-flags] filename(s) [[-flags] filename(s)...]
     where flags are appropriate combinations of:

     c    compile   Default option if none provided.
     i    decompile Produce source listing from object file
     d    describe  Produce descriptive listing from object file
     k    check     Check syntax of source file
     v    verbose   Provide in-depth explanation of the process
     a    active    Interactively compile and debug the source

     The c option (compile) is the default option. The compile
     option instructs ETIC to turn the ASCII file into a format
     that is used by SmartWare for its terminal handling. This
     format is similar to the TERMINFO format.

     The i option (decompile) is used to take a compiled ETIC
     file and reverse engineer it back to the source code that
     comprises it. This is a useful function if an ETIC source
     file is accidentally erased since it can be rebuilt from the
     compiled version. It should be noted that comments and white
     spaces will not be restored during the decompile stage as
     they are ignored during a compile. Note that the -i option
     sends the decompiled information to stdout, so to create a
     file use the > to redirect the output to a file.

     A partial sample is shown below:

     vt100|vt100-am|dec vt100,
     cols#80,
     lines#24,
     csr=\E[%i%p1%d;%p2%dr,
     clear=\E[H\E[2J,
     el=\E[K,
     ...
     kpp=\E\E[A,
     kcuf1=\E[C,
     kcuu1=\E[A,
     rs2=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h,
     # ETICINFO-specific capabilities follow...
     {pc,
     {cmap=\363y,

     The d option (describe) is used to partially disassemble the
     ETIC file into a text file with the individual line items
     described in english. Each line contains a text description
     followed by the keyword in brackets and the value's setting.
     A sample of the VT100 script is shown below:

     ------------------------------------------------------------
     vt100|vt100-am|dec vt100
     ------------------------------------------------------------
     columns( cols)= 80
     lines( lines)= 24
     change_scroll_region( csr)= \E[%i%p1%d;%p2%dr
     clear_screen( clear)= \E[H\E[2J
     clr_eol( el)= \E[K
     ...
     key_left( kcub1)= \E[D
     key_npage( knp)= \E\E[B
     key_ppage( kpp)= \E\E[A
     key_right( kcuf1)= \E[C
     key_up( kcuu1)= \E[A
     reset_2string( rs2)= \E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h
     pc_console( {pc)= TRUE
     sic_cmap( {cmap)= \363y

     The k option (check) is used to validate that the source
     code in the ETIC file is in the proper format for a
     successful compilation. This is useful for quickly checking
     the source code without taking the time to compile the
     source code file.

     When the v option (verbose) is selected, compilation of the
     ETIC file is performed with an in-depth explanation of each
     step that is currently underway. This listing can be helpful
     when debugging a source file. A partial sample is shown
     below:

     Building terminal capability search tree...
     Parsing source file...
     TOKEN vt100 COMPILER STATE = 1
     TOKEN | COMPILER STATE = 2
     TOKEN vt100-am COMPILER STATE = 1
     TOKEN | COMPILER STATE = 2
     TOKEN dec vt100 (w/advanced video) COMPILER STATE = 3
     TOKEN , COMPILER STATE = 4
     TOKEN am COMPILER STATE = 5
     TOKEN , COMPILER STATE = 4
     TOKEN mir COMPILER STATE = 5
     TOKEN , COMPILER STATE = 4
     TOKEN msgr COMPILER STATE = 5
     TOKEN , COMPILER STATE = 4
     TOKEN \E[3g COMPILER STATE = 5
     ...
     TOKEN , COMPILER STATE = 4
     Writing compiled file vt100...
     Step 1: Counting terminfo capabilities...
     Counted 37 booleans, 30 numbers & 363 strings in term.h
     table.

     The a option (active) is used to interactively compile the
     ETIC source code files. This is useful for finding potential
     errors and can aid in debugging problems in the ETIC source
     file.

