Content: * Speak of "process environment", not "shell environment"; things other than shells can launch curses applications. * Refer specifically to "ncurses ABI 6", rather than the elliptical "version 6" (of what?).
Style: * Protect whatever "@TIC@" expands to from hyphenation. * Protect whatever "@TERMINFO_DIRS@" expands to from hyphenation. * Protect whatever "@INFOTOCAP@" expands to from hyphenation. * Protect whatever "@CAPTOINFO@" expands to from hyphenation. * Set the expansions of "@TIC@" and "@INFOCMP@" in bold, not roman. * Specify hyphenation breakpoint in "terminfo". * Favor English phrases over Latin abbreviations. * Set ncurses command names in bold, not roman. * Set file names in italics, not ASCII double quotes. * Set "termcap" in italics, not roman. * Set "terminfo" in italics, not roman. * Quote section names in man page cross references rather than setting them in italics. * Use a singular possessive form with "ncurses"; it is not a plural noun, simply one that orthographically ends with "s". (Aloud, a native English speaker pronounces its possessive as "enn-kurr-sizz-izz", which is no more elocutionarily awkward than "parenthesis".) Also see <https://apastyle.apa.org/\ style-grammar-guidelines/grammar/possessive-nouns>.) * Favor "ncurses" over "this implementation". * Add periods to end of sentences in bulleted list of warning counts. * Fix missing comma. * Favor use of page-local quotation string definitions for quotation in prose over ASCII double quote characters. * Favor using "this" as an adjective (and supply a noun for it to describe), over application as a demonstrative pronoun. * ...or simply employ a noun explicitly. * Distinguish more clearly between "capabilities" in the abstract, capability names, and capability values. (Hypernymy and hyponymy strike again.) * Set equals sign in bold when using it as a literal ("use="). * Recast. Markup: * Favor man(7) font style macros over *roff font selection escape sequences, except for man page cross references (because man/make_sed.sh recognizes only certain patterns when rewriting such cross references) and terms in the "NAME" section (because the generated edit_man.sh script expects font selection escape sequences when scraping terms thence to gather names for man page aliases). --- man/tic.1m | 455 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 327 insertions(+), 128 deletions(-) diff --git a/man/tic.1m b/man/tic.1m index 5e6585c9f..92748b7aa 100644 --- a/man/tic.1m +++ b/man/tic.1m @@ -47,7 +47,7 @@ . .SH NAME \fB\%@TIC@\fP \- -compile terminal descriptions for \fIterminfo\fR or \fItermcap\fR +compile terminal descriptions for \%\fIterm\%info\fR or \fItermcap\fR .SH SYNOPSIS \fB@TIC@\fP [\fB\-\ @@ -82,129 +82,238 @@ .SH SYNOPSIS [\fB\-w\fP[\fIn\fP]] \fIfile\fP .SH DESCRIPTION -The \fB@TIC@\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 \fB\%ncurses\fP(3X). +.B \%@TIC@ +translates a +.I \%term\%info +file from source format +into the compiled format +used by the +\fB\%ncurses\fP(3X) +library. .PP -As described in \fBterm\fP(5), the database may be either a directory -tree (one file per terminal entry) or a hashed database (one record per entry). -The \fB@TIC@\fP command writes only one type of entry, -depending on how it was built: +As described in \fBterm\fP(5), +the database may be either a directory tree +(one file per terminal entry) +or a hashed database +(one record per entry). +The +.B \%@TIC@ +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, +For directory trees, +the top-level directory, +such as +.IR \%/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", +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). +default directory name (only adding a \*(``.db\*('' suffix). .PP In either case (directory or hashed database), -\fB@TIC@\fP will create the container if it does not exist. +.B \%@TIC@ +will create the container if it does not exist. For a directory, this would be the \*(``terminfo\*('' leaf, -versus a "terminfo.db" file. +versus a +.I terminfo.db +file. .PP The results are normally placed -in the system terminfo database +in the system +.I \%term\%info +database .IR \%@TERMINFO@ "." The compiled terminal description can be placed -in a different terminfo database. +in a different +.I \%term\%info +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 \fI\%TERMINFO\fP -in your shell environment to a valid database location. +in the process environment to a valid database location. .bP -Secondly, if \fB@TIC@\fP cannot write in +Secondly, if +.B \%@TIC@ +cannot write in .I \%@TERMINFO@ -or the location specified using your \fI\%TERMINFO\fP variable, -it looks for the directory \fI$HOME/.terminfo\fP -(or hashed database \fI$HOME/.terminfo.db)\fP; +or the location specified using your +.I \%TERMINFO +variable, +it looks for the directory +.I \%$HOME/.terminfo +(or hashed database +.IR $HOME/.terminfo.db ); if that location exists, the entry is placed there. .PP -Libraries that read terminfo entries are expected to check in succession +Libraries that read +.I \%term\%info +entries are expected to check in succession .bP -a location specified with the \fI\%TERMINFO\fP environment variable, +a location specified by the +.I \%TERMINFO +environment variable, .bP -\fI$HOME/.terminfo\fP, +.IR \%$HOME/.terminfo "," .bP -directories listed in the \fI\%TERMINFO_DIRS\fP environment variable, +directories listed in the +.I \%TERMINFO_DIRS +environment variable, .bP -a compiled-in list of directories (@TERMINFO_DIRS@), and +a compiled-in list of directories +.RI \%( @TERMINFO_DIRS@ ), +and .bP -the system terminfo database +the system +.I \%term\%info +database .RI \%( @TERMINFO@ ). .PP -The \fIFetching Compiled Descriptions\fP section in the \fBterminfo\fR(5) -manual goes into further detail. +Section \*(``Fetching Compiled Descriptions\*('' in \fBterminfo\fP(5) +goes into further detail. .SS Aliases -This is the same program as @INFOTOCAP@ and @CAPTOINFO@; -usually those are linked to, or copied from this program: +.B \%@TIC@ +is the same program as +.B \%@INFOTOCAP@ +and +.BR \%@CAPTOINFO@ ";" +usually those are linked to, +or copied from, this program. .bP -When invoked as @INFOTOCAP@, @TIC@ sets the \fB\-I\fP option. +When invoked as +.BR \%@INFOTOCAP@ "," +.B \%@TIC@ +sets the +.B \-I +option. .bP -When invoked as @CAPTOINFO@, @TIC@ sets the \fB\-C\fP option. +When invoked as +.BR \%@CAPTOINFO@ "," +.B \%@TIC@ +sets the +.B \-C +option. .SH OPTIONS .TP -\fB\-0\fP -restricts the output to a single line +.B \-0 +restricts the output to a single line. .TP -\fB\-1\fP -restricts the output to a single column +.B \-1 +restricts the output to a single column. .TP -\fB\-a\fP -tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding -them. +.B \-a +tells +.B \%@TIC@ +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. +.B \-a +implies +.BR \-x "," +because +.B \%@TIC@ +treats the commented-out entries as user-defined names. +If the source is in +.I termcap +format, +.B \%@TIC@ +accepts the two-character names required by +.I \%ncurses +ABI 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 \fB@INFOCMP@\fP(1M) 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 +Force source translation to +.I termcap +format. +Note: this option differs from the +.B \-C +option of \fB\%@INFOCMP@\fP(1M) +in that it does not merely translate capability names, +but also translates +.I \%term\%info +string capability values to +.I termcap +format. +.B \%@TIC@ +leaves capabilities that are not translatable +in the entry under their +.I \%term\%info +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. +The actual format used +incorporates some improvements for escaped characters +from +.I \%term\%info +format. +For a stricter BSD-compatible translation, +specify +.B \-K +as well. .IP -If this is combined with \fB\-c\fP, \fB@TIC@\fP makes additional checks -to report cases where the terminfo values do not have an exact equivalent -in termcap form. +If +.B \-C +is combined with +.BR \-c "," +.B \%@TIC@ +makes additional checks, +reporting cases where +.I \%term\%info +capability values do not have an exact equivalent +in +.I termcap +syntax. 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. +.B sgr +usually does not convert, +because +.I termcap +is unable to work with more than two parameters, +and because +.I termcap 's +language for encoding parameterized capabilities +lacks many of +.IR \%term\%info 's +arithmetic and logical operators. .RE .TP -\fB\-c\fP -tells \fB@TIC@\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. +.B \-c +tells +.B \%@TIC@ +to perform only validation of +.I file "," +including syntax problems and invalid +.RB \*(`` use \*('' +references; +no output is produced. +If you specify +.B \-C +.RB ( \-I ) +with this option, +.B \%@TIC@ +warns about entries that, +after +.RB \*(`` use \*('' +resolution, +exceed 1023 (4096) bytes. +Due to a fixed buffer length in older +.I termcap +libraries, +as well as buggy checking of the buffer length +(and a documented limit in +.IR \%term\%info ), +these entries may cause core dumps +with other implementations. .IP -\fB@TIC@\fP checks string capabilities +.B \%@TIC@ +checks string capabilities to ensure that those with parameters are valid expressions. It validates only standard string capabilities, ignoring those defined with the @@ -212,10 +321,14 @@ .SH OPTIONS option. .TP \fB\-D\fP -tells \fB@TIC@\fP to print the database locations that it knows about, and exit. +tells +.B \%@TIC@ +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 \fB@TIC@\fP is not able to find a writable database location +If +.B \%@TIC@ +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. @@ -228,7 +341,9 @@ .SH OPTIONS 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, +(Note: depending on how +.B \%@TIC@ +was compiled, this option may require \fB\-I\fP or \fB\-C\fP.) .TP \fB\-f\fP @@ -326,12 +441,16 @@ .SH OPTIONS descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). .TP \fB\-t\fP -tells \fB@TIC@\fP to discard commented-out capabilities. +tells +.B \%@TIC@ +to discard commented-out capabilities. Normally when translating from terminfo to termcap, untranslatable capabilities are commented-out. .TP \fB\-U\fP -tells \fB@TIC@\fP to not post-process the data after parsing the source file. +tells +.B \%@TIC@ +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 @@ -341,7 +460,9 @@ .SH OPTIONS .TP \fB\-v\fIn\fR specifies that (verbose) output be written to standard error trace -information showing \fB@TIC@\fP's progress. +information showing +.BR \%@TIC@ 's +progress. .IP The optional parameter \fIn\fP is a number from 1 to 9, inclusive, indicating the desired level of detail of information. @@ -402,45 +523,91 @@ .SH OPTIONS .TP \fB\-x\fP Treat unknown capabilities as user-defined (see \fBuser_caps\fP(5)). -That is, if you supply a capability name which \fB@TIC@\fP does not recognize, +That is, if you supply a capability name which +.B \%@TIC@ +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(5)]. +.I file +contains one or more +.I \%term\%info +terminal descriptions in source format; see \fBterminfo\fP(5). Each description in the file -describes the capabilities of a particular terminal. +describes the capabilities of a particular terminal type. .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. +If +.I file +is \*(``\-\*('', +the data are read from the standard input stream. +The +.I file +parameter may also be the path of a character device. .SS Processing -All but one of the capabilities recognized by \fB@TIC@\fP are documented -in \fBterminfo\fP(5). -The exception is the \fBuse\fP capability. +\fBterminfo\fP(5) documents all but one of the capabilities +recognized by +.BR \%@TIC@ "." +The exception is the +.B use +capability, +which enables a terminal type description to incorporate others +by reference. .PP -When a \fBuse\fP=\fIentry\fP\-\fIname\fP field is discovered in a -terminal entry currently being compiled, \fB@TIC@\fP reads in the binary +.B \%@TIC@ +serially reads and compiles terminal type descriptions; +at any given time, +the program compiles at most one +.I current +entry. +.\" That is, tic doesn't recursively compile entries to resolve "use=". +When +.B \%@TIC@ +encounters a +.BI use= entry-name +field in the current entry, +it reads the compiled description of +.I entry-name from .I \%@TERMINFO@ -to complete the entry. -(Entries created from -\fIfile\fP will be used first. -\fB@TIC@\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. +to complete the current entry. +If +.B \%@TIC@ +has already compiled a description of +.I entry-name +preceding the current entry in +.IR file "," +.B \%@TIC@ +uses it preferentially. +.\" XXX: Check this--tic doesn't read ahead in or index the input file, +.\" does it? Otherwise this feature would break when reading from a +.\" pipe. --GBR +.B \%@TIC@ +duplicates the capabilities in +.I entry-name +for the current entry, +excepting those that the current entry explicitly defines. +The foregoing has implications for capability cancellation. +When +.I entry-1 +declares +.RB \*(`` use=\c +.IR entry-2 \*(``, +any canceled capabilities in +.I entry-2 +must also appear in +.I entry-1 +prior to +.RB \*(`` use=\c +.IR entry-2 \*(`` +for these capabilities to be canceled in +.IR entry-1 "." .PP -Total compiled entries cannot exceed -4096 bytes in the legacy storage format, or +Compiled entries cannot exceed +4096 bytes in the legacy storage format, +or 32768 using the extended number format. The name field cannot exceed 512 bytes. @@ -453,14 +620,20 @@ .SH FILES .I @TERMINFO@ compiled terminal description database .SH NOTES -There is some evidence that historic \fB@TIC@\fP implementations treated +There is some evidence that historic +.B \%@TIC@ +implementations treated description fields with no whitespace in them as additional aliases or short names. -This \fB@TIC@\fP does not do that, but it does warn when +This +.B \%@TIC@ +does not do that, but it does warn when description fields may be treated that way and check them for dangerous characters. .SH EXTENSIONS -Unlike the SVr4 \fB@TIC@\fP command, this implementation can actually +Unlike the SVr4 +.B \%@TIC@ +command, this implementation can actually compile termcap sources. In fact, entries in terminfo and termcap syntax can be mixed in a single source file. @@ -469,23 +642,32 @@ .SH EXTENSIONS .PP The SVr4 manual pages are not clear on the resolution rules for \fBuse\fP capabilities. -This implementation of \fB@TIC@\fP will find \fBuse\fP targets anywhere +.IR ncurses 's +.B \%@TIC@ +finds \fBuse\fP targets anywhere in the source file, -or anywhere in the file tree rooted at -\fI\%TERMINFO\fP +or anywhere in the file tree rooted at the location in the +.I \%TERMINFO +environment variable (if -\fI\%TERMINFO\fP is defined), -or in the user's \fI$HOME/.terminfo\fP database +.I \%TERMINFO +is defined), +or in the user's +.I \%$HOME/.terminfo +database (if it exists), -or (finally) anywhere in the system's file tree of -compiled entries. +or (finally) anywhere in the system's collection of compiled entries. .PP -The error messages from this \fB@TIC@\fP have the same format as GNU C +The error messages from this +.B \%@TIC@ +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 +Most of +.BR \%@TIC@ 's +options are not supported by SVr4 \fBtic\fP: .sp .RS @@ -519,7 +701,9 @@ .SH EXTENSIONS .IP and adds \fB\-S\fP (a feature which does the same thing -as @INFOCMP@'s \fB\-e\fP and \fB\-E\fP options). +as +.BR \%@INFOCMP@ 's +\fB\-e\fP and \fB\-E\fP options). .PP The SVr4 \fB\-c\fP mode does not report bad \*(``use=\*('' links. .PP @@ -590,28 +774,43 @@ .SH HISTORY In 2010, Roy Marples provided a \fBtic\fP program and terminfo library for NetBSD. That implementation adapts several features from \fI\%ncurses\fP, -including \fB@TIC@\fP's \fB\-x\fP option. +including +.BR \%@TIC@ 's +\fB\-x\fP option. .PP -The \fB\-c\fP option tells \fB@TIC@\fP to check for problems in the +The \fB\-c\fP option tells +.B \%@TIC@ +to check for problems in the terminfo source file. Continued development provides additional checks: .bP -\fIpcurses\fP had 8 warnings +.I pcurses +had 8 warnings. .bP -\fI\%ncurses\fP in 1996 had 16 warnings +.I \%ncurses +in 1996 had 16 warnings. .bP -Solaris (SVr4) curses has 28 warnings +Solaris (SVr4) +.I curses +has 28 warnings. .bP -NetBSD tic in 2019 has 19 warnings. +NetBSD +.I tic +in 2019 has 19 warnings. .bP -\fI\%ncurses\fP in 2019 has 96 warnings +.I \%ncurses +in 2019 has 96 warnings. .PP -The checking done in \fI\%ncurses\fP' \fB@TIC@\fP helps with the +The checking done in +.IR \%ncurses 's +.B \%@TIC@ +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 \fI\%ncurses\fP' terminal -database; +There are 527 distinct capabilities in +.IR \%ncurses 's +terminal database; 128 of those are user-defined. .SH AUTHORS Eric S. Raymond <[email protected]> -- 2.30.2
signature.asc
Description: PGP signature
