diff options
Diffstat (limited to 'contrib/ncurses/tack/tack.1')
-rw-r--r-- | contrib/ncurses/tack/tack.1 | 340 |
1 files changed, 0 insertions, 340 deletions
diff --git a/contrib/ncurses/tack/tack.1 b/contrib/ncurses/tack/tack.1 deleted file mode 100644 index dcab18f..0000000 --- a/contrib/ncurses/tack/tack.1 +++ /dev/null @@ -1,340 +0,0 @@ -.\"*************************************************************************** -.\" Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. * -.\" * -.\" Permission is hereby granted, free of charge, to any person obtaining a * -.\" copy of this software and associated documentation files (the * -.\" "Software"), to deal in the Software without restriction, including * -.\" without limitation the rights to use, copy, modify, merge, publish, * -.\" distribute, distribute with modifications, sublicense, and/or sell * -.\" copies of the Software, and to permit persons to whom the Software is * -.\" furnished to do so, subject to the following conditions: * -.\" * -.\" The above copyright notice and this permission notice shall be included * -.\" in all copies or substantial portions of the Software. * -.\" * -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * -.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * -.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * -.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * -.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * -.\" * -.\" Except as contained in this notice, the name(s) of the above copyright * -.\" holders shall not be used in advertising or otherwise to promote the * -.\" sale, use or other dealings in this Software without prior written * -.\" authorization. * -.\"*************************************************************************** -.\" -.\" $Id: tack.1,v 1.3 2006/04/22 22:26:55 tom Exp $ -.TH tack 1M "" -.ds n 5 -.ds d @TERMINFO@ -.SH NAME -\fBtack\fR - \fIterminfo\fR action checker -.SH SYNOPSIS -\fBtack\fR [-itV] [term] -.br -.SH DESCRIPTION -The \fBtack\fR 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 -don't fall behind the incoming data stream. -.PP -\fBTack\fR 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. -\fBTack\fR also provides tools that can help in understanding how -the terminal operates. -.SS OPTIONS -.TP -.I "\-i" -Usually \fBtack\fR will send the reset and init strings to the terminal -when the program starts up. The \fI-i\fR option will inhibit the -terminal initialization. -.TP -.I "\-t" -Tell \fBtack\fR to override the terminfo settings for basic terminal -functions. When this option is set \fBtack\fR 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. -.TP -.I "\-V" -Display the version information and exit. -.TP -.I "term" -Terminfo terminal name to be tested. If not present then the $TERM -environment variable will be used. -.SH OVERVIEW -Since \fBtack\fR is designed to test terminfo's it is not possible -to rely on the correctness of the terminfo data base. Because of this -the menuing system used with \fBtack\fR is vary primitive. When a -menu is printed it will scroll the entire screen. To compensate -for this verbose menu system \fBtack\fR permits menu selection -type ahead. -If you already know what action you would like \fBtack\fR 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. -.PP -When \fBtack\fR 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 \fBtack\fR 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). -.PP -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 \fBtack\fR program uses this convention any time -it displays a terminfo name. Remember \fBtack\fR is designed to -rely on as little of the terminfo entry as possible. -.SH CREATING NEW ENTRIES -\fBTack\fR 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 \fBtack\fR -with options \fI\-it\fR. This will turn off initialization -and default the standard entries. -.PP -These tools may be reached from the main menu by selecting -the 'tools' entry. -.PP -\fBEcho tool\fR: 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 -\fBenable hex output on echo tool\fR 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. -.PP -\fBReply tool\fR: 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 -.PP -\fBANSI sgr display\fR: 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. -.PP -\fBANSI status reports\fR: 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. -.PP -\fBANSI character sets\fR: 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. -.SH VERIFYING AN EXISTING ENTRY -.PP -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. -.PP -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. -.PP -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 \fBtack\fR 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. -.PP -.SH CORRECTING PAD TIMINGS -.SS Theory of Overruns and Padding -.PP -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). -.PP -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. -.PP -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 can't 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 \fIoverrun\fR. -.PP -In terminfo entries, you can attach a \fBpad time\fR 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. -.PP -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. -.PP -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. -.PP -(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). -.PP -.SS Timing your terminal -.PP -In order to get accurate timings from your terminal \fBtack\fR -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. \fBTack\fR -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 - -\fBTack\fR 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. \fBTack\fR 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. -.PP -\fBTack\fR will test this sequence before running any of the pad -tests or the function key tests. \fBTack\fR 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. -.PP -.SS Testing and Repairing Pad Timings -.PP -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. -.PP -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). -.PP -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. -.PP -\fBTack\fR uses the effective baud rate to judge the duration of the test and -how much a particular escape sequence will perturb the terminal. -.PP -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. -.PP -\fBTack\fR will run the pad tests and display the results to the terminal. -On capabilities that have multipliers \fBtack\fR 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). -.PP -.SH NOTE -The tests done at the beginning of the program are assumed to be correct later -in the code. In particular, \fBtack\fR 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. -.SH FILES -.TP 12 -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. -.TP 12 -.I "term" -If you make changes to the terminfo entry \fBtack\fR will save -the new terminfo to a file. The file will have the same name -as the terminal name. -.SH SEE ALSO -\fBterminfo\fR(\*n), \fBncurses\fR(3X), \fBtic\fR(1M), \fBinfocmp\fR(1M). -You should also have the documentation supplied by the terminal -manufacturer. -.SH BUGS -If the screen size is incorrect, many of the tests will fail. -.SH AUTHOR -Concept, design, and original implementation by -Daniel Weaver <danw@znyx.com>. Portions of the code and -documentation are by Eric S. Raymond <esr@snark.thyrsus.com>. -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: |