ncurses 5.6 - patch 20061223
[ncurses.git] / tack / tack.1
1 .\"***************************************************************************
2 .\" Copyright (c) 1998-2005,2006 Free Software Foundation, Inc.              *
3 .\"                                                                          *
4 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
5 .\" copy of this software and associated documentation files (the            *
6 .\" "Software"), to deal in the Software without restriction, including      *
7 .\" without limitation the rights to use, copy, modify, merge, publish,      *
8 .\" distribute, distribute with modifications, sublicense, and/or sell       *
9 .\" copies of the Software, and to permit persons to whom the Software is    *
10 .\" furnished to do so, subject to the following conditions:                 *
11 .\"                                                                          *
12 .\" The above copyright notice and this permission notice shall be included  *
13 .\" in all copies or substantial portions of the Software.                   *
14 .\"                                                                          *
15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
18 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
19 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
22 .\"                                                                          *
23 .\" Except as contained in this notice, the name(s) of the above copyright   *
24 .\" holders shall not be used in advertising or otherwise to promote the     *
25 .\" sale, use or other dealings in this Software without prior written       *
26 .\" authorization.                                                           *
27 .\"***************************************************************************
28 .\"
29 .\" $Id: tack.1,v 1.3 2006/04/22 22:26:55 tom Exp $
30 .TH tack 1M ""
31 .ds n 5
32 .ds d @TERMINFO@
33 .SH NAME
34 \fBtack\fR - \fIterminfo\fR action checker
35 .SH SYNOPSIS
36 \fBtack\fR [-itV] [term]
37 .br
38 .SH DESCRIPTION
39 The \fBtack\fR program has three purposes:
40 (1) to help you build a new terminfo entry describing an unknown terminal,
41 (2) to test the correctness of an existing entry, and
42 (3) to develop the correct pad timings needed to ensure that screen updates
43 don't fall behind the incoming data stream.
44 .PP
45 \fBTack\fR presents a series of screen-painting and interactive
46 tests in ways which are intended to make any mismatches between the
47 terminfo entry and reality visually obvious. 
48 \fBTack\fR also provides tools that can help in understanding how
49 the terminal operates.
50 .SS OPTIONS
51 .TP
52 .I "\-i"
53 Usually \fBtack\fR will send the reset and init strings to the terminal
54 when the program starts up.  The \fI-i\fR option will inhibit the
55 terminal initialization.
56 .TP
57 .I "\-t"
58 Tell \fBtack\fR to override the terminfo settings for basic terminal
59 functions.  When this option is set \fBtack\fR will translate
60 (cr) to \\r, (cud1) to \\n, (ind) to \\n, (nel) to \\r\\n,
61 (cub1) to \\b, (bel) to \\007, (ff) to \\f and (ht) to \\t.
62 .TP
63 .I "\-V"
64 Display the version information and exit.
65 .TP
66 .I "term"
67 Terminfo terminal name to be tested.  If not present then the $TERM
68 environment variable will be used.
69 .SH OVERVIEW
70 Since \fBtack\fR is designed to test terminfo's it is not possible
71 to rely on the correctness of the terminfo data base.  Because of this
72 the menuing system used with \fBtack\fR is vary primitive.  When a
73 menu is printed it will scroll the entire screen.  To compensate
74 for this verbose menu system \fBtack\fR permits menu selection
75 type ahead.
76 If you already know what action you would like \fBtack\fR to perform
77 then you can enter that value immediately and avoid the menu display.
78 When in doubt the question mark (?) is a good character to type.
79 A carriage return will execute the default action.  These default
80 actions are designed to run all the standard tests.
81 .PP
82 When \fBtack\fR first comes up it will display some basic information
83 about the terminal.  Take some time to verify this information.
84 If it is wrong many of the subsequent tests will fail.  The most
85 important item is the screen size.  If the screen size is wrong there
86 is no point in proceeding.  (home) and (clear) are also critical
87 to the success of subsequent tests.  The values of (cr) (ind)
88 (cub1) and (ht) may effect the tests if they are defined incorrectly.
89 If they are undefined \fBtack\fR will set them to reasonable defaults.
90 The last two entries on the display are the enquire and acknowledge strings.
91 These strings are taken from the user strings (u9) and (u8).
92 .PP
93 By now you must be wondering why the terminfo names are enclosed
94 in parenthesis.  This has no profound meaning other than it makes
95 them stand out.  The \fBtack\fR program uses this convention any time
96 it displays a terminfo name.  Remember \fBtack\fR is designed to
97 rely on as little of the terminfo entry as possible.
98 .SH CREATING NEW ENTRIES
99 \fBTack\fR has a number of tools that are designed to help gather
100 information about the terminal.  Although these functions are not
101 dependent on terminal type, you may wish to execute \fBtack\fR
102 with options \fI\-it\fR.  This will turn off initialization
103 and default the standard entries.
104 .PP
105 These tools may be reached from the main menu by selecting
106 the 'tools' entry.
107 .PP
108 \fBEcho tool\fR:  All data typed from the keyboard will be echoed back
109 to the terminal.  Control characters are not translated to the up arrow format
110 but are sent as control characters.  This allows you to test an escape
111 sequence and see what it actually does.  You may also elect to
112 \fBenable hex output on echo tool\fR this will echo the characters in
113 hexadecimal.  Once the test is running you may enter the 'lines'
114 or 'columns' keywords which will display a pattern that will help
115 you determine your screen size.  A complete list of keywords will
116 be displayed when the test starts.  Type 'help' to redisplay
117 the list of available commands.
118 .PP
119 \fBReply tool\fR:  This tool acts much like the echo tool, but
120 control characters that are sent from the terminal more than one character
121 after a carriage return will be expanded to the up arrow format.  For example
122 on a standard ANSI terminal you may type:
123
124                 CR ESC [ c
125
126 and the response will be echoed as something like:
127
128                 ^[ [ ? 6 c
129 .PP
130 \fBANSI sgr display\fR:  This test assumes you have an ANSI terminal.  It
131 goes through attribute numbers 0 to 79, displaying each in turn and using that
132 SGR number to write the text.  This shows you which of the SGR
133 modes are actually implemented by the terminal.  Note: some terminals (such as
134 Tektronix color) use the private use characters to augment the functionality of
135 the SGR command.  These private use characters may be interjected into the
136 escape sequence by typing the character ( <, =, >, ? ) after the original
137 display has been shown.
138 .PP
139 \fBANSI status reports\fR:  This test queries the terminal in standard
140 ANSI/VT-100 fashion.  The results of this test may help
141 determine what options are supported by your terminal.
142 .PP
143 \fBANSI character sets\fR:  This test displays the character sets
144 available on a ANSI/VT-100 style terminal.
145 Character sets on a real VT-100 terminal are usually defined
146 with smacs=\\E(0 and rmacs=\\E(B.  The first character after the
147 escape defines the font bank.  The second character defines the
148 character set.  This test allows you to view any of the possible
149 combinations.  Private use character sets are defined by the digits.
150 Standard character sets are located in the alphabetic range.
151 .SH VERIFYING AN EXISTING ENTRY
152 .PP
153 You can verify the correctness of an entry with the `begin testing'
154 function.  This entry is the default action and will be chosen
155 if you hit carriage return (or enter).  This will bring up a
156 secondary menu that allows you to select more specific tests.
157 .PP
158 The general philosophy of the program is, for each capability, to send an
159 appropriate test pattern to the terminal then send a description of
160 what the user should expect.  Occasionally (as when checking function-key
161 capabilities) the program will ask you to enter input for it to check.
162 .PP
163 If the test fails then you have the option of dynamically changing
164 the terminfo entry and re-running the test.  This is done with
165 the 'edit terminfo' menu item.  The edit submenu allows you to change
166 the offending terminfo entry and immediately retest the capability.
167 The edit menu lets you do other things with the terminfo, such as;
168 display the entire terminfo entry,
169 display which caps have been tested and display which caps cannot
170 be tested.  This menu also allows you to write the newly modified
171 terminfo to disc.  If you have made any modifications to the
172 terminfo \fBtack\fR will ask you if you want to save the file
173 to disc before it exits.  The filename will be the same as the terminal name.
174 After the program exits you can run the tic(1M) compiler on the
175 new terminfo to install it in the terminfo data base.
176 .PP
177 .SH CORRECTING PAD TIMINGS
178 .SS Theory of Overruns and Padding
179 .PP
180 Some terminals require significant amounts of time (that is, more than one
181 transmitted-character interval) to do screen updates that change large
182 portions of the screen, such as screen clears, line insertions,
183 line deletions, and scrolls (including scrolls triggered by line feeds
184 or a write to the lowest, right-hand-most cell of the screen).
185 .PP
186 If the computer continues to send characters to the terminal while one
187 of these time-consuming operations is going on, the screen may be garbled.
188 Since the length of a character transmission time varies inversely with
189 transmission speed in cps, entries which function at lower speeds may
190 break at higher speeds.
191 .PP
192 Similar problems result if the host machine is simply sending characters at a
193 sustained rate faster than the terminal can buffer and process them.  In either
194 case, when the terminal cannot process them and can't tell the host to stop
195 soon enough, it will just drop them.  The dropped characters could be text,
196 escape sequences or the escape character itself, causing some really
197 strange-looking displays.  This kind of glitch is called an \fIoverrun\fR.
198 .PP
199 In terminfo entries, you can attach a \fBpad time\fR to each string capability
200 that is a number of milliseconds to delay after sending it.  This will give
201 the terminal time to catch up and avoid overruns.
202 .PP
203 If you are running a software terminal emulator, or you are on an X pseudo-tty,
204 or your terminal is on an RS-232C line which correctly handles RTS/CTS
205 hardware flow control, then pads are not strictly necessary.  However, some
206 display packages (such as ncurses(3X)) use the pad counts to calculate
207 the fastest way to implement certain functions.
208 For example: scrolling the screen may be faster than deleting the top line.
209 .PP
210 One common way to avoid overruns is with XON/XOFF handshaking.
211 But even this handshake may have problems at high baud rates.
212 This is a result of the way XON/XOFF works.  The terminal tells
213 the host to stop with an XOFF.  When the host gets this character, it stops
214 sending.  However, there is a small amount of time between the stop request and
215 the actual stop.  During this window, the terminal must continue to accept
216 characters even though it has told the host to stop.  If the terminal sends
217 the stop request too late, then its internal buffer will overflow.  If it sends
218 the stop character too early, then the terminal is not getting the most
219 efficient use out of its internal buffers.  In a real application at high baud
220 rates, a terminal could get a dozen or more characters before the host gets
221 around to suspending transmission.  Connecting the terminal over a network
222 will make the problem much worse.
223 .PP
224 (RTS/CTS handshaking does not have this problem because the UARTs are
225 signal-connected and the "stop flow" is done at the lowest level, without
226 software intervention).
227 .PP
228 .SS Timing your terminal
229 .PP
230 In order to get accurate timings from your terminal \fBtack\fR 
231 needs to know when the terminal has finished processing all the
232 characters that were sent.  This requires a different type of handshaking
233 than the XON/XOFF that is supported by most terminals.  \fBTack\fR
234 needs to send a request to the terminal and wait for its reply.
235 Many terminals will respond with an ACK when they receive an ENQ.
236 This is the preferred method since the sequence is short.
237 ANSI/VT-100 style terminals can mimic this handshake with the
238 escape sequence that requests 'primary device attributes'.
239
240    ESC [ c
241
242 The terminal will respond with a sequence like:
243
244    ESC [ ? 1 ; 0 c
245
246 \fBTack\fR assumes that (u9) is the enquire sequence and that (u8) is the
247 acknowledge string.  A VT-100 style terminal could set u9=\\E[c
248 and u8=\\E[?1;0c.
249 Acknowledge strings fall into two categories. 
250 1) Strings with a unique terminating character and,
251 2) strings of fixed length.
252 The acknowledge string for the VT-100 is of the first type since
253 it always ends with the letter 'c'.  Some Tektronics terminals
254 have fixed length acknowledge strings.  \fBTack\fR supports both
255 types of strings by scanning for the terminating character until
256 the length of the expected acknowledge string has arrived.
257 (u8) should be set to some typical acknowledge that will be
258 returned when (u9) is sent.
259 .PP
260 \fBTack\fR will test this sequence before running any of the pad
261 tests or the function key tests.  \fBTack\fR will ask you the following:
262
263     Hit lower case g to start testing...
264
265 After it sends this message it will send the enquire string.
266 It will then read characters from the terminal until it sees the
267 letter g.
268 .PP
269 .SS Testing and Repairing Pad Timings
270 .PP
271 The pad timings in distributed terminfo entries are often incorrect.  One
272 major motivation for this program is to make it relatively easy to tune these
273 timings.
274 .PP
275 You can verify and edit the pad timings for a terminal with
276 the `test string capabilities'
277 function (this is also part of the `normal test sequence' function).
278 .PP
279 The key to determining pad times is to find out the effective baud rate of
280 the terminal.  The effective baud rate determines the number of characters
281 per second that the terminal can accept without either handshaking or
282 losing data.  This rate is frequently less than the nominal cps rate on the
283 RS-232 line.
284 .PP
285 \fBTack\fR uses the effective baud rate to judge the duration of the test and
286 how much a particular escape sequence will perturb the terminal.
287 .PP
288 Each pad test has two associated variables that can be tweaked to help verify
289 the correctness of the pad timings.  One is the pad test length.  The other is
290 the pad multiplier, which is used if the pad prefix includes `*'.  In curses
291 use, it is often the first parameter of the capability (if there is one).
292 For a capability like (dch) or (il) this will be the number of character
293 positions or lines affected, respectively.
294 .PP
295 \fBTack\fR will run the pad tests and display the results to the terminal.
296 On capabilities that have multipliers \fBtack\fR will not tell you
297 if the pad needs the multiplier or not.  You must make this decision
298 yourself by rerunning the test with a different multiplier.
299 If the padding changes in proportion to the multiplier than the
300 multiplier is required.  If the multiplier has little or no effect on
301 the suggested padding then the multiplier is not needed.
302 Some capabilities will take several runs to get a good feel for
303 the correct values.  You may wish to make the test longer
304 to get more accurate results.  System load will also effect the
305 results (a heavily loaded system will not stress the
306 terminal as much, possibly leading to pad timings that are too short).
307 .PP
308 .SH NOTE
309 The tests done at the beginning of the program are assumed to be correct later
310 in the code.  In particular, \fBtack\fR displays the number of lines and
311 columns indicated in the terminfo entry as part of its initial output.
312 If these values are wrong a large number of tests will fail or give incorrect
313 results.
314 .SH FILES
315 .TP 12
316 tack.log
317 If logging is enabled then all characters written to the terminal
318 will also be written to the log file.  This gives you the ability
319 to see how the tests were performed.  This feature is disabled by default.
320 .TP 12
321 .I "term"
322 If you make changes to the terminfo entry \fBtack\fR will save
323 the new terminfo to a file.  The file will have the same name
324 as the terminal name.
325 .SH SEE ALSO
326 \fBterminfo\fR(\*n), \fBncurses\fR(3X), \fBtic\fR(1M), \fBinfocmp\fR(1M).
327 You should also have the documentation supplied by the terminal
328 manufacturer.
329 .SH BUGS
330 If the screen size is incorrect, many of the tests will fail.
331 .SH AUTHOR
332 Concept, design, and original implementation by
333 Daniel Weaver <danw@znyx.com>.  Portions of the code and
334 documentation are by Eric S. Raymond <esr@snark.thyrsus.com>.
335 .\"#
336 .\"# The following sets edit modes for GNU EMACS
337 .\"# Local Variables:
338 .\"# mode:nroff
339 .\"# fill-column:79
340 .\"# End: