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