Annotation of src/usr.bin/tic/tic.1, Revision 1.12
1.12 ! millert 1: .\" $OpenBSD: tic.1,v 1.11 2000/07/24 04:06:12 millert Exp $
1.1 millert 2: .\"
3: .\"***************************************************************************
1.10 millert 4: .\" Copyright (c) 1998,1999,2000 Free Software Foundation, Inc. *
1.1 millert 5: .\" *
6: .\" Permission is hereby granted, free of charge, to any person obtaining a *
7: .\" copy of this software and associated documentation files (the *
8: .\" "Software"), to deal in the Software without restriction, including *
9: .\" without limitation the rights to use, copy, modify, merge, publish, *
10: .\" distribute, distribute with modifications, sublicense, and/or sell *
11: .\" copies of the Software, and to permit persons to whom the Software is *
12: .\" furnished to do so, subject to the following conditions: *
13: .\" *
14: .\" The above copyright notice and this permission notice shall be included *
15: .\" in all copies or substantial portions of the Software. *
16: .\" *
17: .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18: .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19: .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20: .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21: .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22: .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23: .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24: .\" *
25: .\" Except as contained in this notice, the name(s) of the above copyright *
26: .\" holders shall not be used in advertising or otherwise to promote the *
27: .\" sale, use or other dealings in this Software without prior written *
28: .\" authorization. *
29: .\"***************************************************************************
30: .\"
1.12 ! millert 31: .\" $From: tic.1m,v 1.29 2000/08/19 18:51:05 tom Exp $
1.1 millert 32: .TH tic 1 ""
33: .ds n 5
34: .ds d /usr/share/terminfo
35: .SH NAME
36: \fBtic\fR - the \fIterminfo\fR entry-description compiler
37: .SH SYNOPSIS
38: \fBtic\fR
1.3 millert 39: [\fB\-\
1.1 millert 40: 1\
41: C\
42: I\
43: N\
44: R\
45: T\
1.12 ! millert 46: V\
1.10 millert 47: a\
1.1 millert 48: c\
49: f\
50: r\
51: s\
1.9 millert 52: x\
1.1 millert 53: \fR]
54: [\fB-e\fR \fInames\fR]
55: [\fB-o\fR \fIdir\fR]
56: [\fB-v\fR[\fIn\fR]]
57: [\fB-w\fR[\fIn\fR]]
58: \fIfile\fR
59: .br
60: .SH DESCRIPTION
61: The command \fBtic\fR translates a \fBterminfo\fR file from source
62: format into compiled format. The compiled format is necessary for use with
63: the library routines in \fBcurses\fR(3).
64: .PP
65: The results are normally placed in the system terminfo
66: directory \fB\*d\fR. There are two ways to change this behavior.
67: .PP
68: First, you may override the system default by setting the variable
69: \fBTERMINFO\fR in your shell environment to a valid (existing) directory name.
70: .PP
71: Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO
72: directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory
73: exists, the entry is placed there.
74: .PP
75: Libraries that read terminfo entries are expected to check for a TERMINFO
76: directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and
77: finally look in \fI\*d\fR.
78: .TP
1.10 millert 79: \fB-a\fR
80: tells \fBtic\fP to retain commented-out capabilities rather than discarding
81: them. Capabilities are commented by prefixing them with a period.
82: This sets the \fB-x\fR option, because it treats the commented-out
83: entries as user-defined names.
84: .TP
1.1 millert 85: \fB-c\fR
1.10 millert 86: tells \fBtic\fP to only check \fIfile\fR for errors, including syntax problems and
1.1 millert 87: bad use links. If you specify \fB-C\fR (\fB-I\fR) with this option, the code
88: will print warnings about entries which, after use resolution, are more than
89: 1023 (4096) bytes long. Due to a fixed buffer length in older termcap
90: libraries (and a documented limit in terminfo), these entries may cause core
91: dumps.
92: .TP
93: \fB-v\fR\fIn\fR
94: specifies that (verbose) output be written to standard error trace
95: information showing \fBtic\fR's progress. The optional integer
96: \fIn\fR is a number from 1 to 10, inclusive, indicating the desired
97: level of detail of information. If \fIn\fR is omitted, the default
98: level is 1. If \fIn\fR is specified and greater than 1, the level of
99: detail is increased.
100: .TP
101: \fB-o\fR\fIdir\fR
102: Write compiled entries to given directory. Overrides the TERMINFO environment
103: variable.
104: .TP
105: \fB-w\fR\fIn\fR
106: specifies the width of the output.
107: .TP
108: \fB-1\fR
109: restricts the output to a single column
110: .TP
111: \fB-C\fR
112: Force source translation to termcap format. Note: this differs from the -C
113: option of \fIinfocmp\fR(1) in that it does not merely translate capability
114: names, but also translates terminfo strings to termcap format. Capabilities
115: that are not translatable are left in the entry under their terminfo names
116: but commented out with two preceding dots.
117: .TP
1.6 millert 118: \fB-G\fR
119: Display constant literals in decimal form
120: rather than their character equivalents.
121: .TP
1.1 millert 122: \fB-I\fR
123: Force source translation to terminfo format.
124: .TP
125: \fB-L\fR
126: Force source translation to terminfo format
127: using the long C variable names listed in <\fBterm.h\fR>
128: .TP
129: \fB-N\fR
1.7 aaron 130: Disable smart defaults.
131: Normally, when translating from termcap to terminfo, the compiler makes
1.1 millert 132: a number of assumptions about the defaults of string capabilities
1.7 aaron 133: \fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
1.1 millert 134: \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
135: \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
136: to use obsolete termcap capabilities to deduce correct values. It also
137: normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
138: This option forces a more literal translation that also preserves the
139: obsolete capabilities.
140: .TP
141: \fB-R\fR\fIsubset\fR
142: Restrict output to a given subset. This option is for use with archaic
143: versions of terminfo like those on SVr1, Ultrix, or HP/UX that don't support
144: the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
145: that have their own extensions incompatible with SVr4/XSI. Available subsets
146: are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
147: .TP
148: \fB-T\fR
149: eliminates size-restrictions on the generated text.
150: This is mainly useful for testing and analysis, since the compiled
151: descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
152: .TP
1.12 ! millert 153: \fB-V\fR
! 154: reports the version of ncurses which was used in this program, and exits.
! 155: .TP
1.1 millert 156: \fB-r\fR
157: Force entry resolution (so there are no remaining tc capabilities) even
158: when doing translation to termcap format. This may be needed if you are
159: preparing a termcap file for a termcap library (such as GNU termcap up
160: to version 1.3 or BSD termcap up to 4.3BSD) that doesn't handle multiple
161: tc capabilities per entry.
162: .TP
163: \fB-e\fR
164: Limit writes and translations to the following comma-separated list of
165: terminals.
166: If any name or alias of a terminal matches one of the names in
167: the list, the entry will be written or translated as normal.
168: Otherwise no output will be generated for it.
169: The option value is interpreted as a file containing the list if it
170: contains a '/'.
171: (Note: depending on how tic was compiled, this option may require -I or -C.)
172: .TP
173: \fB-f\fR
174: Display complex terminfo strings which contain if/then/else/endif expressions
175: indented for readability.
176: .TP
1.3 millert 177: \fB-g\fR
178: Display constant character literals in quoted form
179: rather than their decimal equivalents.
180: .TP
1.1 millert 181: \fB-s\fR
182: Summarize the compile by showing the directory into which entries
183: are written, and the number of entries which are compiled.
184: .TP
1.9 millert 185: \fB-x\fR
186: Treat unknown capabilities as user-defined.
1.10 millert 187: That is, if you supply a capability name which \fBtic\fP does not recognize,
188: it will infer its type (boolean, number or string) from the syntax and
189: make an extended table entry for that.
1.9 millert 190: .TP
1.1 millert 191: \fIfile\fR
192: contains one or more \fBterminfo\fR terminal descriptions in source
193: format [see \fBterminfo\fR(\*n)]. Each description in the file
194: describes the capabilities of a particular terminal.
195: .PP
196: The debug flag levels are as follows:
197: .TP
198: 1
199: Names of files created and linked
200: .TP
201: 2
202: Information related to the ``use'' facility
203: .TP
204: 3
205: Statistics from the hashing algorithm
206: .TP
207: 5
208: String-table memory allocations
209: .TP
210: 7
211: Entries into the string-table
212: .TP
213: 8
214: List of tokens encountered by scanner
215: .TP
216: 9
217: All values computed in construction of the hash table
218: .LP
219: If n is not given, it is taken to be one.
220: .PP
221: All but one of the capabilities recognized by \fBtic\fR are documented
222: in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability.
223:
224: When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a
225: terminal entry currently being compiled, \fBtic\fR reads in the binary
226: from \fB\*d\fR to complete the entry. (Entries created from
227: \fIfile\fR will be used first. If the environment variable
228: \fBTERMINFO\fR is set, that directory is searched instead of
229: \fB\*d\fR.) \fBtic\fR duplicates the capabilities in
230: \fIentry\fR-\fIname\fR for the current entry, with the exception of
231: those capabilities that explicitly are defined in the current entry.
232:
233: When an entry, e.g., \fBentry_name_1\fR, contains a
234: \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
235: capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
236: \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
237: canceled in \fBentry_name_1\fR.
238:
239: If the environment variable \fBTERMINFO\fR is set, the compiled
240: results are placed there instead of \fB\*d\fR.
241:
242: Total compiled entries cannot exceed 4096 bytes. The name field cannot
243: exceed 512 bytes. Terminal names exceeding the maximum alias length
244: (32 characters on systems with long filenames, 14 characters otherwise)
245: will be truncated to the maximum alias length and a warning message will be printed.
246: .SH COMPATIBILITY
247: There is some evidence that historic \fBtic\fR implementations treated
248: description fields with no whitespace in them as additional aliases or
249: short names. This \fBtic\fR does not do that, but it does warn when
250: description fields may be treated that way and check them for dangerous
251: characters.
252: .SH EXTENSIONS
253: Unlike the stock SVr4 \fBtic\fR command, this implementation can actually
254: compile termcap sources. In fact, entries in terminfo and termcap syntax can
255: be mixed in a single source file. See \fBterminfo\fR(\*n) for the list of
256: termcap names taken to be equivalent to terminfo names.
257:
258: The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
259: capabilities.
260: This implementation of \fBtic\fR will find \fBuse\fR targets anywhere
261: in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
262: \fBTERMINFO\fR is defined), or in the user's \fI$HOME/.terminfo\fR directory
263: (if it exists), or (finally) anywhere in the system's file tree of
264: compiled entries.
265:
266: The error messages from this \fBtic\fR have the same format as GNU C
267: error messages, and can be parsed by GNU Emacs's compile facility.
268:
1.3 millert 269: The
1.10 millert 270: \fB-C\fR,
1.6 millert 271: \fB-G\fR,
1.3 millert 272: \fB-I\fR,
273: \fB-N\fR,
274: \fB-R\fR,
1.10 millert 275: \fB-T\fR,
1.12 ! millert 276: \fB-V\fR,
1.10 millert 277: \fB-a\fR,
1.3 millert 278: \fB-e\fR,
279: \fB-f\fR,
280: \fB-g\fR,
1.10 millert 281: \fB-o\fR,
1.9 millert 282: \fB-r\fR,
283: \fB-s\fR and
284: \fB-x\fR
1.3 millert 285: options
1.1 millert 286: are not supported under SVr4.
287: The SVr4 -c mode does not report bad use links.
288:
289: System V does not compile entries to or read entries from your
290: \fI$HOME/.terminfo\fR directory unless TERMINFO is explicitly set to it.
291: .SH FILES
292: .TP 5
293: \fB\*d/?/*\fR
294: Compiled terminal description database.
295: .SH SEE ALSO
1.9 millert 296: \fBcaptoinfo\fR(1), \fBinfocmp\fR(1), \fBinfotocap\fR(1),
297: \fBcurses\fR(3), \fBterminfo\fR(\*n).
1.1 millert 298: .\"#
299: .\"# The following sets edit modes for GNU EMACS
300: .\"# Local Variables:
301: .\"# mode:nroff
302: .\"# fill-column:79
303: .\"# End: