Provided by: tack_1.08-1build1_amd64 bug

NAME

       tack - terminfo action checker

SYNOPSIS

       tack [-itV] [term]

DESCRIPTION

       The  tack  program  has  three purposes: (1) to help you build a new terminfo entry describing an unknown
       terminal, (2) to test the correctness of an existing entry, and (3) to develop the  correct  pad  timings
       needed to ensure that screen updates do not fall behind the incoming data stream.

       Tack  presents  a  series of screen-painting and interactive tests in ways which are intended to make any
       mismatches between the terminfo entry and reality visually obvious.  Tack also provides  tools  that  can
       help in understanding how the terminal operates.

   OPTIONS
       -i     Usually tack will send the reset and init strings to the terminal when the program starts up.  The
              -i option will inhibit the terminal initialization.

       -t     Tell tack to override the terminfo settings for basic terminal functions.  When this option is set
              tack  will  translate (cr) to \r, (cud1) to \n, (ind) to \n, (nel) to \r\n, (cub1) to \b, (bel) to
              \007, (ff) to \f and (ht) to \t.

       -V     Display the version information and exit.

       term   Terminfo terminal name to be tested.  If not present then the $TERM environment variable  will  be
              used.

OVERVIEW

       Since  tack  is  designed  to  test terminfo entries it is not possible to rely on the correctness of the
       terminfo data base.  Because of this the menuing system used with tack is vary primitive.  When a menu is
       printed it will scroll the entire screen.  To compensate for this verbose menu system tack  permits  menu
       selection  type ahead.  If you already know what action you would like tack to perform then you can enter
       that value immediately and avoid the menu display.  When in  doubt  the  question  mark  (?)  is  a  good
       character  to  type.   A  carriage  return  will  execute  the default action.  These default actions are
       designed to run all the standard tests.

       When tack first comes up it will display some basic information about the terminal.  Take  some  time  to
       verify this information.  If it is wrong many of the subsequent tests will fail.  The most important item
       is the screen size.  If the screen size is wrong there is no point in proceeding.  (home) and (clear) are
       also  critical  to  the success of subsequent tests.  The values of (cr) (ind) (cub1) and (ht) may effect
       the tests if they are defined incorrectly.  If they are  undefined  tack  will  set  them  to  reasonable
       defaults.   The  last  two entries on the display are the enquire and acknowledge strings.  These strings
       are taken from the user strings (u9) and (u8).

       By now you must be wondering why the terminfo names are enclosed in parenthesis.  This  has  no  profound
       meaning other than it makes them stand out.  The tack program uses this convention any time it displays a
       terminfo name.  Remember tack is designed to rely on as little of the terminfo entry as possible.

CREATING NEW ENTRIES

       Tack  has  a  number  of tools that are designed to help gather information about the terminal.  Although
       these functions are not dependent on terminal type, you may wish to execute tack with options -it.   This
       will turn off initialization and default the standard entries.

       These tools may be reached from the main menu by selecting the “tools” entry.

       Echo tool:  All data typed from the keyboard will be echoed back to the terminal.  Control characters are
       not  translated  to  the  up arrow format but are sent as control characters.  This allows you to test an
       escape sequence and see what it actually does.  You may also elect to enable hex output on echo tool this
       will echo the characters in hexadecimal.  Once the test is running you may enter the “lines” or “columns”
       keywords which will display a pattern that will help you determine your screen size.  A complete list  of
       keywords  will  be  displayed  when  the  test  starts.   Type  “help” to redisplay the list of available
       commands.

       Reply tool:  This tool acts much like the echo tool, but  control  characters  that  are  sent  from  the
       terminal  more  than  one character after a carriage return will be expanded to the up arrow format.  For
       example on a standard ANSI terminal you may type:

                 CR ESC [ c

       and the response will be echoed as something like:

                 ^[ [ ? 6 c

       ANSI sgr display:  This test assumes you have an ANSI terminal.  It goes through attribute numbers  0  to
       79, displaying each in turn and using that SGR number to write the text.  This shows you which of the SGR
       modes  are  actually implemented by the terminal.  Note: some terminals (such as Tektronix color) use the
       private use characters to augment the functionality of the SGR command.  These private use characters may
       be interjected into the escape sequence by typing the character ( <, =, >, ? ) after the original display
       has been shown.

       ANSI status reports:  This test queries the terminal in standard ANSI/VT-100  fashion.   The  results  of
       this test may help determine what options are supported by your terminal.

       ANSI  character  sets:   This test displays the character sets available on a ANSI/VT-100 style terminal.
       Character sets on a real VT-100 terminal are usually defined with smacs=\E(0 and rmacs=\E(B.   The  first
       character  after the escape defines the font bank.  The second character defines the character set.  This
       test allows you to view any of the possible combinations.  Private use character sets are defined by  the
       digits.  Standard character sets are located in the alphabetic range.

VERIFYING AN EXISTING ENTRY

       You  can verify the correctness of an entry with the “begin testing” function.  This entry is the default
       action and will be chosen if you hit carriage return (or enter).  This will bring  up  a  secondary  menu
       that allows you to select more specific tests.

       The general philosophy of the program is, for each capability, to send an appropriate test pattern to the
       terminal  then  send  a  description  of  what  the  user  should expect.  Occasionally (as when checking
       function-key capabilities) the program will ask you to enter input for it to check.

       If the test fails then you have the option of dynamically changing the terminfo entry and re-running  the
       test.   This  is  done  with  the  “edit  terminfo” menu item.  The edit submenu allows you to change the
       offending terminfo entry and immediately retest the capability.  The edit menu lets you do  other  things
       with  the  terminfo,  such as; display the entire terminfo entry, display which caps have been tested and
       display which caps cannot be tested.  This menu also allows you to write the newly modified  terminfo  to
       disc.   If you have made any modifications to the terminfo tack will ask you if you want to save the file
       to disc before it exits.  The filename will be the same as the terminal name.  After  the  program  exits
       you can run the tic(1M) compiler on the new terminfo to install it in the terminfo data base.

CORRECTING PAD TIMINGS

   Theory of Overruns and Padding
       Some  terminals  require  significant  amounts  of  time  (that  is,  more than one transmitted-character
       interval) to do screen updates that change large portions of the screen,  such  as  screen  clears,  line
       insertions,  line  deletions,  and  scrolls  (including scrolls triggered by line feeds or a write to the
       lowest, right-hand-most cell of the screen).

       If the computer continues to send characters to the terminal while one of these time-consuming operations
       is going on, the screen may be garbled.  Since  the  length  of  a  character  transmission  time  varies
       inversely  with  transmission  speed  in  cps, entries which function at lower speeds may break at higher
       speeds.

       Similar problems result if the host machine is simply sending characters at a sustained rate faster  than
       the  terminal  can  buffer  and  process them.  In either case, when the terminal cannot process them and
       cannot tell the host to stop soon enough, it will just drop them.  The dropped characters could be  text,
       escape sequences or the escape character itself, causing some really strange-looking displays.  This kind
       of glitch is called an overrun.

       In terminfo entries, you can attach a pad time to each string capability that is a number of milliseconds
       to delay after sending it.  This will give the terminal time to catch up and avoid overruns.

       If you are running a software terminal emulator, or you are on an X pseudo-tty, or your terminal is on an
       RS-232C line which correctly handles RTS/CTS hardware flow control, then pads are not strictly necessary.
       However,  some  display packages (such as ncurses(3X)) use the pad counts to calculate the fastest way to
       implement certain functions.  For example: scrolling the screen may be faster than deleting the top line.

       One common way to avoid overruns is with XON/XOFF handshaking.  But even this handshake may have problems
       at high baud rates.  This is a result of the way XON/XOFF works.  The terminal tells  the  host  to  stop
       with  an XOFF.  When the host gets this character, it stops sending.  However, there is a small amount of
       time between the stop request and the actual stop.  During this window, the  terminal  must  continue  to
       accept  characters  even though it has told the host to stop.  If the terminal sends the stop request too
       late, then its internal buffer will overflow.  If it  sends  the  stop  character  too  early,  then  the
       terminal  is  not  getting  the most efficient use out of its internal buffers.  In a real application at
       high baud rates, a terminal could get a  dozen  or  more  characters  before  the  host  gets  around  to
       suspending transmission.  Connecting the terminal over a network will make the problem much worse.

       (RTS/CTS  handshaking  does  not  have  this problem because the UARTs are signal-connected and the "stop
       flow" is done at the lowest level, without software intervention).

   Timing your terminal
       In order to get accurate timings from your terminal tack needs to know when  the  terminal  has  finished
       processing  all  the  characters  that were sent.  This requires a different type of handshaking than the
       XON/XOFF that is supported by most terminals.  Tack needs to send a request to the terminal and wait  for
       its  reply.   Many  terminals  will  respond with an ACK when they receive an ENQ.  This is the preferred
       method since the sequence is short.  ANSI/VT-100 style terminals can mimic this handshake with the escape
       sequence that requests “primary device attributes”.

          ESC [ c

       The terminal will respond with a sequence like:

          ESC [ ? 1 ; 0 c

       Tack assumes that (u9) is the enquire sequence and that (u8) is the acknowledge string.  A  VT-100  style
       terminal  could  set  u9=\E[c and u8=\E[?1;0c.  Acknowledge strings fall into two categories.  1) Strings
       with a unique terminating character and, 2) strings of fixed length.   The  acknowledge  string  for  the
       VT-100  is  of  the  first type since it always ends with the letter “c”.  Some Tektronics terminals have
       fixed length acknowledge strings.  Tack supports both types of strings by scanning  for  the  terminating
       character  until  the  length of the expected acknowledge string has arrived.  (u8) should be set to some
       typical acknowledge that will be returned when (u9) is sent.

       Tack will test this sequence before running any of the pad tests or the function key  tests.   Tack  will
       ask you the following:

           Hit lower case g to start testing...

       After  it  sends  this  message  it  will send the enquire string.  It will then read characters from the
       terminal until it sees the letter g.

   Testing and Repairing Pad Timings
       The pad timings in distributed terminfo entries are often  incorrect.   One  major  motivation  for  this
       program is to make it relatively easy to tune these timings.

       You can verify and edit the pad timings for a terminal with the “test string capabilities” function (this
       is also part of the “normal test sequence” function).

       The  key  to determining pad times is to find out the effective baud rate of the terminal.  The effective
       baud rate determines the number of characters per second that the  terminal  can  accept  without  either
       handshaking or losing data.  This rate is frequently less than the nominal cps rate on the RS-232 line.

       Tack  uses  the  effective  baud  rate to judge the duration of the test and how much a particular escape
       sequence will perturb the terminal.

       Each pad test has two associated variables that can be tweaked to help verify the correctness of the  pad
       timings.   One  is the pad test length.  The other is the pad multiplier, which is used if the pad prefix
       includes “*”.  In curses use, it is often the first parameter of the capability (if there is one).  For a
       capability like (dch) or (il) this  will  be  the  number  of  character  positions  or  lines  affected,
       respectively.

       Tack  will  run  the  pad  tests  and  display  the  results  to the terminal.  On capabilities that have
       multipliers tack will not tell you if the pad needs the multiplier or not.  You must make  this  decision
       yourself  by rerunning the test with a different multiplier.  If the padding changes in proportion to the
       multiplier than the multiplier is required.  If the multiplier has little or no effect on  the  suggested
       padding  then  the multiplier is not needed.  Some capabilities will take several runs to get a good feel
       for the correct values.  You may wish to make the test longer to get more accurate results.  System  load
       will  also  effect  the  results  (a heavily loaded system will not stress the terminal as much, possibly
       leading to pad timings that are too short).

NOTE

       The tests done at the beginning of the program  are  assumed  to  be  correct  later  in  the  code.   In
       particular,  tack displays the number of lines and columns indicated in the terminfo entry as part of its
       initial output.  If these values are wrong a large number of tests will fail or give incorrect results.

FILES

       tack.log    If logging is enabled then all characters written to the terminal will also be written to the
                   log file.  This gives you the ability to see how the tests were performed.  This  feature  is
                   disabled by default.

       term        If  you  make  changes  to the terminfo entry tack will save the new terminfo to a file.  The
                   file will have the same name as the terminal name.

SEE ALSO

       terminfo(5), ncurses(3X), tic(1M), infocmp(1M).  You should also have the documentation supplied  by  the
       terminal manufacturer.

BUGS

       If the screen size is incorrect, many of the tests will fail.

AUTHOR

       Concept,  design,  and  original  implementation by Daniel Weaver <dan.weaver@znyx.com>.  Portions of the
       code and documentation are by Eric S. Raymond <esr@snark.thyrsus.com>.

                                                                                                         tack(1)