![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to termcap-2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info|
Return to termcap-2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info |
1.1 root 1: Info file: termcap, -*-Text-*-
2: produced by texinfo-format-buffer
3: from file: termcap.texinfo
4:
5: This file documents the termcap library of the GNU system.
6:
7: Copyright (C) 1988 Free Software Foundation, Inc.
8:
9: Permission is granted to make and distribute verbatim copies of
10: this manual provided the copyright notice and this permission notice
11: are preserved on all copies.
12:
13: Permission is granted to copy and distribute modified versions of this
14: manual under the conditions for verbatim copying, provided that the entire
15: resulting derived work is distributed under the terms of a permission
16: notice identical to this one.
17:
18: Permission is granted to copy and distribute translations of this manual
19: into another language, under the above conditions for modified versions,
20: except that this permission notice may be stated in a translation approved
21: by the Foundation.
22:
23:
24:
25:
26: File: termcap Node: Basic, Prev: Capabilities, Up: Capabilities, Next: Screen Size
27:
28: Basic Characteristics
29: =====================
30:
31: This section documents the capabilities that describe the basic and
32: nature of the terminal, and also those that are relevant to the output
33: of graphic characters.
34:
35: `os'
36: Flag whose presence means that the terminal can overstrike. This
37: means that outputting a graphic character does not erase whatever was
38: present in the same character position before. The terminals that can
39: overstrike include printing terminals, storage tubes (all obsolete
40: nowadays), and many bit-map displays.
41:
42: `eo'
43: Flag whose presence means that outputting a space can erase an
44: overstrike. If this is not present and overstriking is supported,
45: output of a space has no effect except to move the cursor.
46:
47: `gn'
48: Flag whose presence means that this terminal type is a generic type
49: which does not really describe any particular terminal. Generic types
50: are intended for use as the default type assigned when the user
51: connects to the system, with the intention that the user should
52: specify what type he really has. One example of a generic type
53: is the type `network'.
54:
55: Since the generic type cannot say how to do anything interesting with
56: the terminal, termcap-using programs will always find that the
57: terminal is too weak to be supported if the user has failed to specify
58: a real terminal type in place of the generic one. The `gn' flag
59: directs these programs to use a different error message: "You have
60: not specified your real terminal type", rather than "Your terminal
61: is not powerful enough to be used".
62:
63: `hc'
64: Flag whose presence means this is a hardcopy terminal.
65:
66: `rp'
67: String of commands to output a graphic character C, repeated N
68: times. The first parameter value is the ASCII code for the desired
69: character, and the second parameter is the number of times to repeat the
70: character. Often this command requires padding proportional to the
71: number of times the character is repeated. This effect can be had by
72: using parameter arithmetic with `%'-sequences to compute the
73: amount of padding, then generating the result as a number at the front
74: of the string so that `tputs' will treat it as padding.
75:
76: `hz'
77: Flag whose presence means that the ASCII character `~' cannot be
78: output on this terminal because it is used for display commands.
79:
80: Programs handle this flag by checking all text to be output and
81: replacing each `~' with some other character(s). If this is not
82: done, the screen will be thoroughly garbled.
83:
84: The old Hazeltine terminals that required such treatment are probably
85: very rare today, so you might as well not bother to support this flag.
86:
87: `CC'
88: String whose presence means the terminal has a settable command
89: character. The value of the string is the default command character
90: (which is usually ESC).
91:
92: All the strings of commands in the terminal description should be
93: written to use the default command character. If you are writing an
94: application program that changes the command character, use the
95: `CC' capability to figure out how to translate all the display
96: commands to work with the new command character.
97:
98: Most programs have no reason to look at the `CC' capability.
99:
100: `xb'
101: Flag whose presence identifies Superbee terminals which are unable to
102: transmit the characters ESC and `Control-C'. Programs which
103: support this flag are supposed to check the input for the code sequences
104: sent by the F1 and F2 keys, and pretend that ESC
105: or `Control-C' (respectively) had been read. But this flag is
106: obsolete, and not worth supporting.
107:
108:
109: File: termcap Node: Screen Size, Prev: Basic, Up: Capabilities, Next: Cursor Motion
110:
111: Screen Size
112: ===========
113:
114: A terminal description has two capabilities, `co' and `li',
115: that describe the screen size in columns and lines. But there is more
116: to the question of screen size than this.
117:
118: On some operating systems the "screen" is really a window and the
119: effective width can vary. On some of these systems, `tgetnum'
120: uses the actual width of the window to decide what value to return for
121: the `co' capability, overriding what is actually written in the
122: terminal description. On other systems, it is up to the application
123: program to check the actual window width using a system call. For
124: example, on BSD 4.3 systems, the system call `ioctl' with code
125: `TIOCGWINSZ' will tell you the current screen size.
126:
127: On all window systems, termcap is powerless to advise the application
128: program if the user resizes the window. Application programs must
129: deal with this possibility in a system-dependent fashion. On some
130: systems the C shell handles part of the problem by detecting changes
131: in window size and setting the `TERMCAP' environment variable
132: appropriately. This takes care of application programs that are
133: started subsequently. It does not help application programs already
134: running.
135:
136: On some systems, including BSD 4.3, all programs using a terminal get
137: a signal named `SIGWINCH' whenever the screen size changes.
138: Programs that use termcap should handle this signal by using
139: `ioctl TIOCGWINSZ' to learn the new screen size.
140:
141: `co'
142: Numeric value, the width of the screen in character positions. Even
143: hardcopy terminals normally have a `co' capability.
144:
145: `li'
146: Numeric value, the height of the screen in lines.
147:
148:
149: File: termcap Node: Cursor Motion, Prev: Screen Size, Up: Capabilities, Next: Wrapping
150:
151: Cursor Motion
152: =============
153:
154: Termcap assumes that the terminal has a "cursor", a spot on the screen
155: where a visible mark is displayed, and that most display commands take
156: effect at the position of the cursor. It follows that moving the cursor
157: to a specified location is very important.
158:
159: There are many terminal capabilities for different cursor motion
160: operations. A terminal description should define as many as possible, but
161: most programs do not need to use most of them. One capability, `cm',
162: moves the cursor to an arbitrary place on the screen; this by itself is
163: sufficient for any application as long as there is no need to support
164: hardcopy terminals or certain old, weak displays that have only relative
165: motion commands. Use of other cursor motion capabilities is an
166: optimization, enabling the program to output fewer characters in some
167: common cases.
168:
169: If you plan to use the relative cursor motion commands in an application
170: program, you must know what the starting cursor position is. To do this,
171: you must keep track of the cursor position and update the records each
172: time anything is output to the terminal, including graphic characters.
173: In addition, it is necessary to know whether the terminal wraps after
174: writing in the rightmost column. *Note Wrapping::.
175:
176: One other motion capability needs special mention: `nw' moves the
177: cursor to the beginning of the following line, perhaps clearing all the
178: starting line after the cursor, or perhaps not clearing at all. This
179: capability is a least common denominator that is probably supported even by
180: terminals that cannot do most other things such as `cm' or `do'.
181: Even hardcopy terminals can support `nw'.
182:
183: `cm'
184: String of commands to position the cursor at line L, column C.
185: Both parameters are origin-zero, and are defined relative to the
186: screen, not relative to display memory.
187:
188: All display terminals except a few very obsolete ones support `cm',
189: so it is acceptable for an application program to refuse to operate on
190: terminals lacking `cm'.
191:
192: `ho'
193: String of commands to move the cursor to the upper left corner of the
194: screen (this position is called the "home position"). In
195: terminals where the upper left corner of the screen is not the same as
196: the beginning of display memory, this command must go to the upper
197: left corner of the screen, not the beginning of display memory.
198:
199: Every display terminal supports this capability, and many application
200: programs refuse to operate if the `ho' capability is missing.
201:
202: `ll'
203: String of commands to move the cursor to the lower left corner of the
204: screen. On some terminals, moving up from home position does this,
205: but programs should never assume that will work. Just output the
206: `ll' string (if it is provided); if moving to home position and
207: then moving up is the best way to get there, the `ll' command
208: will do that.
209:
210: `cr'
211: String of commands to move the cursor to the beginning of the line it
212: is on. If this capability is not specified, many programs assume
213: they can use the ASCII carriage return character for this.
214:
215: `le'
216: String of commands to move the cursor left one column. Unless the
217: `bw' flag capability is specified, the effect is undefined if the
218: cursor is at the left margin; do not use this command there. If
219: `bw' is present, this command may be used at the left margin, and
220: it wraps the cursor to the last column of the preceding line.
221:
222: `nd'
223: String of commands to move the cursor right one column. The effect is
224: undefined if the cursor is at the right margin; do not use this
225: command there, not even if `am' is present.
226:
227: `up'
228: String of commands to move the cursor vertically up one line. The
229: effect of sending this string when on the top line is undefined;
230: programs should never use it that way.
231:
232: `do'
233: String of commands to move the cursor vertically down one line. The
234: effect of sending this string when on the bottom line is undefined;
235: programs should never use it that way.
236:
237: The original idea was that this string would not contain a newline
238: character and therefore could be used without disabling the kernel's usual
239: habit of converting of newline into a carriage-return newline sequence.
240: But many terminal descriptions do use newline in the `do' string, so
241: this is not possible; a program which sends the `do' string must
242: disable output conversion in the kernel (*Note Initialize::).
243:
244: `bw'
245: Flag whose presence says that `le' may be used in column zero
246: to move to the last column of the preceding line. If this flag
247: is not present, `le' should not be used in column zero.
248:
249: `nw'
250: String of commands to move the cursor to start of next line, possibly
251: clearing rest of line (following the cursor) before moving.
252:
253: `DO', `UP', `LE', `RI'
254: Strings of commands to move the cursor N lines down vertically,
255: up vertically, or N columns left or right. Do not attempt to
256: move past any edge of the screen with these commands; the effect of
257: trying that is undefined. Only a few terminal descriptions provide
258: these commands, and most programs do not use them.
259:
260: `CM'
261: String of commands to position the cursor at line L, column
262: C, relative to display memory. Both parameters are origin-zero.
263: This capability is present only in terminals where there is a
264: difference between screen-relative and memory-relative addressing, and
265: not even in all such terminals.
266:
267: `ch'
268: String of commands to position the cursor at column C in the
269: same line it is on. This is a special case of `cm' in which the
270: vertical position is not changed. The `ch' capability is
271: provided only when it is faster to output than `cm' would be in
272: this special case. Programs should not assume most display terminals
273: have `ch'.
274:
275: `cv'
276: String of commands to position the cursor at line L in the same
277: column. This is a special case of `cm' in which the horizontal
278: position is not changed. The `cv' capability is provided only
279: when it is faster to output than `cm' would be in this special
280: case. Programs should not assume most display terminals have
281: `cv'.
282:
283: `sc'
284: String of commands to make the terminal save the current cursor
285: position. Only the last saved position can be used. If this
286: capability is present, `rc' should be provided also. Most
287: terminals have neither.
288:
289: `rc'
290: String of commands to make the terminal restore the last saved cursor
291: position. If this capability is present, `sc' should be provided
292: also. Most terminals have neither.
293:
294: `ff'
295: String of commands to advance to the next page, for a hardcopy
296: terminal.
297:
298: `ta'
299: String of commands to move the cursor right to the next hardware tab
300: stop column. Missing if the terminal does not have any kind of
301: hardware tabs. Do not send this command if the kernel's terminal
302: modes say that the kernel is expanding tabs into spaces.
303:
304: `bt'
305: String of commands to move the cursor left to the previous hardware
306: tab stop column. Missing if the terminal has no such ability; many
307: terminals do not. Do not send this command if the kernel's terminal
308: modes say that the kernel is expanding tabs into spaces.
309:
310: The following obsolete capabilities should be included in terminal
311: descriptions when appropriate, but should not be looked at by new programs.
312:
313: `nc'
314: Flag whose presence means the terminal does not support the ASCII
315: carriage return character as `cr'. This flag is needed because
316: old programs assume, when the `cr' capability is missing, that
317: ASCII carriage return can be used for the purpose. We use `nc'
318: to tell the old programs that carriage return may not be used.
319:
320: New programs should not assume any default for `cr', so they need
321: not look at `nc'. However, descriptions should contain `nc'
322: whenever they do not contain `cr'.
323:
324: `xt'
325: Flag whose presence means that the ASCII tab character may not be used
326: for cursor motion. This flag exists because old programs assume, when
327: the `ta' capability is missing, that ASCII tab can be used for
328: the purpose. We use `xt' to tell the old programs not to use tab.
329:
330: New programs should not assume any default for `ta', so they need
331: not look at `xt' in connection with cursor motion. Note that
332: `xt' also has implications for standout mode (*Note Standout::).
333: It is obsolete in regard to cursor motion but not in regard to
334: standout.
335:
336: In fact, `xt' means that the terminal is a Teleray 1061.
337:
338: `bc'
339: Very obsolete alternative name for the `le' capability.
340:
341: `bs'
342: Flag whose presence means that the ASCII character backspace may be
343: used to move the cursor left. Obsolete; look at `le' instead.
344:
345: `nl'
346: Obsolete capability which is a string that can either be used to move
347: the cursor down or to scroll. The same string must scroll when used
348: on the bottom line and move the cursor when used on any other line.
349: New programs should use `do' or `sf', and ignore `nl'.
350:
351: If there is no `nl' capability, some old programs assume they can
352: use the newline character for this purpose. These programs follow a
353: bad practice, but because they exist, it is still desirable to define
354: the `nl' capability in a terminal description if the best way to
355: move down is *not* a newline.
356:
357:
358: File: termcap Node: Wrapping, Prev: Cursor Motion, Up: Capabilities, Next: Scrolling
359:
360: Wrapping
361: ========
362:
363: "Wrapping" means moving the cursor from the right margin to the left
364: margin of the following line. Some terminals wrap automatically when a
365: graphic character is output in the last column, while others do not. Most
366: application programs that use termcap need to know whether the terminal
367: wraps. There are two special flag capabilities to describe what the
368: terminal does when a graphic character is output in the last column.
369:
370: `am'
371: Flag whose presence means that writing a character in the last column
372: causes the cursor to wrap to the beginning of the next line.
373:
374: If `am' is not present, writing in the last column leaves the
375: cursor at the place where the character was written.
376:
377: Writing in the last column of the last line should be avoided on
378: terminals with `am', as it may or may not cause scrolling to
379: occur (*Note Scrolling::). Scrolling is surely not what you would
380: intend.
381:
382: If your program needs to check the `am' flag, then it also needs
383: to check the `xn' flag which indicates that wrapping happens in a
384: strange way. Many common terminals have the `xn' flag.
385:
386: `xn'
387: Flag whose presence means that the cursor wraps in a strange way. At
388: least two distinct kinds of strange behavior are known; the termcap
389: data base does not contain anything to distinguish the two.
390:
391: On Concept-100 terminals, output in the last column wraps the cursor
392: almost like an ordinary `am' terminal. But if the next thing
393: output is a newline, it is ignored.
394:
395: DEC VT-100 terminals (when the wrap switch is on) do a different
396: strange thing: the cursor wraps only if the next thing output is
397: another graphic character. In fact, the wrap occurs when the
398: following graphic character is received by the terminal, before the
399: character is placed on the screen.
400:
401: On both of these terminals, after writing in the last column a
402: following graphic character will be displayed in the first column of
403: the following line. But the effect of relative cursor motion
404: characters such as newline or backspace at such a time depends on the
405: terminal. The effect of erase or scrolling commands also depends on
406: the terminal. You can't assume anything about what they will do on a
407: terminal that has `xn'. So, to be safe, you should never do
408: these things at such a time on such a terminal.
409:
410: To be sure of reliable results on a terminal which has the `xn'
411: flag, output a `cm' absolute positioning command after writing in
412: the last column. Another safe thing to do is to output carriage-return
413: newline, which will leave the cursor at the beginning of the following
414: line.
415:
416:
417: File: termcap Node: Scrolling, Prev: Wrapping, Up: Capabilities, Next: Windows
418:
419: Scrolling
420: =========
421:
422: "Scrolling" means moving the contents of the screen up or down one or
423: more lines. Moving the contents up is "forward scrolling"; moving them
424: down is "reverse scrolling".
425:
426: Scrolling happens after each line of output during ordinary output on most
427: display terminals. But in an application program that uses termcap for
428: random-access output, scrolling happens only when explicitly requested with
429: the commands in this section.
430:
431: Some terminals have a "scroll region" feature. This lets you limit
432: the effect of scrolling to a specified range of lines. Lines outside the
433: range are unaffected when scrolling happens. The scroll region feature
434: is available if either `cs' or `cS' is present.
435:
436: `sf'
437: String of commands to scroll the screen one line up, assuming it is
438: output with the cursor at the beginning of the bottom line.
439:
440: `sr'
441: String of commands to scroll the screen one line down, assuming it is
442: output with the cursor at the beginning of the top line.
443:
444: `SF'
445: String of commands to scroll the screen N lines up, assuming it
446: is output with the cursor at the beginning of the bottom line.
447:
448: `SR'
449: String of commands to scroll the screen N line down, assuming it
450: is output with the cursor at the beginning of the top line.
451:
452: `cs'
453: String of commands to set the scroll region. This command takes two
454: parameters, START and END, which are the line numbers
455: (origin-zero) of the first line to include in the scroll region and of
456: the last line to include in it. When a scroll region is set,
457: scrolling is limited to the specified range of lines; lines outside
458: the range are not affected by scroll commands.
459:
460: Do not try to move the cursor outside the scroll region. The region
461: remains set until explicitly removed. To remove the scroll region,
462: use another `cs' command specifying the full height of the
463: screen.
464:
465: The cursor position is undefined after the `cs' command is set,
466: so position the cursor with `cm' immediately afterward.
467:
468: `cS'
469: String of commands to set the scroll region using parameters in
470: different form. The effect is the same as if `cs' were used.
471: Four parameters are required:
472:
473: 1. Total number of lines on the screen.
474: 2. Number of lines above desired scroll region.
475: 3. Number of lines below (outside of) desired scroll region.
476: 4. Total number of lines on the screen, the same as the first parameter.
477:
478: This capability is a GNU extension that was invented to allow the Ann
479: Arbor Ambassador's scroll-region command to be described; it could
480: also be done by putting non-Unix `%'-sequences into a `cs'
481: string, but that would have confused Unix programs that used the
482: `cs' capability with the Unix termcap. Currently only GNU Emacs
483: uses the `cS' capability.
484:
485: `ns'
486: Flag which means that the terminal does not normally scroll for
487: ordinary sequential output. For modern terminals, this means that
488: outputting a newline in ordinary sequential output with the cursor on
489: the bottom line wraps to the top line. For some obsolete terminals,
490: other things may happen.
491:
492: The terminal may be able to scroll even if it does not normally do so.
493: If the `sf' capability is provided, it can be used for scrolling
494: regardless of `ns'.
495:
496: `da'
497: Flag whose presence means that lines scrolled up off the top of the
498: screen may come back if scrolling down is done subsequently.
499:
500: The `da' and `db' flags do not, strictly speaking, affect
501: how to scroll. But programs that scroll usually need to clear the
502: lines scrolled onto the screen, if these flags are present.
503:
504: `db'
505: Flag whose presence means that lines scrolled down off the bottom of
506: the screen may come back if scrolling up is done subsequently.
507:
508: `lm'
509: Numeric value, the number of lines of display memory that the terminal
510: has. A value of zero means that the terminal has more display memory
511: than can fit on the screen, but no fixed number of lines. (The number
512: of lines may depend on the amount of text in each line.)
513:
514: Any terminal description that defines `SF' should also define `sf';
515: likewise for `SR' and `sr'. However, many terminals can only scroll by
516: one line at a time, so it is common to find `sf' and not `SF', or `sr'
517: without `SR'.
518:
519: Therefore, all programs that use the scrolling facilities should be
520: prepared to work with `sf' in the case that `SF' is absent, and likewise
521: with `sr'. On the other hand, an application program that uses only
522: `sf' and not `SF' is acceptable, though slow on some terminals.
523:
524: When outputting a scroll command with `tputs', the NLINES
525: argument should be the total number of lines in the portion of the screen
526: being scrolled. Very often these commands require padding proportional to
527: this number of lines. *Note Padding::.
528:
529:
530: File: termcap Node: Windows, Prev: Scrolling, Up: Capabilities, Next: Clearing
531:
532: Windows
533: =======
534:
535: A "window", in termcap, is a rectangular portion of the screen to which
536: all display operations are restricted. Wrapping, clearing, scrolling,
537: insertion and deletion all operate as if the specified window were all the
538: screen there was.
539:
540: `wi'
541: String of commands to set the terminal output screen window.
542: This string requires four parameters, all origin-zero:
543: 1. The first line to include in the window.
544: 2. The last line to include in the window.
545: 3. The first column to include in the window.
546: 4. The last column to include in the window.
547:
548: Most terminals do not support windows.
549:
550:
551: File: termcap Node: Clearing, Prev: Windows, Up: Capabilities, Next: Insdel Line
552:
553: Clearing Parts of the Screen
554: ============================
555:
556: There are several terminal capabilities for clearing parts of the screen
557: to blank. All display terminals support the `cl' string, and most
558: display terminals support all of these capabilities.
559:
560: `cl'
561: String of commands to clear the entire screen and position the cursor
562: at the upper left corner.
563:
564: `cd'
565: String of commands to clear the line the cursor is on, and all the
566: lines below it, down to the bottom of the screen. This command string
567: should be used only with the cursor in column zero; their effect is
568: undefined if the cursor is elsewhere.
569:
570: `ce'
571: String of commands to clear from the cursor to the end of the current
572: line.
573:
574: `ec'
575: String of commands to clear N characters, starting with the
576: character that the cursor is on. This command string is expected to
577: leave the cursor position unchanged. The parameter N should never
578: be large enough to reach past the right margin; the effect of such a
579: large parameter would be undefined.
580:
581: Clear to end of line (`ce') is extremely important in programs that
582: maintain an updating display. Nearly all display terminals support this
583: operation, so it is acceptable for a an application program to refuse to
584: work if `ce' is not present. However, if you do not want this
585: limitation, you can accomplish clearing to end of line by outputting spaces
586: until you reach the right margin. In order to do this, you must know the
587: current horizontal position. Also, this technique assumes that writing a
588: space will erase. But this happens to be true on all the display terminals
589: that fail to support `ce'.
590:
591:
592: File: termcap Node: Insdel Line, Prev: Clearing, Up: Capabilities, Next: Insdel Char
593:
594: Insert/Delete Line
595: ==================
596:
597: "Inserting a line" means creating a blank line in the middle
598: of the screen, and pushing the existing lines of text apart. In fact,
599: the lines above the insertion point do not change, while the lines below
600: move down, and one is normally lost at the bottom of the screen.
601:
602: "Deleting a line" means causing the line to disappear from the screen,
603: closing up the gap by moving the lines below it upward. A new line
604: appears at the bottom of the screen. Usually this line is blank, but
605: on terminals with the `db' flag it may be a line previously moved
606: off the screen bottom by scrolling or line insertion.
607:
608: Insertion and deletion of lines is useful in programs that maintain an
609: updating display some parts of which may get longer or shorter. They are
610: also useful in editors for scrolling parts of the screen, and for
611: redisplaying after lines of text are killed or inserted.
612:
613: Many terminals provide commands to insert or delete a single line at the
614: cursor position. Some provide the ability to insert or delete several
615: lines with one command, using the number of lines to insert or delete as a
616: parameter. Always move the cursor to column zero before using any of
617: these commands.
618:
619: `al'
620: String of commands to insert a blank line before the line the cursor
621: is on. The existing line, and all lines below it, are moved down.
622: The last line in the screen (or in the scroll region, if one is set)
623: disappears and in most circumstances is discarded. It may not be
624: discarded if the `db' is present (*Note Scrolling::).
625:
626: The cursor must be at the left margin before this command is used.
627: This command does not move the cursor.
628:
629: `dl'
630: String of commands to delete the line the cursor is on. The following
631: lines move up, and a blank line appears at the bottom of the screen
632: (or bottom of the scroll region). If the terminal has the `db'
633: flag, a nonblank line previously pushed off the screen bottom may
634: reappear at the bottom.
635:
636: The cursor must be at the left margin before this command is used.
637: This command does not move the cursor.
638:
639: `AL'
640: String of commands to insert N blank lines before the line that
641: the cursor is on. It is like `al' repeated N times, except
642: that it is as fast as one `al'.
643:
644: `DL'
645: String of commands to delete N lines starting with the line that
646: the cursor is on. It is like `dl' repeated N times, except
647: that it is as fast as one `dl'.
648:
649: Any terminal description that defines `AL' should also define `al';
650: likewise for `DL' and `dl'. However, many terminals can only insert or
651: delete one line at a time, so it is common to find `al' and not `AL', or
652: `dl' without `DL'.
653:
654: Therefore, all programs that use the insert and delete facilities should
655: be prepared to work with `al' in the case that `AL' is absent, and
656: likewise with `dl'. On the other hand, it is acceptable to write an
657: application that uses only `al' and `dl' and does not look for `AL' or
658: `DL' at all.
659:
660: If a terminal does not support line insertion and deletion directly,
661: but does support a scroll region, the effect of insertion and deletion
662: can be obtained with scrolling. However, it is up to the individual
663: user program to check for this possibility and use the scrolling
664: commands to get the desired result. It is fairly important to implement
665: this alternate strategy, since it is the only way to get the effect of
666: line insertion and deletion on the popular VT100 terminal.
667:
668: Insertion and deletion of lines is affected by the scroll region on
669: terminals that have a settable scroll region. This is useful when it is
670: desirable to move any few consecutive lines up or down by a few lines.
671: *Note Scrolling::.
672:
673: The line pushed off the bottom of the screen is not lost if the terminal
674: has the `db' flag capability; instead, it is pushed into display
675: memory that does not appear on the screen. This is the same thing that
676: happens when scrolling pushes a line off the bottom of the screen.
677: Either reverse scrolling or deletion of a line can bring the apparently
678: lost line back onto the bottom of the screen. If the terminal has the
679: scroll region feature as well as `db', the pushed-out line really
680: is lost if a scroll region is in effect.
681:
682: When outputting an insert or delete command with `tputs', the
683: NLINES argument should be the total number of lines from the cursor
684: to the bottom of the screen (or scroll region). Very often these commands
685: require padding proportional to this number of lines. *Note Padding::.
686:
687: For `AL' and `DL' the NLINES argument should *not*
688: depend on the number of lines inserted or deleted; only the total number of
689: lines affected. This is because it is just as fast to insert two or
690: N lines with `AL' as to insert one line with `al'.
691:
692:
693: File: termcap Node: Insdel Char, Prev: Insdel Line, Up: Capabilities, Next: Standout
694:
695: Insert/Delete Character
696: =======================
697:
698: "Inserting a character" means creating a blank space in the middle of a
699: line, and pushing the rest of the line rightward. The character in the
700: rightmost column is lost.
701:
702: "Deleting a character" means causing the character to disappear from
703: the screen, closing up the gap by moving the rest of the line leftward. A
704: blank space appears in the rightmost column.
705:
706: Insertion and deletion of characters is useful in programs that maintain an
707: updating display some parts of which may get longer or shorter. It is also
708: useful in editors for redisplaying the results of editing within a line.
709:
710: Many terminals provide commands to insert or delete a single character at
711: the cursor position. Some provide the ability to insert or delete several
712: characters with one command, using the number of characters to insert or
713: delete as a parameter.
714:
715: Many terminals provide an insert mode in which outputting a graphic
716: character has the added effect of inserting a position for that character.
717: A special command string is used to enter insert mode and another is used
718: to exit it. The reason for designing a terminal with an insert mode rather
719: than an insert command is that inserting character positions is usually
720: followed by writing characters into them. With insert mode, this is as
721: fast as simply writing the characters, except for the fixed overhead of
722: entering and leaving insert mode. However, when the line speed is great
723: enough, padding may be required for the graphic characters output in insert
724: mode.
725:
726: Some terminals require you to enter insert mode and then output a special
727: command for each position to be inserted. Or they may require special
728: commands to be output before or after each graphic character to be
729: inserted.
730:
731: Deletion of characters is usually accomplished by a straightforward command
732: to delete one or several positions; but on some terminals, it is necessary
733: to enter a special delete mode before using the delete command, and leave
734: delete mode afterward. Sometimes delete mode and insert mode are the same
735: mode.
736:
737: Some terminals make a distinction between character positions in which a
738: space character has been output and positions which have been cleared. On
739: these terminals, the effect of insert or delete character runs to the first
740: cleared position rather than to the end of the line. In fact, the effect
741: may run to more than one line if there is no cleared position to stop the
742: shift on the first line. These terminals are identified by the `in'
743: flag capability.
744:
745: On terminals with the `in' flag, the technique of skipping over
746: characters that you know were cleared, and then outputting text later on in
747: the same line, causes later insert and delete character operations on that
748: line to do nonstandard things. A program that has any chance of doing this
749: must check for the `in' flag and must be careful to write explicit
750: space characters into the intermediate columns when `in' is present.
751:
752: A plethora of terminal capabilities are needed to describe all of this
753: complexity. Here is a list of them all. Following the list, we present
754: an algorithm for programs to use to take proper account of all of these
755: capabilities.
756:
757: `im'
758: String of commands to enter insert mode.
759:
760: If the terminal has no special insert mode, but it can insert
761: characters with a special command, `im' should be defined with a
762: null value, because the `vi' editor assumes that insertion of a
763: character is impossible if `im' is not provided.
764:
765: New programs should not act like `vi'. They should pay attention
766: to `im' only if it is defined.
767:
768: `ei'
769: String of commands to leave insert mode. This capability must be
770: present if `im' is.
771:
772: On a few old terminals the same string is used to enter and exit
773: insert mode. This string turns insert mode on if it was off, and off
774: it it was on. You can tell these terminals because the `ei'
775: string equals the `im' string. If you want to support these
776: terminals, you must always remember accurately whether insert mode is
777: in effect. However, these terminals are obsolete, and it is
778: reasonable to refuse to support them. On all modern terminals, you
779: can safely output `ei' at any time to ensure that insert mode is
780: turned off.
781:
782: `ic'
783: String of commands to insert one character position at the cursor.
784: The cursor does not move.
785:
786: If outputting a graphic character while in insert mode is sufficient
787: to insert the character, then the `ic' capability should be
788: defined with a null value.
789:
790: If your terminal offers a choice of ways to insert---either use insert
791: mode or use a special command---then define `im' and do not define
792: `ic', since this gives the most efficient operation when several
793: characters are to be inserted. *Do not* define both strings, for
794: that means that *both* must be used each time insertion is done.
795:
796: `ip'
797: String of commands to output following an inserted graphic character
798: in insert mode. Often it is used just for a padding spec, when padding
799: is needed after an inserted character (*Note Padding::).
800:
801: `IC'
802: String of commands to insert N character positions at and after
803: the cursor. It has the same effect as repeating the `ic' string
804: and a space, N times.
805:
806: If `IC' is provided, application programs may use it without first
807: entering insert mode.
808:
809: `mi'
810: Flag whose presence means it is safe to move the cursor while in insert
811: mode and assume the terminal remains in insert mode.
812:
813: `in'
814: Flag whose presence means that the terminal distinguishes between
815: character positions in which space characters have been output and
816: positions which have been cleared.
817:
818: An application program can assume that the terminal can do character
819: insertion if *any one of* the capabilities `IC', `im',
820: `ic' or `ip' is provided.
821:
822: To insert N blank character positions, move the cursor to the place
823: to insert them and follow this algorithm:
824:
825: 1. If an `IC' string is provided, output it with parameter N
826: and you are finished. Otherwise (or if you don't want to bother to
827: look for an `IC' string) follow the remaining steps.
828:
829: 2. Output the `im' string, if there is one, unless the terminal is
830: already in insert mode.
831:
832: 3. Repeat steps 4 through 6, N times.
833:
834: 4. Output the `ic' string if any.
835:
836: 5. Output a space.
837:
838: 6. Output the `ip' string if any.
839:
840: 7. Output the `ei' string, eventually, to exit insert mode. There
841: is no need to do this right away. If the `mi' flag is present,
842: you can move the cursor and the cursor will remain in insert mode;
843: then you can do more insertion elsewhere without reentering insert
844: mode.
845:
846: To insert N graphic characters, position the cursor and follow this
847: algorithm:
848:
849: 1. If an `IC' string is provided, output it with parameter N,
850: then output the graphic characters, and you are finished. Otherwise
851: (or if you don't want to bother to look for an `IC' string)
852: follow the remaining steps.
853:
854: 2. Output the `im' string, if there is one, unless the terminal is
855: already in insert mode.
856:
857: 3. For each character to be output, repeat steps 4 through 6.
858:
859: 4. Output the `ic' string if any.
860:
861: 5. Output the next graphic character.
862:
863: 6. Output the `ip' string if any.
864:
865: 7. Output the `ei' string, eventually, to exit insert mode. There
866: is no need to do this right away. If the `mi' flag is present,
867: you can move the cursor and the cursor will remain in insert mode;
868: then you can do more insertion elsewhere without reentering insert
869: mode.
870:
871: Note that this is not the same as the original Unix termcap specifications
872: in one respect: it assumes that the `IC' string can be used without
873: entering insert mode. This is true as far as I know, and it allows you be
874: able to avoid entering and leaving insert mode, and also to be able to
875: avoid the inserted-character padding after the characters that go into the
876: inserted positions.
877:
878: Deletion of characters is less complicated; deleting one column is done by
879: outputting the `dc' string. However, there may be a delete mode that
880: must be entered with `dm' in order to make `dc' work.
881:
882: `dc'
883: String of commands to delete one character position at the cursor. If
884: `dc' is not present, the terminal cannot delete characters.
885:
886: `DC'
887: String of commands to delete N characters starting at the cursor.
888: It has the same effect as repeating the `dc' string N times.
889: Any terminal description that has `DC' also has `dc'.
890:
891: `dm'
892: String of commands to enter delete mode. If not present, there is no
893: delete mode, and `dc' can be used at any time (assuming there is
894: a `dc').
895:
896: `ed'
897: String of commands to exit delete mode. This must be present if
898: `dm' is.
899:
900: To delete N character positions, position the cursor and follow these
901: steps:
902:
903: 1. If the `DC' string is present, output it with parameter N
904: and you are finished. Otherwise, follow the remaining steps.
905:
906: 2. Output the `dm' string, unless you know the terminal is already
907: in delete mode.
908:
909: 3. Output the `dc' string N times.
910:
911: 4. Output the `ed' string eventually. If the flag capability
912: `mi' is present, you can move the cursor and do more deletion
913: without leaving and reentering delete mode.
914:
915: As with the `IC' string, we have departed from the original termcap
916: specifications by assuming that `DC' works without entering delete
917: mode even though `dc' would not.
918:
919: If the `dm' and `im' capabilities are both present and have the
920: same value, it means that the terminal has one mode for both insertion and
921: deletion. It is useful for a program to know this, because then it can do
922: insertions after deletions, or vice versa, without leaving insert/delete
923: mode and reentering it.
924:
925:
926: File: termcap Node: Standout, Prev: Insdel Char, Up: Capabilities, Next: Underlining
927:
928: Standout and Appearance Modes
929: =============================
930:
931: "Appearance modes" are modifications to the ways characters are
932: displayed. Typical appearance modes include reverse video, dim, bright,
933: blinking, underlined, invisible, and alternate character set. Each kind of
934: terminal supports various among these, or perhaps none.
935:
936: For each type of terminal, one appearance mode or combination of them that
937: looks good for highlighted text is chosen as the "standout mode". The
938: capabilities `so' and `se' say how to enter and leave standout
939: mode. Programs that use appearance modes only to highlight some text
940: generally use the standout mode so that they can work on as many terminals
941: as possible. Use of specific appearance modes other than "underlined"
942: and "alternate character set" is rare.
943:
944: Terminals that implement appearance modes fall into two general classes as
945: to how they do it.
946:
947: In some terminals, the presence or absence of any appearance mode is
948: recorded separately for each character position. In these terminals, each
949: graphic character written is given the appearance modes current at the time
950: it is written, and keeps those modes until it is erased or overwritten.
951: There are special commands to turn the appearance modes on or off for
952: characters to be written in the future.
953:
954: In other terminals, the change of appearance modes is represented by a
955: marker that belongs to a certain screen position but affects all following
956: screen positions until the next marker. These markers are traditionally
957: called "magic cookies".
958:
959: The same capabilities (`so', `se', `mb' and so on) for
960: turning appearance modes on and off are used for both magic-cookie
961: terminals and per-character terminals. On magic cookie terminals, these
962: give the commands to write the magic cookies. On per-character terminals,
963: they change the current modes that affect future output and erasure. Some
964: simple applications can use these commands without knowing whether or not
965: they work by means of cookies.
966:
967: However, a program that maintains and updates a display needs to know
968: whether the terminal uses magic cookies, and exactly what their effect is.
969: This information comes from the `sg' capability.
970:
971: The `sg' capability is a numeric capability whose presence indicates
972: that the terminal uses magic cookies for appearance modes. Its value is
973: the number of character positions that a magic cookie occupies. Usually
974: the cookie occupies one or more character positions on the screen, and these
975: character positions are displayed as blank, but in some terminals the
976: cookie has zero width.
977:
978: The `sg' capability describes both the magic cookie to turn standout
979: on and the cookie to turn it off. This makes the assumption that both
980: kinds of cookie have the same width on the screen. If that is not true,
981: the narrower cookie must be "widened" with spaces until it has the same
982: width as the other.
983:
984: On some magic cookie terminals, each line always starts with normal
985: display; in other words, the scope of a magic cookie never extends over
986: more than one line. But on other terminals, one magic cookie affects all
987: the lines below it unless explicitly canceled. Termcap does not define any
988: way to distinguish these two ways magic cookies can work. To be safe, it
989: is best to put a cookie at the beginning of each line.
990:
991: On some per-character terminals, standout mode or other appearance modes
992: may be canceled by moving the cursor. On others, moving the cursor has no
993: effect on the state of the appearance modes. The latter class of terminals
994: are given the flag capability `ms' ("can move in standout"). All
995: programs that might have occasion to move the cursor while appearance modes
996: are turned on must check for this flag; if it is not present, they should
997: reset appearance modes to normal before doing cursor motion.
998:
999: A program that has turned on only standout mode should use `se' to
1000: reset the standout mode to normal. A program that has turned on only
1001: alternate character set mode should use `ae' to return it to normal.
1002: If it is possible that any other appearance modes are turned on, use the
1003: `me' capability to return them to normal.
1004:
1005: Note that the commands to turn on one appearance mode, including `so'
1006: and `mb' ... `mr', if used while some other appearance modes
1007: are turned on, may combine the two modes on some terminals but may turn off
1008: the mode previously enabled on other terminals. This is because some
1009: terminals do not have a command to set or clear one appearance mode without
1010: changing the others. Programs should not attempt to use appearance modes
1011: in combination except with `sa', and when switching from one single
1012: mode to another should always turn off the previously enabled mode and then
1013: turn on the new desired mode.
1014:
1015: On some old terminals, the `so' and `se' commands may be the same
1016: command, which has the effect of turning standout on if it is off, or off
1017: it is on. It is therefore risky for a program to output extra `se'
1018: commands for good measure. Fortunately, all these terminals are obsolete.
1019:
1020: Programs that update displays in which standout-text may be replaced with
1021: non-standout text must check for the `xs' flag. In a per-character
1022: terminal, this flag says that the only way to remove standout once written is
1023: to clear that portion of the line with the `ce' string or something
1024: even more powerful (*Note Clearing::); just writing new characters at those
1025: screen positions will not change the modes in effect there. In a magic
1026: cookie terminal, `xs' says that the only way to remove a cookie is to
1027: clear a portion of the line that includes the cookie; writing a different
1028: cookie at the same position does not work.
1029:
1030: Such programs must also check for the `xt' flag, which means that the
1031: terminal is a Teleray 1061. On this terminal it is impossible to position
1032: the cursor at the front of a magic cookie, so the only two ways to remove a
1033: cookie are (1) to delete the line it is on or (2) to position the cursor at
1034: least one character before it (possibly on a previous line) and output the
1035: `se' string, which on these terminals finds and removes the next
1036: `so' magic cookie on the screen. (It may also be possible to remove a
1037: cookie which is not at the beginning of a line by clearing that line.) The
1038: `xt' capability also has implications for the use of tab characters,
1039: but in that regard it is obsolete (*Note Cursor Motion::).
1040:
1041: `so'
1042: String of commands to enter standout mode.
1043:
1044: `se'
1045: String of commands to leave standout mode.
1046:
1047: `sg'
1048: Numeric capability, the width on the screen of the magic cookie. This
1049: capability is absent in terminals that record appearance modes
1050: character by character.
1051:
1052: `ms'
1053: Flag whose presence means that it is safe to move the cursor while the
1054: appearance modes are not in the normal state. If this flag is absent,
1055: programs should always reset the appearance modes to normal before
1056: moving the cursor.
1057:
1058: `xs'
1059: Flag whose presence means that the only way to reset appearance modes
1060: already on the screen is to clear to end of line. On a per-character
1061: terminal, you must clear the area where the modes are set. On a magic
1062: cookie terminal, you must clear an area containing the cookie.
1063: See the discussion above.
1064:
1065: `xt'
1066: Flag whose presence means that the cursor cannot be positioned right
1067: in front of a magic cookie, and that `se' is a command to delete
1068: the next magic cookie following the cursor. See discussion above.
1069:
1070: `mb'
1071: String of commands to enter blinking mode.
1072:
1073: `md'
1074: String of commands to enter double-bright mode.
1075:
1076: `mh'
1077: String of commands to enter half-bright mode.
1078:
1079: `mk'
1080: String of commands to enter invisible mode.
1081:
1082: `mp'
1083: String of commands to enter protected mode.
1084:
1085: `mr'
1086: String of commands to enter reverse-video mode.
1087:
1088: `me'
1089: String of commands to turn off all appearance modes, including
1090: standout mode and underline mode. On some terminals it also turns off
1091: alternate character set mode; on others, it may not. This capability
1092: must be present if any of `mb' ... `mr' is present.
1093:
1094: `as'
1095: String of commands to turn on alternate character set mode. This mode
1096: assigns some or all graphic characters an alternate picture on the
1097: screen. There is no standard as to what the alternate pictures look
1098: like.
1099:
1100: `ae'
1101: String of commands to turn off alternate character set mode.
1102:
1103: `sa'
1104: String of commands to turn on an arbitrary combination of appearance
1105: modes. It accepts 9 parameters, each of which controls a particular
1106: kind of appearance mode. A parameter should be 1 to turn its appearance
1107: mode on, or zero to turn that mode off. Most terminals do not support
1108: the `sa' capability, even among those that do have various
1109: appearance modes.
1110:
1111: The nine parameters are, in order, STANDOUT, UNDERLINE,
1112: REVERSE, BLINK, HALF-BRIGHT, DOUBLE-BRIGHT,
1113: BLANK, PROTECT, ALT CHAR SET.
1114:
1115:
1116: File: termcap Node: Underlining, Prev: Standout, Up: Capabilities, Next: Cursor Visibility
1117:
1118: Underlining
1119: ===========
1120:
1121: Underlining on most terminals is a kind of appearance mode, much like
1122: standout mode. Therefore, it may be implemented using magic cookies or as
1123: a flag in the terminal whose current state affects each character that is
1124: output. *Note Standout::, for a full explanation.
1125:
1126: The `ug' capability is a numeric capability whose presence indicates
1127: that the terminal uses magic cookies for underlining. Its value is the
1128: number of character positions that a magic cookie for underlining occupies;
1129: it is used for underlining just as `sg' is used for standout. Aside
1130: from the simplest applications, it is impossible to use underlining
1131: correctly without paying attention to the value of `ug'.
1132:
1133: `us'
1134: String of commands to turn on underline mode or to output a magic cookie
1135: to start underlining.
1136:
1137: `ue'
1138: String of commands to turn off underline mode or to output a magic
1139: cookie to stop underlining.
1140:
1141: `ug'
1142: Width of magic cookie that represents a change of underline mode;
1143: or missing, if the terminal does not use a magic cookie for this.
1144:
1145: `ms'
1146: Flag whose presence means that it is safe to move the cursor while the
1147: appearance modes are not in the normal state. Underlining is an
1148: appearance mode. If this flag is absent, programs should always turn
1149: off underlining before moving the cursor.
1150:
1151: There are two other, older ways of doing underlining: there can be a
1152: command to underline a single character, or the output of `_', the
1153: ASCII underscore character, as an overstrike could cause a character to be
1154: underlined. New programs need not bother to handle these capabilities
1155: unless the author cares strongly about the obscure terminals which support
1156: them. However, terminal descriptions should provide these capabilities
1157: when appropriate.
1158:
1159: `uc'
1160: String of commands to underline the character under the cursor, and
1161: move the cursor right.
1162:
1163: `ul'
1164: Flag whose presence means that the terminal can underline by
1165: overstriking an underscore character (`_'); some terminals can do
1166: this even though they do not support overstriking in general. An
1167: implication of this flag is that when outputting new text to overwrite
1168: old text, underscore characters must be treated specially lest they
1169: underline the old text instead.
1170:
1171:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.