man/infocmp.1m

   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.60 2017/01/14 19:55:27 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 \fB@INFOCMP@\fP 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 \fB@INFOCMP@\fP 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 .IP
 480 The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
 481 indicating the desired level of detail of information.
 482 If ncurses is built without tracing support, the optional parameter is ignored.
 483 .TP
 484 \fB\-W\fR
 485 By itself, the \fB\-w\fP option will not force long strings to be wrapped.
 486 Use the \fB\-W\fP option to do this.
 487 .TP 5
 488 \fB\-w\fR \fIwidth\fR
 489 changes the output to \fIwidth\fR characters.
 490 .TP
 491 \fB\-x\fR
 492 print information for user-defined capabilities.
 493 These are extensions to the terminfo repertoire which can be loaded
 494 using the \fB\-x\fR option of \fB@TIC@\fP.
 495 .SH FILES
 496 .TP 20
 497 \*d
 498 Compiled terminal description database.
 499 .SH EXTENSIONS
 500 The
 501 \fB\-0\fR,
 502 \fB\-1\fR,
 503 \fB\-E\fR,
 504 \fB\-F\fR,
 505 \fB\-G\fR,
 506 \fB\-R\fR,
 507 \fB\-T\fR,
 508 \fB\-V\fR,
 509 \fB\-a\fR,
 510 \fB\-e\fR,
 511 \fB\-f\fR,
 512 \fB\-g\fR,
 513 \fB\-i\fR,
 514 \fB\-l\fR,
 515 \fB\-p\fR,
 516 \fB\-q\fR and
 517 \fB\-t\fR
 518 options are not supported in SVr4 curses.
 519 .PP
 520 The \fB\-r\fR option's notion of `termcap' capabilities is System V Release 4's.
 521 Actual BSD curses versions will have a more restricted set.
 522 To see only the
 523 4.4BSD set, use \fB\-r\fR \fB\-RBSD\fR.
 524 .SH BUGS
 525 The \fB\-F\fR option of \fB@INFOCMP@\fR(1M) should be a \fB@TOE@\fR(1M) mode.
 526 .SH SEE ALSO
 527 \fB@CAPTOINFO@\fR(1M),
 528 \fB@INFOTOCAP@\fR(1M),
 529 \fB@TIC@\fR(1M),
 530 \fB@TOE@\fR(1M),
 531 \fBcurses\fR(3X),
 532 \fBterminfo\fR(\*n).
 533 .sp
 534 http://invisible-island.net/ncurses/tctest.html
 535 .PP
 536 This describes \fBncurses\fR
 537 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
 538 .SH AUTHOR
 539 Eric S. Raymond <esr@snark.thyrsus.com>
 540 and
 541 .br
 542 Thomas E. Dickey <dickey@invisible-island.net>