Annotation of src/usr.bin/infocmp/infocmp.1tbl, Revision 1.3
1.1 millert 1: '\" t
1.3 ! millert 2: .\" $OpenBSD: infocmp.1tbl,v 1.2 1999/01/22 04:56:00 millert Exp $
1.1 millert 3: .\"
4: .\"***************************************************************************
5: .\" Copyright (c) 1998 Free Software Foundation, Inc. *
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.3 ! millert 32: .\" $From: infocmp.1m,v 1.20 1999/03/07 02:07:48 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.3 ! millert 39: \fBinfocmp\fR [\fB-dcGgnpILCuV1\fR] [\fB-v\fR \fIn\fR] [\fB-s d\fR| \fBi\fR| \fBl\fR| \fBc\fR]
1.1 millert 40: .br
41: [\fB-w\fR \fIwidth\fR] [\fB-A\fR \fIdirectory\fR] [\fB-B\fR \fIdirectory\fR] [\fItermname\fR...]
42: .SH DESCRIPTION
43: \fBinfocmp\fR can be used to compare a binary \fBterminfo\fR entry with other
44: terminfo entries, rewrite a \fBterminfo\fR description to take advantage of the
45: \fBuse=\fR terminfo field, or print out a \fBterminfo\fR description from the
46: binary file (\fBterm\fR) in a variety of formats. In all cases, the boolean
47: fields will be printed first, followed by the numeric fields, followed by the
48: string fields.
49: ..
50: .SS Default Options
51: If no options are specified and zero or one \fItermnames\fR are specified, the
52: \fB-I\fR option will be assumed. If more than one \fItermname\fR is specified,
53: the \fB-d\fR option will be assumed.
54: ..
55: .SS Comparison Options [-d] [-c] [-n]
56: \fBinfocmp\fR compares the \fBterminfo\fR description of the first terminal
57: \fItermname\fR with each of the descriptions given by the entries for the other
58: terminal's \fItermnames\fR. If a capability is defined for only one of the
59: terminals, the value returned will depend on the type of the capability:
60: \fBF\fR for boolean variables, \fB-1\fR for integer variables, and \fBNULL\fR
61: for string variables.
62:
63: The \fB-d\fR option produces a list of each capability that is different
64: between two entries. This option is useful to show the difference between two
65: entries, created by different people, for the same or similar terminals.
66:
67: The \fB-c\fR option produces a list of each capability that is common between
68: two entries. Capabilities that are not set are ignored. This option can be
69: used as a quick check to see if the \fB-u\fR option is worth using.
70:
71: The \fB-n\fR option produces a list of each capability that is in neither
72: entry. If no \fItermnames\fR are given, the environment variable \fBTERM\fR
73: will be used for both of the \fItermnames\fR. This can be used as a quick
74: check to see if anything was left out of a description.
75: ..
76: .SS Source Listing Options [-I] [-L] [-C] [-r]
77: The \fB-I\fR, \fB-L\fR, and \fB-C\fR options will produce a source listing for
78: each terminal named.
79:
80: .TS
81: center tab(/) ;
82: l l .
83: \fB-I\fR/use the \fBterminfo\fR names
84: \fB-L\fR/use the long C variable name listed in <\fBterm.h\fR>
85: \fB-C\fR/use the \fBtermcap\fR names
86: \fB-r\fR/when using \fB-C\fR, put out all capabilities in \fBtermcap\fR form
87: .TE
88:
89: If no \fItermnames\fR are given, the environment variable \fBTERM\fR will be
90: used for the terminal name.
91:
92: The source produced by the \fB-C\fR option may be used directly as a
93: \fBtermcap\fR entry, but not all parameterized strings can be changed to
94: the \fBtermcap\fR format. \fBinfocmp\fR will attempt to convert most of the
95: parameterized information, and anything not converted will be plainly marked in
96: the output and commented out. These should be edited by hand.
97:
98: All padding information for strings will be collected together and placed
99: at the beginning of the string where \fBtermcap\fR expects it. Mandatory
100: padding (padding information with a trailing '/') will become optional.
101:
102: All \fBtermcap\fR variables no longer supported by \fBterminfo\fR, but which
103: are derivable from other \fBterminfo\fR variables, will be output. Not all
104: \fBterminfo\fR capabilities will be translated; only those variables which were
105: part of \fBtermcap\fR will normally be output. Specifying the \fB-r\fR option
106: will take off this restriction, allowing all capabilities to be output in
107: \fItermcap\fR form.
108:
109: Note that because padding is collected to the beginning of the capability, not
110: all capabilities are output. Mandatory padding is not supported. Because
111: \fBtermcap\fR strings are not as flexible, it is not always possible to convert
112: a \fBterminfo\fR string capability into an equivalent \fBtermcap\fR format. A
113: subsequent conversion of the \fBtermcap\fR file back into \fBterminfo\fR format
114: will not necessarily reproduce the original \fBterminfo\fR
115: source.
116:
117: Some common \fBterminfo\fR parameter sequences, their \fBtermcap\fR
118: equivalents, and some terminal types which commonly have such sequences, are:
119:
120: .TS
121: center tab(/) ;
122: l c l
123: l l l.
124: \fBterminfo/termcap\fR/Representative Terminals
125: =
126: \fB%p1%c/%.\fR/adm
127: \fB%p1%d/%d\fR/hp, ANSI standard, vt100
128: \fB%p1%'x'%+%c/%+x\fR/concept
129: \fB%i/%i\fRq/ANSI standard, vt100
130: \fB%p1%?%'x'%>%t%p1%'y'%+%;/%>xy\fR/concept
131: \fB%p2\fR is printed before \fB%p1/%r\fR/hp
132: .TE
133: .SS Use= Option [-u]
134: The \fB-u\fR option produces a \fBterminfo\fR source description of the first
135: terminal \fItermname\fR which is relative to the sum of the descriptions given
136: by the entries for the other terminals \fItermnames\fR. It does this by
137: analyzing the differences between the first \fItermname\fR and the other
138: \fItermnames\fR and producing a description with \fBuse=\fR fields for the
139: other terminals. In this manner, it is possible to retrofit generic terminfo
140: entries into a terminal's description. Or, if two similar terminals exist, but
141: were coded at different times or by different people so that each description
142: is a full description, using \fBinfocmp\fR will show what can be done to change
143: one description to be relative to the other.
144:
145: A capability will get printed with an at-sign (@) if it no longer exists in the
146: first \fItermname\fR, but one of the other \fItermname\fR entries contains a
147: value for it. A capability's value gets printed if the value in the first
148: \fItermname\fR is not found in any of the other \fItermname\fR entries, or if
149: the first of the other \fItermname\fR entries that has this capability gives a
150: different value for the capability than that in the first \fItermname\fR.
151:
152: The order of the other \fItermname\fR entries is significant. Since the
153: terminfo compiler \fBtic\fR does a left-to-right scan of the capabilities,
154: specifying two \fBuse=\fR entries that contain differing entries for the same
155: capabilities will produce different results depending on the order that the
156: entries are given in. \fBinfocmp\fR will flag any such inconsistencies between
157: the other \fItermname\fR entries as they are found.
158:
159: Alternatively, specifying a capability \fIafter\fR a \fBuse=\fR entry that
160: contains that capability will cause the second specification to be ignored.
161: Using \fBinfocmp\fR to recreate a description can be a useful check to make
162: sure that everything was specified correctly in the original source
163: description.
164:
165: Another error that does not cause incorrect compiled files, but will slow down
166: the compilation time, is specifying extra \fBuse=\fR fields that are
167: superfluous. \fBinfocmp\fR will flag any other \fItermname use=\fR fields that
168: were not needed.
169: ..
170: .SS Changing Databases [-A \fIdirectory\fR] [-B \fIdirectory\fR]
171: The location of the compiled \fBterminfo\fR database is taken from the
172: environment variable \fBTERMINFO\fR . If the variable is not defined, or the
173: terminal is not found in that location, the system \fBterminfo\fR database,
174: in \fB/usr/share/terminfo\fR, will be used. The options \fB-A\fR
175: and \fB-B\fR may be used to override this location. The \fB-A\fR option will
176: set \fBTERMINFO\fR for the first \fItermname\fR and the \fB-B\fR option will
177: set \fBTERMINFO\fR for the other \fItermnames\fR. With this, it is possible to
178: compare descriptions for a terminal with the same name located in two different
179: databases. This is useful for comparing descriptions for the same terminal
180: created by different people.
181: ..
182: .SS Other Options [-s d|i|l|c] [-1FTVefip] [-Rsubset] [-v \fIn\fR] [-w \fIwidth\fR]
183: The \fB-s\fR option sorts the fields within each type according to the argument
184: below:
185: ..
186: .TP 5
187: \fBd\fR
188: leave fields in the order that they are stored in the \fIterminfo\fR database.
189: .TP 5
190: \fBi\fR
191: sort by \fIterminfo\fR name.
192: .TP 5
193: \fBl\fR
194: sort by the long C variable name.
195: .TP 5
196: \fBc\fR
197: sort by the \fItermcap\fR name.
198:
199: If the \fB-s\fR option is not given, the fields printed out will be
200: sorted alphabetically by the \fBterminfo\fR name within each type,
201: except in the case of the \fB-C\fR or the \fB-L\fR options, which cause the
202: sorting to be done by the \fBtermcap\fR name or the long C variable
203: name, respectively.
204: .TP 5
205: \fB-1\fR
206: causes the fields to be printed out one to a line. Otherwise,
207: the fields will be printed several to a line to a maximum width
208: of 60 characters.
209: .TP 5
210: \fB-F\fR
211: compare terminfo files. This assumes that two following arguments are
212: filenames. The files are searched for pairwise matches between
213: entries, with two entries considered to match if any of their names do.
214: The report printed to standard output lists entries with no matches in
215: the other file, and entries with more than one match. For entries
216: with exactly one match it includes a difference report.
1.3 ! millert 217: .TP
! 218: \fB-G\fR
! 219: Display constant literals in decimal form
! 220: rather than their character equivalents.
1.1 millert 221: .TP 5
222: \fB-R\fR\fIsubset\fR
223: Restrict output to a given subset. This option is for use with archaic
224: versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support
225: the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX
226: that have their own extensions incompatible with SVr4/XSI. Available terminfo
227: subsets are "SVr1", "Ultrix", "HP", and "AIX"; see \fBterminfo\fR(\*n) for
228: details. You can also choose the subset "BSD" which selects only capabilities
229: with termcap equivalents recognized by 4.4BSD.
230: .TP 5
231: \fB-T\fR
232: eliminates size-restrictions on the generated text.
233: This is mainly useful for testing and analysis, since the compiled
234: descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
235: .TP 5
236: \fB-V\fR
237: prints out the version of the program in use on standard error and exits.
238: .TP 5
239: \fB-e\fR
240: Dump the capabilities of the given terminal as a C initializer for a
241: TERMTYPE structure (the terminal capability structure in the \fB<term.h>\fR).
242: This option is useful for preparing versions of the curses library hardwired
243: for a given terminal type.
244: .TP
245: \fB-f\fR
246: Display complex terminfo strings which contain if/then/else/endif expressions
247: indented for readability.
248: .TP
249: \fB-g\fR
250: Display constant character literals in quoted form
251: rather than their decimal equivalents.
252: .TP 5
253: \fB-i\fR
254: Analyze the initialization (\fBis1\fR, \fBis2\fR, \fBis3\fR), and reset
255: (\fBrs1\fR, \fBrs2\fR, \fBrs3\fR), strings in the entry. For each string, the
256: code tries to analyze it into actions in terms of the other capabilities in the
257: entry, certain X3.64/ISO 6429/ECMA-48 capabilities, and certain DEC VT-series
258: private modes (the set of recognized special sequences has been selected for
259: completeness over the existing terminfo database). Each report line consists
260: of the capability name, followed by a colon and space, followed by a printable
261: expansion of the capability string with sections matching recognized actions
262: translated into {}-bracketed descriptions. Here is a list of the DEC/ANSI
263: special sequences recognized:
264:
265: .TS
266: center tab(/) ;
267: l l
268: l l.
269: Action/Meaning
270: =
271: RIS/full reset
272: SC/save cursor
273: RC/restore cursor
274: LL/home-down
275: RSR/reset scroll region
276:
277: ISO DEC G0/enable DEC graphics for G0
278: ISO UK G0/enable UK chars for G0
279: ISO US G0/enable US chars for G0
280: ISO DEC G1/enable DEC graphics for G1
281: ISO UK G1/enable UK chars for G1
282: ISO US G1/enable US chars for G1
283:
284: DECPAM/application keypad mode
285: DECPNM/normal keypad mode
286: DECANSI/enter ANSI mode
287:
288: DEC[+-]CKM/application cursor keys
289: DEC[+-]ANM/set VT52 mode
290: DEC[+-]COLM/132-column mode
291: DEC[+-]SCLM/smooth scroll
292: DEC[+-]SCNM/reverse video mode
293: DEC[+-]OM/origin mode
294: DEC[+-]AWM/wraparound mode
295: DEC[+-]ARM/auto-repeat mode
296: .TE
297: .sp
298: It also recognizes a SGR action corresponding to ANSI/ISO 6429/ECMA Set
299: Graphics Rendition, with the values NORMAL, BOLD, UNDERLINE, BLINK, and
300: REVERSE. All but NORMAL may be prefixed with `+' (turn on) or `-' (turn off).
301:
302: An SGR0 designates an empty highlight sequence (equivalent to {SGR:NORMAL}).
303: .TP 5
304: \fB-p\fR
305: Ignore padding specifications when comparing strings.
306: .TP 5
307: \fB-v\fR \fIn\fR
308: prints out tracing information on standard error as the program runs.
309: Higher values of n induce greater verbosity.
310: .TP 5
311: \fB-w\fR \fIwidth\fR
312: changes the output to \fIwidth\fR characters.
313: ..
314: .SH FILES
315: .TP 20
316: \*d
317: Compiled terminal description database.
318: ..
319: .SH EXTENSIONS
320: The
321: \fB-F\fR,
1.3 ! millert 322: \fB-G\fR,
1.1 millert 323: \fB-R\fR,
324: \fB-T\fR,
325: \fB-e\fR,
326: \fB-f\fR,
327: \fB-g\fR,
328: \fB-i\fR, and
329: \fB-p\fR
330: options are not supported in SVr4 curses.
331:
332: The \fB-r\fR option's notion of `termcap' capabilities is System V Release 4's.
333: Actual BSD curses versions will have a more restricted set. To see only the
334: 4.4BSD set, use -r -RBSD.
335: .SH SEE ALSO
1.2 millert 336: \fBcaptoinfo\fR(1), \fBtic\fR(1),
1.1 millert 337: \fBcurses\fR(3), \fBterminfo\fR(\*n).
338: .SH AUTHOR
339: Eric S. Raymond <esr@snark.thyrsus.com>
1.3 ! millert 340: and
! 341: Thomas E. Dickey <dickey@clark.net>
1.1 millert 342: .\"#
343: .\"# The following sets edit modes for GNU EMACS
344: .\"# Local Variables:
345: .\"# mode:nroff
346: .\"# fill-column:79
347: .\"# End: