tic.1: mdoc(7) conversion
[dragonfly.git] / usr.bin / tic / tic.1
CommitLineData
8331b1d2
JM
1.\"***************************************************************************
2.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
3.\" *
4.\" Permission is hereby granted, free of charge, to any person obtaining a *
5.\" copy of this software and associated documentation files (the *
6.\" "Software"), to deal in the Software without restriction, including *
7.\" without limitation the rights to use, copy, modify, merge, publish, *
8.\" distribute, distribute with modifications, sublicense, and/or sell *
9.\" copies of the Software, and to permit persons to whom the Software is *
10.\" furnished to do so, subject to the following conditions: *
11.\" *
12.\" The above copyright notice and this permission notice shall be included *
13.\" in all copies or substantial portions of the Software. *
14.\" *
15.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
16.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
17.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
18.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
19.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
20.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
21.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
22.\" *
23.\" Except as contained in this notice, the name(s) of the above copyright *
24.\" holders shall not be used in advertising or otherwise to promote the *
25.\" sale, use or other dealings in this Software without prior written *
26.\" authorization. *
27.\"***************************************************************************
28.\"
29.\" $Id: tic.1m,v 1.47 2010/12/04 18:38:55 tom Exp $
ff2cf2db
FF
30.Dd September 14, 2013
31.Dt TIC 1
32.Os
33.Sh NAME
34.Nm tic
35.Nd the terminfo entry-description compiler
36.Sh SYNOPSIS
37.Nm
38.Op Fl 1CGILNTUVacfgrstx
39.Op Fl e Ar names
40.Op Fl o Ar dir
41.Op Fl R Ar subset
42.Op Fl v Ns Op Ar n
43.Op Fl w Ns Op Ar n
44.Ar file
45.Sh DESCRIPTION
46The command
47.Nm
48translates a
49.Xr terminfo 5
50file from source format into compiled format.
51The compiled format is necessary for use with the library routines in
52.Xr ncurses 3 .
53.Pp
54The results are normally placed in the system terminfo directory
55.Pa /usr/share/terminfo .
8331b1d2 56There are two ways to change this behavior.
ff2cf2db 57.Pp
8331b1d2 58First, you may override the system default by setting the variable
ff2cf2db
FF
59.Ev TERMINFO
60in your shell environment to a valid (existing) directory name.
61.Pp
62Secondly, if
63.Nm
64cannot get access to
65.Pa /usr/share/terminfo
66or your
67.Ev TERMINFO
68directory, it looks for the directory
69.Pa $HOME/.terminfo ;
70if that directory exists, the entry is placed there.
71.Pp
72Libraries that read terminfo entries are expected to check for a
73.Ev TERMINFO
74directory first, look at
75.Pa $HOME/.terminfo
76if
77.Ev TERMINFO
78is not set, and finally look in
79.Pa /usr/share/terminfo .
80.Bl -tag -width ".Fl R subset"
81.It Fl 1
8331b1d2 82restricts the output to a single column
ff2cf2db
FF
83.It Fl a
84tells
85.Nm
86to retain commented-out capabilities rather than discarding them.
8331b1d2 87Capabilities are commented by prefixing them with a period.
ff2cf2db
FF
88This sets the
89.Fl x
90option, because it treats the commented-out entries as user-defined names.
8331b1d2
JM
91If the source is termcap, accept the 2-character names required by version 6.
92Otherwise these are ignored.
ff2cf2db 93.It Fl C
8331b1d2 94Force source translation to termcap format.
ff2cf2db
FF
95Capabilities that are not translatable are left in the entry under
96their terminfo names but commented out with two preceding dots.
97.It Fl c
98tells
99.Nm
100to only check
101.Ar file
102for errors, including syntax problems and bad use links.
103If you specify
104.Fl C
105.Pq Fl I
106with this option, the code will print warnings about entries which,
107after use resolution, are more than 1023 (4096) bytes long.
108Due to a fixed buffer length in older termcap libraries
109(and a documented limit in terminfo),
110these entries may cause core dumps.
111.It Fl e Ar names
8331b1d2
JM
112Limit writes and translations to the following comma-separated list of
113terminals.
114If any name or alias of a terminal matches one of the names in
115the list, the entry will be written or translated as normal.
116Otherwise no output will be generated for it.
117The option value is interpreted as a file containing the list if it
ff2cf2db
FF
118contains a
119.Sq / .
120Note: depending on how
121.Nm
122was compiled, this option may require
123.Fl I
124or
125.Fl C .
126.It Fl f
8331b1d2
JM
127Display complex terminfo strings which contain if/then/else/endif expressions
128indented for readability.
ff2cf2db 129.It Fl G
8331b1d2
JM
130Display constant literals in decimal form
131rather than their character equivalents.
ff2cf2db 132.It Fl g
8331b1d2
JM
133Display constant character literals in quoted form
134rather than their decimal equivalents.
ff2cf2db 135.It Fl I
8331b1d2 136Force source translation to terminfo format.
ff2cf2db 137.It Fl L
8331b1d2 138Force source translation to terminfo format
ff2cf2db
FF
139using the long C variable names listed in
140.In term.h
141.It Fl N
8331b1d2
JM
142Disable smart defaults.
143Normally, when translating from termcap to terminfo, the compiler makes
144a number of assumptions about the defaults of string capabilities
ff2cf2db
FF
145.Cm reset1_string ,
146.Cm carriage_return ,
147.Cm cursor_left ,
148.Cm cursor_down ,
149.Cm scroll_forward ,
150.Cm tab ,
151.Cm newline ,
152.Cm key_backspace ,
153.Cm key_left ,
154and
155.Cm key_down ,
156then attempts to use obsolete termcap capabilities to deduce correct values.
157It also normally suppresses output of obsolete termcap capabilities such as
158.Cm bs .
8331b1d2
JM
159This option forces a more literal translation that also preserves the
160obsolete capabilities.
ff2cf2db 161.It Fl o Ar dir
8331b1d2 162Write compiled entries to given directory.
ff2cf2db
FF
163Overrides the
164.Ev TERMINFO
165environment variable.
166.It Fl R Ar subset
8331b1d2 167Restrict output to a given subset.
ff2cf2db
FF
168This option is for use with archaic versions of terminfo like those on
169SVr1, Ultrix, or HP/UX that do not support the full set of
170SVR4/XSI Curses terminfo;
171and outright broken ports like AIX 3.x
8331b1d2 172that have their own extensions incompatible with SVr4/XSI.
ff2cf2db
FF
173Available subsets are
174.Dq SVr1 ,
175.Dq Ultrix ,
176.Dq HP ,
177.Dq BSD
178and
179.Dq AIX ;
180see
181.Xr terminfo 5
182for details.
183.It Fl r
8331b1d2
JM
184Force entry resolution (so there are no remaining tc capabilities) even
185when doing translation to termcap format.
186This may be needed if you are
187preparing a termcap file for a termcap library (such as GNU termcap through
ff2cf2db
FF
188version 1.3 or BSD termcap through
189.Bx 4.3 )
190that does not handle multiple tc capabilities per entry.
191.It Fl s
8331b1d2
JM
192Summarize the compile by showing the directory into which entries
193are written, and the number of entries which are compiled.
ff2cf2db 194.It Fl T
8331b1d2
JM
195eliminates size-restrictions on the generated text.
196This is mainly useful for testing and analysis, since the compiled
ff2cf2db
FF
197descriptions are limited (e.g. 1023 for termcap, 4096 for terminfo).
198.It Fl t
199tells
200.Nm
201to discard commented-out capabilities.
8331b1d2
JM
202Normally when translating from terminfo to termcap,
203untranslatable capabilities are commented-out.
ff2cf2db
FF
204.It Fl U
205tells
206.Nm
207to not post-process the data after parsing the source file.
8331b1d2
JM
208Normally, it infers data which is commonly missing in older terminfo data,
209or in termcaps.
ff2cf2db
FF
210.It Fl V
211reports the version of
212.Xr ncurses 3
213which was used in this program, and exits.
214.It Fl v Ns Op Ar n
8331b1d2 215specifies that (verbose) output be written to standard error trace
ff2cf2db
FF
216information showing
217.Nm Ns 's
218progress.
219The optional parameter
220.Ar n
221is a number from 1 to 10, inclusive,
8331b1d2 222indicating the desired level of detail of information.
ff2cf2db
FF
223If
224.Ar n
225is omitted, the default level is 1.
226If
227.Ar n
228is specified and greater than 1, the level of
8331b1d2 229detail is increased.
ff2cf2db 230.It Fl w Ns Op Ar n
8331b1d2
JM
231specifies the width of the output.
232The parameter is optional.
233If it is omitted, it defaults to 60.
ff2cf2db 234.It Fl x
8331b1d2 235Treat unknown capabilities as user-defined.
ff2cf2db
FF
236That is, if you supply a capability name which
237.Nm
238does not recognize, it will infer its type (boolean, number or string)
239from the syntax and make an extended table entry for that.
8331b1d2 240User-defined capability strings
ff2cf2db
FF
241whose name begins with
242.Sq k
243are treated as function keys.
244.Ar file
245contains one or more
246.Xr terminfo 5
247terminal descriptions in source format.
8331b1d2
JM
248Each description in the file
249describes the capabilities of a particular terminal.
ff2cf2db
FF
250.El
251.Pp
8331b1d2 252The debug flag levels are as follows:
ff2cf2db
FF
253.Bl -tag -width "1xxx"
254.It 1
8331b1d2 255Names of files created and linked
ff2cf2db
FF
256.It 2
257Information related to the
258.Dq use
259facility
260.It 3
8331b1d2 261Statistics from the hashing algorithm
ff2cf2db 262.It 5
8331b1d2 263String-table memory allocations
ff2cf2db 264.It 7
8331b1d2 265Entries into the string-table
ff2cf2db 266.It 8
8331b1d2 267List of tokens encountered by scanner
ff2cf2db 268.It 9
8331b1d2 269All values computed in construction of the hash table
ff2cf2db
FF
270.El
271.Pp
272If the debug level
273.Ar n
274is not given, it is taken to be one.
275.Pp
276All but one of the capabilities recognized by
277.Nm
278are documented in
279.Xr terminfo 5 .
280The exception is the
281.Cm use
282capability.
283.Pp
284When a
285.Cm use Ns Li = Ns Ar entry-name
286field is discovered in a terminal entry currently being compiled,
287.Nm
288reads in the binary from
289.Pa /usr/share/terminfo
290to complete the entry.
8331b1d2 291(Entries created from
ff2cf2db
FF
292.Ar file
293will be used first.
8331b1d2 294If the environment variable
ff2cf2db
FF
295.Ev TERMINFO
296is set, that directory is searched instead of
297.Pa /usr/share/terminfo . )
298.Nm
299duplicates the capabilities in
300.Ar entry-name
301for the current entry, with the exception of
8331b1d2 302those capabilities that explicitly are defined in the current entry.
ff2cf2db
FF
303.Pp
304When an entry, e.g.\&
305.Li entry_name_1 ,
306contains a
307.Cm use Ns Li = Ns Li entry_name_2
308field, any canceled capabilities in
309.Li entry_name_2
310must also appear in
311.Li entry_name_1
312before
313.Cm use Ns Li =
314for these capabilities to be canceled in
315.Li entry_name_1 .
316.Pp
317If the environment variable
318.Ev TERMINFO
319is set, the compiled results are placed there instead of
320.Pa /usr/share/terminfo .
321.Pp
8331b1d2 322Total compiled entries cannot exceed 4096 bytes.
ff2cf2db 323The name field cannot exceed 512 bytes.
8331b1d2
JM
324Terminal names exceeding the maximum alias length
325(32 characters on systems with long filenames, 14 characters otherwise)
ff2cf2db
FF
326will be truncated to the maximum alias length and a warning message
327will be printed.
328.Ss COMPATIBILITY
329There is some evidence that historic
330.Nm
331implementations treated description fields with no whitespace
332in them as additional aliases or short names.
333This
334.Nm
335does not do that, but it does warn when description fields may be
336treated that way and check them for dangerous characters.
337.Ss EXTENSIONS
338Unlike the stock SVr4
339.Nm
340command, this implementation can actually compile termcap sources.
8331b1d2
JM
341In fact, entries in terminfo and termcap syntax can
342be mixed in a single source file.
ff2cf2db
FF
343See
344.Xr terminfo 5
345for the list of termcap names taken to be equivalent to terminfo names.
346.Pp
347The SVr4 manual pages are not clear on the resolution rules for
348.Cm use
8331b1d2 349capabilities.
ff2cf2db
FF
350This implementation of
351.Nm
352will find
353.Cm use
354targets anywhere in the source file,
355or anywhere in the file tree rooted at
356.Ev TERMINFO
357(if it is defined), or in the user's
358.Pa $HOME/.terminfo
359directory (if it exists), or (finally) anywhere in the system's
360file tree of compiled entries.
361.Pp
362The error messages from this
363.Nm
364have the same format as GNU C error messages,
365and can be parsed by GNU Emacs's compile facility.
366.Pp
8331b1d2 367The
ff2cf2db
FF
368.Fl C ,
369.Fl G ,
370.Fl I ,
371.Fl N ,
372.Fl R ,
373.Fl T ,
374.Fl V ,
375.Fl a ,
376.Fl e ,
377.Fl f ,
378.Fl g ,
379.Fl o ,
380.Fl r ,
381.Fl s ,
382.Fl t
383and
384.Fl x
385options are not supported under SVr4.
386The SVr4
387.Fl c
388mode does not report bad use links.
389.Pp
8331b1d2 390System V does not compile entries to or read entries from your
ff2cf2db
FF
391.Pa $HOME/.terminfo
392directory unless
393.Ev TERMINFO
394is explicitly set to it.
395.Sh FILES
396.Bl -tag -width "Pa /usr/share/terminfo/?/*"
397.It Pa /usr/share/terminfo/?/*
8331b1d2 398Compiled terminal description database.
ff2cf2db
FF
399.El
400.Sh SEE ALSO
401.Xr ncurses 3 ,
402.Xr terminfo 5
403.Sh AUTHORS
404.An Eric S. Raymond Aq Mt esr@snark.thyrsus.com
405.An Thomas E. Dickey Aq Mt dickey@invisible-island.net