ncurses 6.0 - patch 20161001
[ncurses.git] / man / infocmp.1m
1 '\" t
2 .\"***************************************************************************
3 .\" Copyright (c) 1998-2015,2016 Free Software Foundation, Inc.              *
4 .\"                                                                          *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
6 .\" copy of this software and associated documentation files (the            *
7 .\" "Software"), to deal in the Software without restriction, including      *
8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
10 .\" copies of the Software, and to permit persons to whom the Software is    *
11 .\" furnished to do so, subject to the following conditions:                 *
12 .\"                                                                          *
13 .\" The above copyright notice and this permission notice shall be included  *
14 .\" in all copies or substantial portions of the Software.                   *
15 .\"                                                                          *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
23 .\"                                                                          *
24 .\" Except as contained in this notice, the name(s) of the above copyright   *
25 .\" holders shall not be used in advertising or otherwise to promote the     *
26 .\" sale, use or other dealings in this Software without prior written       *
27 .\" authorization.                                                           *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: infocmp.1m,v 1.58 2016/10/01 17:15:45 tom Exp $
31 .TH @INFOCMP@ 1M ""
32 .ds n 5
33 .de bP
34 .IP \(bu 4
35 ..
36 .ds d @TERMINFO@
37 .SH NAME
38 \fB@INFOCMP@\fR \- compare or print out \fIterminfo\fR descriptions
39 .SH SYNOPSIS
40 \fB@INFOCMP@\fR [\fB\-\
41 1\
42 C\
43 D\
44 E\
45 F\
46 G\
47 I\
48 K\
49 L\
50 T\
51 U\
52 V\
53 W\
54 c\
55 d\
56 e\
57 g\
58 i\
59 l\
60 n\
61 p\
62 q\
63 r\
64 t\
65 u\
66 x\
67 \fR]
68 .br
69       [\fB\-v\fR \fIn\fR] [\fB\-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR] [\fB\-Q\fR \fIn\fR] [\fB\-R \fR\fBsubset\fR]
70 .br
71       [\fB\-w\fR\ \fIwidth\fR] [\fB\-A\fR\ \fIdirectory\fR] [\fB\-B\fR\ \fIdirectory\fR]
72 .br
73       [\fItermname\fR...]
74 .SH DESCRIPTION
75 \fB@INFOCMP@\fR can be used to compare a binary \fBterminfo\fR entry with other
76 terminfo entries, rewrite a \fBterminfo\fR description to take advantage of the
77 \fBuse=\fR terminfo field, or print out a \fBterminfo\fR description from the
78 binary file (\fBterm\fR) in a variety of formats.
79 In all cases, the boolean
80 fields will be printed first, followed by the numeric fields, followed by the
81 string fields.
82 .SS Default Options
83 If no options are specified and zero or one \fItermnames\fR are specified, the
84 \fB\-I\fR option will be assumed.
85 If more than one \fItermname\fR is specified,
86 the \fB\-d\fR option will be assumed.
87 .SS Comparison Options [\-d] [\-c] [\-n]
88 \fB@INFOCMP@\fR compares the \fBterminfo\fR description of the first terminal
89 \fItermname\fR with each of the descriptions given by the entries for the other
90 terminal's \fItermnames\fR.
91 If a capability is defined for only one of the
92 terminals, the value returned will depend on the type of the capability:
93 \fBF\fR for boolean variables, \fB\-1\fR for integer variables, and \fBNULL\fR
94 for string variables.
95 .PP
96 The \fB\-d\fR option produces a list of each capability that is different
97 between two entries.
98 This option is useful to show the difference between two
99 entries, created by different people, for the same or similar terminals.
100 .PP
101 The \fB\-c\fR option produces a list of each capability that is common between
102 two or more entries.
103 Capabilities that are not set are ignored.
104 This option can be
105 used as a quick check to see if the \fB\-u\fR option is worth using.
106 .PP
107 The \fB\-n\fR option produces a list of each capability that is in none of
108 the given entries.
109 If no \fItermnames\fR are given, the environment variable \fBTERM\fR
110 will be used for both of the \fItermnames\fR.
111 This can be used as a quick
112 check to see if anything was left out of a description.
113 .SS Source Listing Options [\-I] [\-L] [\-C] [\-r]
114 The \fB\-I\fR, \fB\-L\fR, and \fB\-C\fR options will produce a source listing for
115 each terminal named.
116 .
117 .TS
118 center tab(/) ;
119 l l .
120 \fB\-I\fR/use the \fBterminfo\fR names
121 \fB\-L\fR/use the long C variable name listed in <\fBterm.h\fR>
122 \fB\-C\fR/use the \fBtermcap\fR names
123 \fB\-r\fR/when using \fB\-C\fR, put out all capabilities in \fBtermcap\fR form
124 \fB\-K\fR/modifies the \fB\-C\fP option, improving BSD-compatibility.
125 .TE
126 .PP
127 If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be
128 used for the terminal name.
129 .PP
130 The source produced by the \fB\-C\fR option may be used directly as a
131 \fBtermcap\fR entry, but not all parameterized strings can be changed to
132 the \fBtermcap\fR format.
133 \fB@INFOCMP@\fR will attempt to convert most of the
134 parameterized information, and anything not converted will be plainly marked in
135 the output and commented out.
136 These should be edited by hand.
137 .PP
138 For best results when converting to \fBtermcap\fP format,
139 you should use both \fB\-C\fP and \fB\-r\fP.
140 Normally a termcap description is limited to 1023 bytes.
141 @INFOCMP@ trims away less essential parts to make it fit.
142 If you are converting to one of the (rare) termcap implementations
143 which accept an unlimited size of termcap,
144 you may want to add the \fB\-T\fP option.
145 More often however, you must help the termcap implementation,
146 and trim excess whitespace (use the \fB\-0\fP option for that).
147 .PP
148 All padding information for strings will be collected together and placed
149 at the beginning of the string where \fBtermcap\fR expects it.
150 Mandatory
151 padding (padding information with a trailing '/') will become optional.
152 .PP
153 All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which
154 are derivable from other \fBterminfo\fR variables, will be output.
155 Not all
156 \fBterminfo\fR capabilities will be translated; only those variables which were
157 part of \fBtermcap\fR will normally be output.
158 Specifying the \fB\-r\fR option
159 will take off this restriction, allowing all capabilities to be output in
160 \fItermcap\fR form.
161 Normally you would use both the \fB\-C\fP and \fB\-r\fP options.
162 The actual format used incorporates some improvements for escaped characters
163 from terminfo format.
164 For a stricter BSD-compatible translation, use the \fB\-K\fR option
165 rather than \fB\-C\fP.
166 .PP
167 Note that because padding is collected to the beginning of the capability, not
168 all capabilities are output.
169 Mandatory padding is not supported.
170 Because
171 \fBtermcap\fR strings are not as flexible, it is not always possible to convert
172 a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format.
173 A subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format
174 will not necessarily reproduce the original \fBterminfo\fR
175 source.
176 .PP
177 Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR
178 equivalents, and some terminal types which commonly have such sequences, are:
179 .
180 .TS
181 center tab(/) ;
182 l c l
183 l l l.
184 \fBterminfo/termcap\fR/Representative Terminals
185 =
186 \fB%p1%c/%.\fR/adm
187 \fB%p1%d/%d\fR/hp, ANSI standard, vt100
188 \fB%p1%'x'%+%c/%+x\fR/concept
189 \fB%i/%i\fRq/ANSI standard, vt100
190 \fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fR/concept
191 \fB%p2\fR is printed before \fB%p1/%r\fR/hp
192 .TE
193 .SS Use= Option [\-u]
194 The \fB\-u\fR option produces a \fBterminfo\fR source description of the first
195 terminal \fItermname\fR which is relative to the sum of the descriptions given
196 by the entries for the other terminals \fItermnames\fR.
197 It does this by
198 analyzing the differences between the first \fItermname\fR and the other
199 \fItermnames\fR and producing a description with \fBuse=\fR fields for the
200 other terminals.
201 In this manner, it is possible to retrofit generic terminfo
202 entries into a terminal's description.
203 Or, if two similar terminals exist, but
204 were coded at different times or by different people so that each description
205 is a full description, using \fB@INFOCMP@\fR will show what can be done to change
206 one description to be relative to the other.
207 .PP
208 A capability will get printed with an at-sign (@) if it no longer exists in the
209 first \fItermname\fR, but one of the other \fItermname\fR entries contains a
210 value for it.
211 A capability's value gets printed if the value in the first
212 \fItermname\fR is not found in any of the other \fItermname\fR entries, or if
213 the first of the other \fItermname\fR entries that has this capability gives a
214 different value for the capability than that in the first \fItermname\fR.
215 .PP
216 The order of the other \fItermname\fR entries is significant.
217 Since the
218 terminfo compiler \fB@TIC@\fR does a left-to-right scan of the capabilities,
219 specifying two \fBuse=\fR entries that contain differing entries for the same
220 capabilities will produce different results depending on the order that the
221 entries are given in.
222 \fB@INFOCMP@\fR will flag any such inconsistencies between
223 the other \fItermname\fR entries as they are found.
224 .PP
225 Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that
226 contains that capability will cause the second specification to be ignored.
227 Using \fB@INFOCMP@\fR to recreate a description can be a useful check to make
228 sure that everything was specified correctly in the original source
229 description.
230 .PP
231 Another error that does not cause incorrect compiled files, but will slow down
232 the compilation time, is specifying extra \fBuse=\fR fields that are
233 superfluous.
234 \fB@INFOCMP@\fR will flag any other \fItermname use=\fR fields that
235 were not needed.
236 .SS Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]
237 Like other \fBncurses\fP utilities,
238 @INFOCMP@ looks for the terminal descriptions in several places.
239 You can use the \fBTERMINFO\fP and \fBTERMINFO_DIRS\fP environment variables
240 to override the compiled-in default list of places to search
241 (see \fBcurses\fP(3X) for details).
242 .PP
243 You can also use the options \fB\-A\fR
244 and \fB\-B\fR to override the list of places to search
245 when comparing terminal descriptions:
246 .bP
247 The \fB\-A\fR option sets the location for the first \fItermname\fR
248 .bP
249 The \fB\-B\fR option sets the location for the other \fItermnames\fR.
250 .PP
251 Using these options, it is possible to
252 compare descriptions for a terminal with the same name located in two different
253 databases.
254 For instance,
255 you can use this feature for comparing descriptions for the same terminal
256 created by different people.
257 .SS Other Options
258 .TP 5
259 \fB\-0\fR
260 causes the fields to be printed on one line, without wrapping.
261 .TP 5
262 \fB\-1\fR
263 causes the fields to be printed out one to a line.
264 Otherwise,
265 the fields will be printed several to a line to a maximum width
266 of 60 characters.
267 .TP
268 \fB\-a\fR
269 tells \fB@INFOCMP@\fP to retain commented-out capabilities rather than discarding
270 them.
271 Capabilities are commented by prefixing them with a period.
272 .TP
273 \fB\-D\fR
274 tells \fB@INFOCMP@\fP to print the database locations that it knows about, and exit.
275 .TP 5
276 \fB\-E\fR
277 Dump the capabilities of the given terminal as tables, needed in
278 the C initializer for a
279 TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
280 This option is useful for preparing versions of the curses library hardwired
281 for a given terminal type.
282 The tables are all declared static, and are named according to the type
283 and the name of the corresponding terminal entry.
284 .sp
285 Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
286 options was not needed; but support for extended names required making
287 the arrays of terminal capabilities separate from the TERMTYPE structure.
288 .TP 5
289 \fB\-e\fR
290 Dump the capabilities of the given terminal as a C initializer for a
291 TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
292 This option is useful for preparing versions of the curses library hardwired
293 for a given terminal type.
294 .TP 5
295 \fB\-F\fR
296 compare terminfo files.
297 This assumes that two following arguments are filenames.
298 The files are searched for pairwise matches between
299 entries, with two entries considered to match if any of their names do.
300 The report printed to standard output lists entries with no matches in
301 the other file, and entries with more than one match.
302 For entries
303 with exactly one match it includes a difference report.
304 Normally,
305 to reduce the volume of the report, use references are
306 not resolved before looking for differences, but resolution can be forced
307 by also specifying \fB\-r\fR.
308 .TP 5
309 \fB\-f\fR
310 Display complex terminfo strings which contain if/then/else/endif expressions
311 indented for readability.
312 .TP 5
313 \fB\-G\fR
314 Display constant literals in decimal form
315 rather than their character equivalents.
316 .TP 5
317 \fB\-g\fR
318 Display constant character literals in quoted form
319 rather than their decimal equivalents.
320 .TP 5
321 \fB\-i\fR
322 Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset
323 (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry,
324 as well as those used for starting/stopping cursor-positioning mode
325 (\fBsmcup\fP, \fBrmcup\fP) as well as starting/stopping keymap mode
326 (\fBsmkx\fP, \fBrmkx\fP).
327 .IP
328 For each string, the
329 code tries to analyze it into actions in terms of the other capabilities in the
330 entry, certain X3.64/ISO 6429/ECMA\-48 capabilities, and certain DEC VT-series
331 private modes (the set of recognized special sequences has been selected for
332 completeness over the existing terminfo database).
333 Each report line consists
334 of the capability name, followed by a colon and space, followed by a printable
335 expansion of the capability string with sections matching recognized actions
336 translated into {}-bracketed descriptions.
337 .IP
338 Here is a list of the DEC/ANSI
339 special sequences recognized:
340 .TS
341 center tab(/) ;
342 l l
343 l l.
344 Action/Meaning
345 =
346 RIS/full reset
347 SC/save cursor
348 RC/restore cursor
349 LL/home-down
350 RSR/reset scroll region
351 =
352 DECSTR/soft reset (VT320)
353 S7C1T/7-bit controls (VT220)
354 =
355 ISO DEC G0/enable DEC graphics for G0
356 ISO UK G0/enable UK chars for G0
357 ISO US G0/enable US chars for G0
358 ISO DEC G1/enable DEC graphics for G1
359 ISO UK G1/enable UK chars for G1
360 ISO US G1/enable US chars for G1
361 =
362 DECPAM/application keypad mode
363 DECPNM/normal keypad mode
364 DECANSI/enter ANSI mode
365 =
366 ECMA[+\-]AM/keyboard action mode
367 ECMA[+\-]IRM/insert replace mode
368 ECMA[+\-]SRM/send receive mode
369 ECMA[+\-]LNM/linefeed mode
370 =
371 DEC[+\-]CKM/application cursor keys
372 DEC[+\-]ANM/set VT52 mode
373 DEC[+\-]COLM/132-column mode
374 DEC[+\-]SCLM/smooth scroll
375 DEC[+\-]SCNM/reverse video mode
376 DEC[+\-]OM/origin mode
377 DEC[+\-]AWM/wraparound mode
378 DEC[+\-]ARM/auto-repeat mode
379 .TE
380 .sp
381 It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
382 Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
383 REVERSE.
384 All but NORMAL may be prefixed with `+' (turn on) or `\-' (turn off).
385 .IP
386 An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
387 .TP 5
388 \fB\-l\fR
389 Set output format to terminfo.
390 .TP 5
391 \fB\-p\fR
392 Ignore padding specifications when comparing strings.
393 .TP 5
394 \fB\-Q\fR \fIn\fR
395 Rather than show source in terminfo (text) format,
396 print the compiled (binary) format in hexadecimal or base64 form,
397 depending on the option's value:
398 .RS 8
399 .TP 3
400 1
401 hexadecimal
402 .TP 3
403 2
404 base64
405 .TP 3
406 3
407 hexadecimal and base64
408 .RE
409 .TP 5
410 \fB\-q\fR
411 This makes the output a little shorter:
412 .RS
413 .bP
414 Make the comparison listing shorter by omitting subheadings, and using
415 "\-" for absent capabilities, "@" for canceled rather than "NULL".
416 .bP
417 Omit the "Reconstructed from" comment for source listings.
418 .RE
419 .TP 5
420 \fB\-R\fR\fIsubset\fR
421 Restrict output to a given subset.
422 This option is for use with archaic
423 versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
424 the full set of SVR4/XSI Curses terminfo; and variants such as AIX
425 that have their own extensions incompatible with SVr4/XSI.
426 .IP
427 Available terminfo
428 subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for
429 details.
430 You can also choose the subset "BSD" which selects only capabilities
431 with termcap equivalents recognized by 4.4BSD.
432 .TP
433 \fB\-s \fR\fI[d|i|l|c]\fR
434 The \fB\-s\fR option sorts the fields within each type according to the argument
435 below:
436 .br
437 .RS 5
438 .TP 5
439 \fBd\fR
440 leave fields in the order that they are stored in the \fIterminfo\fR database.
441 .TP 5
442 \fBi\fR
443 sort by \fIterminfo\fR name.
444 .TP 5
445 \fBl\fR
446 sort by the long C variable name.
447 .TP 5
448 \fBc\fR
449 sort by the \fItermcap\fR name.
450 .RE
451 .IP
452 If the \fB\-s\fR option is not given, the fields printed out will be
453 sorted alphabetically by the \fBterminfo\fR name within each type,
454 except in the case of the \fB\-C\fR or the \fB\-L\fR options, which cause the
455 sorting to be done by the \fBtermcap\fR name or the long C variable
456 name, respectively.
457 .TP 5
458 \fB\-T\fR
459 eliminates size-restrictions on the generated text.
460 This is mainly useful for testing and analysis, since the compiled
461 descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
462 .TP
463 \fB\-t\fR
464 tells \fB@TIC@\fP to discard commented-out capabilities.
465 Normally when translating from terminfo to termcap,
466 untranslatable capabilities are commented-out.
467 .TP 5
468 \fB\-U\fR
469 tells \fB@INFOCMP@\fP to not post-process the data after parsing the source file.
470 This feature helps when comparing the actual contents of two source files,
471 since it excludes the inferences that \fB@INFOCMP@\fP makes to fill in missing
472 data.
473 .TP 5
474 \fB\-V\fR
475 reports the version of ncurses which was used in this program, and exits.
476 .TP 5
477 \fB\-v\fR \fIn\fR
478 prints out tracing information on standard error as the program runs.
479 Higher values of n induce greater verbosity.
480 .TP
481 \fB\-W\fR
482 By itself, the \fB\-w\fP option will not force long strings to be wrapped.
483 Use the \fB\-W\fP option to do this.
484 .TP 5
485 \fB\-w\fR \fIwidth\fR
486 changes the output to \fIwidth\fR characters.
487 .TP
488 \fB\-x\fR
489 print information for user-defined capabilities.
490 These are extensions to the terminfo repertoire which can be loaded
491 using the \fB\-x\fR option of \fB@TIC@\fP.
492 .SH FILES
493 .TP 20
494 \*d
495 Compiled terminal description database.
496 .SH EXTENSIONS
497 The
498 \fB\-0\fR,
499 \fB\-1\fR,
500 \fB\-E\fR,
501 \fB\-F\fR,
502 \fB\-G\fR,
503 \fB\-R\fR,
504 \fB\-T\fR,
505 \fB\-V\fR,
506 \fB\-a\fR,
507 \fB\-e\fR,
508 \fB\-f\fR,
509 \fB\-g\fR,
510 \fB\-i\fR,
511 \fB\-l\fR,
512 \fB\-p\fR,
513 \fB\-q\fR and
514 \fB\-t\fR
515 options are not supported in SVr4 curses.
516 .PP
517 The \fB\-r\fR option's notion of `termcap' capabilities is System V Release 4's.
518 Actual BSD curses versions will have a more restricted set.
519 To see only the
520 4.4BSD set, use \fB\-r\fR \fB\-RBSD\fR.
521 .SH BUGS
522 The \fB\-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode.
523 .SH SEE ALSO
524 \fB@CAPTOINFO@\fR(1M),
525 \fB@INFOTOCAP@\fR(1M),
526 \fB@TIC@\fR(1M),
527 \fB@TOE@\fR(1M),
528 \fBcurses\fR(3X),
529 \fBterminfo\fR(\*n).
530 .sp
531 http://invisible-island.net/ncurses/tctest.html
532 .PP
533 This describes \fBncurses\fR
534 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
535 .SH AUTHOR
536 Eric S. Raymond <esr@snark.thyrsus.com>
537 and
538 .br
539 Thomas E. Dickey <dickey@invisible-island.net>