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