diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/tic.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/tic.1 | 601 |
1 files changed, 601 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/tic.1 b/upstream/debian-bookworm/man1/tic.1 new file mode 100644 index 00000000..5efe3491 --- /dev/null +++ b/upstream/debian-bookworm/man1/tic.1 @@ -0,0 +1,601 @@ +.\"*************************************************************************** +.\" Copyright 2018-2021,2022 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: tic.1m,v 1.84 2022/09/17 19:01:24 tom Exp $ +.TH tic 1 "" +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.ds n 5 +.ds d /etc/terminfo +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fBtic\fP \- the \fIterminfo\fP entry-description compiler +.SH SYNOPSIS +\fBtic\fP +[\fB\-\ +0\ +1\ +C\ +D\ +G\ +I\ +K\ +L\ +N\ +T\ +U\ +V\ +W\ +a\ +c\ +f\ +g\ +q\ +r\ +s\ +t\ +x\ +\fP] +[\fB\-e\fP \fInames\fP] +[\fB\-o\fP \fIdir\fP] +[\fB\-Q\fP[\fIn\fP]] +[\fB\-R\fP \fIsubset\fP] +[\fB\-v\fP[\fIn\fP]] +[\fB\-w\fP[\fIn\fP]] +\fIfile\fP +.br +.SH DESCRIPTION +The \fBtic\fP command translates a \fBterminfo\fP file from source +format into compiled format. +The compiled format is necessary for use with +the library routines in \fBncurses\fP(3NCURSES). +.PP +As described in \fBterm\fP(\*n), the database may be either a directory +tree (one file per terminal entry) or a hashed database (one record per entry). +The \fBtic\fP command writes only one type of entry, +depending on how it was built: +.bP +For directory trees, the top-level directory, e.g., /usr/share/terminfo, +specifies the location of the database. +.bP +For hashed databases, a filename is needed. +If the given file is not found by that name, +but can be found by adding the suffix ".db", +then that is used. +.IP +The default name for the hashed database is the same as the +default directory name (only adding a ".db" suffix). +.PP +In either case (directory or hashed database), +\fBtic\fP will create the container if it does not exist. +For a directory, this would be the \*(``terminfo\*('' leaf, +versus a "terminfo.db" file. +.PP +The results are normally placed in the system terminfo database \fB\*d\fP. +The compiled terminal description can be placed +in a different terminfo database. +There are two ways to achieve this: +.bP +First, you may override the system default either by +using the \fB\-o\fP option, +or by setting the variable \fBTERMINFO\fP +in your shell environment to a valid database location. +.bP +Secondly, if \fBtic\fP cannot write in \fI\*d\fP +or the location specified using your TERMINFO variable, +it looks for the directory \fI$HOME/.terminfo\fP +(or hashed database \fI$HOME/.terminfo.db)\fP; +if that location exists, the entry is placed there. +.PP +Libraries that read terminfo entries are expected to check in succession +.bP +a location specified with the TERMINFO environment variable, +.bP +\fI$HOME/.terminfo\fP, +.bP +directories listed in the TERMINFO_DIRS environment variable, +.bP +a compiled-in list of directories (no default value), and +.bP +the system terminfo database (\fI\*d\fP). +.SS ALIASES +.PP +This is the same program as infotocap and captoinfo; +usually those are linked to, or copied from this program: +.bP +When invoked as infotocap, tic sets the \fB\-I\fP option. +.bP +When invoked as captoinfo, tic sets the \fB\-C\fP option. +.SS OPTIONS +.TP +\fB\-0\fP +restricts the output to a single line +.TP +\fB\-1\fP +restricts the output to a single column +.TP +\fB\-a\fP +tells \fBtic\fP to retain commented-out capabilities rather than discarding +them. +Capabilities are commented by prefixing them with a period. +This sets the \fB\-x\fP option, because it treats the commented-out +entries as user-defined names. +If the source is termcap, accept the 2-character names required by version 6. +Otherwise these are ignored. +.TP +\fB\-C\fP +Force source translation to termcap format. +Note: this differs from the \fB\-C\fP +option of \fBinfocmp\fP(1) in that it does not merely translate capability +names, but also translates terminfo strings to termcap format. +Capabilities +that are not translatable are left in the entry under their terminfo names +but commented out with two preceding dots. +The actual format used incorporates some improvements for escaped characters +from terminfo format. +For a stricter BSD-compatible translation, add the \fB\-K\fP option. +.IP +If this is combined with \fB\-c\fP, \fBtic\fP makes additional checks +to report cases where the terminfo values do not have an exact equivalent +in termcap form. +For example: +.RS +.bP +\fBsgr\fP usually will not convert, because termcap lacks the ability to +work with more than two parameters, and because termcap lacks many of +the arithmetic/logical operators used in terminfo. +.bP +capabilities with more than one delay or with delays before the end of +the string will not convert completely. +.RE +.TP +\fB\-c\fP +tells \fBtic\fP to only check \fIfile\fP for errors, +including syntax problems and bad use-links. +If you specify \fB\-C\fP (\fB\-I\fP) with this option, the code +will print warnings about entries which, after use resolution, are more than +1023 (4096) bytes long. +Due to a fixed buffer length in older termcap libraries, +as well as buggy checking for the buffer length +(and a documented limit in terminfo), +these entries may cause core +dumps with other implementations. +.IP +\fBtic\fP checks string capabilities to ensure that those with parameters +will be valid expressions. +It does this check only for the predefined string capabilities; +those which are defined with the \fB\-x\fP option are ignored. +.TP +\fB\-D\fP +tells \fBtic\fP to print the database locations that it knows about, and exit. +The first location shown is the one to which it would write compiled +terminal descriptions. +If \fBtic\fP is not able to find a writable database location +according to the rules summarized above, +it will print a diagnostic and exit with an error rather than +printing a list of database locations. +.TP +\fB\-e \fInames\fR +Limit writes and translations to the following comma-separated list of +terminals. +If any name or alias of a terminal matches one of the names in +the list, the entry will be written or translated as normal. +Otherwise no output will be generated for it. +The option value is interpreted as a file containing the list if it +contains a '/'. +(Note: depending on how tic was compiled, +this option may require \fB\-I\fP or \fB\-C\fP.) +.TP +\fB\-f\fP +Display complex terminfo strings which contain if/then/else/endif expressions +indented for readability. +.TP +\fB\-G\fP +Display constant literals in decimal form +rather than their character equivalents. +.TP +\fB\-g\fP +Display constant character literals in quoted form +rather than their decimal equivalents. +.TP +\fB\-I\fP +Force source translation to terminfo format. +.TP +\fB\-K\fP +Suppress some longstanding ncurses extensions to termcap format, +e.g., "\\s" for space. +.TP +\fB\-L\fP +Force source translation to terminfo format +using the long C variable names listed in <\fBterm.h\fP> +.TP +\fB\-N\fP +Disable smart defaults. +Normally, when translating from termcap to terminfo, the compiler makes +a number of assumptions about the defaults of string capabilities +\fBreset1_string\fP, \fBcarriage_return\fP, \fBcursor_left\fP, +\fBcursor_down\fP, \fBscroll_forward\fP, \fBtab\fP, \fBnewline\fP, +\fBkey_backspace\fP, \fBkey_left\fP, and \fBkey_down\fP, then attempts +to use obsolete termcap capabilities to deduce correct values. +It also +normally suppresses output of obsolete termcap capabilities such as \fBbs\fP. +This option forces a more literal translation that also preserves the +obsolete capabilities. +.TP +\fB\-o\fIdir\fR +Write compiled entries to given database location. +Overrides the TERMINFO environment variable. +.TP +\fB\-Q\fIn\fR +Rather than show source in terminfo (text) format, +print the compiled (binary) format in hexadecimal or base64 form, +depending on the option's value: +.RS 8 +.TP 3 +1 +hexadecimal +.TP 3 +2 +base64 +.TP 3 +3 +hexadecimal and base64 +.RE +.TP +\fB\-q\fP +Suppress comments and blank lines when showing translated source. +.TP +\fB\-R\fIsubset\fR +Restrict output to a given subset. +This option is for use with archaic +versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support +the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x +that have their own extensions incompatible with SVr4/XSI. +Available subsets +are \*(``SVr1\*('', \*(``Ultrix\*('', \*(``HP\*('', \*(``BSD\*('' and \*(``AIX\*(''; +see \fBterminfo\fP(\*n) for details. +.TP +\fB\-r\fP +Force entry resolution (so there are no remaining tc capabilities) even +when doing translation to termcap format. +This may be needed if you are +preparing a termcap file for a termcap library (such as GNU termcap through +version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple +tc capabilities per entry. +.TP +\fB\-s\fP +Summarize the compile by showing the database location into which entries +are written, and the number of entries which are compiled. +.TP +\fB\-T\fP +eliminates size-restrictions on the generated text. +This is mainly useful for testing and analysis, since the compiled +descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). +.TP +\fB\-t\fP +tells \fBtic\fP to discard commented-out capabilities. +Normally when translating from terminfo to termcap, +untranslatable capabilities are commented-out. +.TP 5 +\fB\-U\fP +tells \fBtic\fP to not post-process the data after parsing the source file. +Normally, it infers data which is commonly missing in older terminfo data, +or in termcaps. +.TP +\fB\-V\fP +reports the version of ncurses which was used in this program, and exits. +.TP +\fB\-v\fIn\fR +specifies that (verbose) output be written to standard error trace +information showing \fBtic\fP's progress. +.IP +The optional parameter \fIn\fP is a number from 1 to 9, inclusive, +indicating the desired level of detail of information. +.RS +.bP +If ncurses is built without tracing support, the optional parameter is ignored. +.bP +If \fIn\fP is omitted, the default level is 1. +.bP +If \fIn\fP is specified and greater than 1, the level of +detail is increased, and the output is written (with tracing information) +to the \*(``trace\*('' file. +.RE +.RS +.PP +The debug flag levels are as follows: +.TP 4 +1 +Names of files created and linked +.TP +2 +Information related to the \*(``use\*('' facility +.TP +3 +Statistics from the hashing algorithm +.TP +4 +Details of extended capabilities +.TP +5 +(unused) +.TP +6 +(unused) +.TP +7 +Entries into the string-table +.TP +8 +List of tokens encountered by scanner +.TP +9 +All values computed in construction of the hash table +.RE +.TP +\fB\-W\fP +By itself, the \fB\-w\fP option will not force long strings to be wrapped. +Use the \fB\-W\fP option to do this. +.IP +If you specify both \fB\-f\fP and \fB\-W\fP options, +the latter is ignored when \fB\-f\fP has already split the line. +.TP +\fB\-w\fIn\fR +specifies the width of the output. +The parameter is optional. +If it is omitted, it defaults to 60. +.TP +\fB\-x\fP +Treat unknown capabilities as user-defined (see \fBuser_caps(\*n)\fP). +That is, if you supply a capability name which \fBtic\fP does not recognize, +it will infer its type (boolean, number or string) from the syntax and +make an extended table entry for that. +User-defined capability strings +whose name begins with \*(``k\*('' are treated as function keys. +.SS PARAMETERS +.TP +\fIfile\fP +contains one or more \fBterminfo\fP terminal descriptions in source +format [see \fBterminfo\fP(\*n)]. +Each description in the file +describes the capabilities of a particular terminal. +.IP +If \fIfile\fP is \*(``-\*('', then the data is read from the standard input. +The \fIfile\fP parameter may also be the path of a character-device. +.SS PROCESSING +.PP +All but one of the capabilities recognized by \fBtic\fP are documented +in \fBterminfo\fP(\*n). +The exception is the \fBuse\fP capability. +.PP +When a \fBuse\fP=\fIentry\fP\-\fIname\fP field is discovered in a +terminal entry currently being compiled, \fBtic\fP reads in the binary +from \fB\*d\fP to complete the entry. +(Entries created from +\fIfile\fP will be used first. +\fBtic\fP duplicates the capabilities in +\fIentry\fP\-\fIname\fP for the current entry, with the exception of +those capabilities that explicitly are defined in the current entry. +.PP +When an entry, e.g., \fBentry_name_1\fP, contains a +\fBuse=\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled +capabilities in \fIentry\fR_\fIname\fR_\fI2\fP must also appear in +\fBentry_name_1\fP before \fBuse=\fP for these capabilities to be +canceled in \fBentry_name_1\fP. +.PP +Total compiled entries cannot exceed 4096 bytes. +The name field cannot +exceed 512 bytes. +Terminal names exceeding the maximum alias length +(32 characters on systems with long filenames, 14 characters otherwise) +will be truncated to the maximum alias length +and a warning message will be printed. +.SH HISTORY +.PP +System V Release 2 provided a \fBtic\fP utility. +It accepted a single option: \fB\-v\fP (optionally followed by a number). +According to Ross Ridge's comment in \fImytinfo\fP, +this version of \fBtic\fP was +unable to represent cancelled capabilities. +.PP +System V Release 3 provided a different \fBtic\fP utility, +written by Pavel Curtis, +(originally named \*(``compile\*('' in \fIpcurses\fP). +This added an option \fB\-c\fP to check the file for +errors, with the caveat that errors in \*(``use=\*('' links +would not be reported. +System V Release 3 documented a few warning messages which +did not appear in \fIpcurses\fP. +While the program itself was changed little as development +continued with System V Release 4, +the table of capabilities grew from 180 (\fIpcurses\fP) to 464 (Solaris). +.PP +In early development of ncurses (1993), +Zeyd Ben-Halim used the table from \fImytinfo\fP to +extend the \fIpcurses\fP table to 469 capabilities +(456 matched SVr4, 8 were only in SVr4, 13 were not in SVr4). +Of those 13, 11 were ultimately discarded +(perhaps to match the draft of X/Open Curses). +The exceptions were +\fBmemory_lock_above\fP and +\fBmemory_unlock\fP (see \fBuser_caps\fP(5)). +.PP +Eric Raymond incorporated parts of \fImytinfo\fP into ncurses +to implement the termcap-to-terminfo source conversion, +and extended that to begin development of +the corresponding terminfo-to-termcap source conversion, +Thomas Dickey completed that development over the course of several years. +.PP +In 1999, Thomas Dickey added the \fB\-x\fP option +to support user-defined capabilities. +.PP +In 2010, Roy Marples provided a \fBtic\fP program +and terminfo library for NetBSD. +That implementation adapts several features from ncurses, +including \fBtic\fP's \fB\-x\fP option. +.PP +The \fB\-c\fP option tells \fBtic\fP to check for problems in the +terminfo source file. +Continued development provides additional checks: +.bP +\fIpcurses\fP had 8 warnings +.bP +ncurses in 1996 had 16 warnings +.bP +Solaris (SVr4) curses has 28 warnings +.bP +NetBSD tic in 2019 has 19 warnings. +.bP +ncurses in 2019 has 96 warnings +.PP +The checking done in ncurses' \fBtic\fP helps with the conversion to +termcap, as well as pointing out errors and inconsistencies. +It is also used to ensure consistency with the user-defined capabilities. +There are 527 distinct capabilities in ncurses' terminal database; +128 of those are user-defined. +.SH PORTABILITY +.PP +X/Open Curses, Issue 7 (2009) provides a brief description of \fBtic\fP. +It lists one option: \fB\-c\fP. +The omission of \fB\-v\fP is unexpected. +The change history states that the description is derived from True64 UNIX. +According to its manual pages, that system also supported the \fB\-v\fP option. +.PP +Shortly after Issue 7 was released, Tru64 was discontinued. +As of 2019, the surviving implementations of \fBtic\fP +are SVr4 (AIX, HP-UX and Solaris), +ncurses +and NetBSD curses. +The SVr4 \fBtic\fP programs all support the \fB\-v\fP option. +The NetBSD \fBtic\fP program follows X/Open's documentation, +omitting the \fB\-v\fP option. +.PP +The X/Open rationale states that some implementations of \fBtic\fP +read terminal descriptions from the standard input if the \fIfile\fP +parameter is omitted. +None of these implementations do that. +Further, it comments that some may choose to read from \*(''./terminfo.src\*('' +but that is obsolescent behavior from SVr2, +and is not (for example) a documented feature of SVr3. +.SS COMPATIBILITY +There is some evidence that historic \fBtic\fP implementations treated +description fields with no whitespace in them as additional aliases or +short names. +This \fBtic\fP does not do that, but it does warn when +description fields may be treated that way and check them for dangerous +characters. +.SS EXTENSIONS +Unlike the SVr4 \fBtic\fP command, this implementation can actually +compile termcap sources. +In fact, entries in terminfo and termcap syntax can +be mixed in a single source file. +See \fBterminfo\fP(\*n) for the list of +termcap names taken to be equivalent to terminfo names. +.PP +The SVr4 manual pages are not clear on the resolution rules for \fBuse\fP +capabilities. +This implementation of \fBtic\fP will find \fBuse\fP targets anywhere +in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fP (if +\fBTERMINFO\fP is defined), +or in the user's \fI$HOME/.terminfo\fP database +(if it exists), +or (finally) anywhere in the system's file tree of +compiled entries. +.PP +The error messages from this \fBtic\fP have the same format as GNU C +error messages, and can be parsed by GNU Emacs's compile facility. +.PP +Aside from \fB\-c\fP and \fB\-v\fP, options are not portable: +.bP +Most of tic's options +are not supported by SVr4 \fBtic\fP: +.sp +.RS +\fB\-0\fP +\fB\-1\fP +\fB\-C\fP +\fB\-G\fP +\fB\-I\fP +\fB\-N\fP +\fB\-R\fP +\fB\-T\fP +\fB\-V\fP +\fB\-a\fP +\fB\-e\fP +\fB\-f\fP +\fB\-g\fP +\fB\-o\fP +\fB\-r\fP +\fB\-s\fP +\fB\-t\fP +\fB\-x\fP +.RE +.bP +The NetBSD \fBtic\fP supports a few of the ncurses options +.sp +.RS +\fB\-a\fP +\fB\-o\fP +\fB\-x\fP +.RE +.IP +and adds \fB\-S\fP +(a feature which does the same thing +as infocmp's \fB\-e\fP and \fB\-E\fP options). +.PP +The SVr4 \fB\-c\fP mode does not report bad \*(``use=\*('' links. +.PP +System V does not compile entries to or read entries from your +\fI$HOME/.terminfo\fP database unless TERMINFO is explicitly set to it. +.SH FILES +.TP 5 +\fB\*d/?/*\fP +Compiled terminal description database. +.SH SEE ALSO +\fBcaptoinfo\fP(1), +\fBinfocmp\fP(1), +\fBinfotocap\fP(1), +\fBtoe\fP(1), +\fBncurses\fP(3NCURSES), +\fBterm\fP(\*n). +\fBterminfo\fP(\*n). +\fBuser_caps\fP(\*n). +.PP +This describes \fBncurses\fP +version 6.4 (patch 20221231). +.SH AUTHOR +Eric S. Raymond <esr@snark.thyrsus.com> +and +.br +Thomas E. Dickey <dickey@invisible-island.net> |