[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 2/5] man/toe.1m: Revise.
From: |
G. Branden Robinson |
Subject: |
[PATCH 2/5] man/toe.1m: Revise. |
Date: |
Wed, 27 Sep 2023 07:29:45 -0500 |
* Drop definitions of page-local `bP`, `NS`, and `NE` macros; see below.
* Convert synopsis to call man(7) macros for formatting.
* Mark operands as optional (in non-[Uu] mode).
* Synopsize distinct operation modes separately. For example, the `-a`,
`-h`, and `-s` options are ignored without diagnostic if either of
`-u` or `-U` is used. Further, the latter two are mutually exclusive.
* Use "directory" as metasyntactic variable for a directory, not "file".
* Recast description.
* Protect literals from hyphenation.
* Set "ncurses", "termcap", and "terminfo" in italics.
* Add "OPTIONS" section. Shift partial discussion of available options
(such as `-h`) into it. Recast, converting option presentation to
stem format, as used in clear(1), and in infocmp(1), tset(1), and
tic(1) (albeit inconsistently).
* Use man(7) macros to present option syntax.
* Set tagged paragraph indentation in option list sufficient to prevent
a break after "-u file".
* Use typographer's double quotes where available; the page already
had definitions for them.
* Document how the `-u` and `-U` options interpret termcap entries in
more detail.
* Increase precision. (For instance, say "integer", not "number", when
we mean the former.)
* Update examples to illustrate terminal types one is likely to
encounter nowadays. Annotate how they were obtained.
* Set examples with tbl(1) tables and man(7) `RS`, `RE`, and `PP` macros
instead of page-local `NS`/`NE` macros.
* Drop explicit indentation from `TP` call in "FILES" section.
* Stop noun phrase from masquerading as sentence.
* Recast "HISTORY" section. Move origin of name to the end.
---
man/toe.1m | 284 +++++++++++++++++++++++++++++------------------------
1 file changed, 154 insertions(+), 130 deletions(-)
diff --git a/man/toe.1m b/man/toe.1m
index c0325e81..f2698728 100644
--- a/man/toe.1m
+++ b/man/toe.1m
@@ -29,10 +29,6 @@
.\"
.\" $Id: toe.1m,v 1.46 2023/09/16 23:38:39 tom Exp $
.TH @TOE@ 1M 2023-09-16 "ncurses 6.4" "User commands"
-.de bP
-.ie n .IP \(bu 4
-.el .IP \(bu 2
-..
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
@@ -42,156 +38,184 @@
.ie \n(.g .ds CW CR
.el .ds CW CW
.\}
-.de NS
-.ie n .sp
-.el .sp .5
-.ie n .in +4
-.el .in +2
-.nf
-.ft \*(CW
-..
-.de NE
-.fi
-.ft R
-.ie n .in -4
-.el .in -2
-..
.ds n 5
.ds d @TERMINFO@
.SH NAME
\fB\%@TOE@\fP \-
list table of entries of \fIterminfo\fR terminal types
.SH SYNOPSIS
-\fB@TOE@\fP [\fB\-v\fP[\fIn\fP]] [\fB\-ahsuUV\fP] \fIfile...\fP
-.SH DESCRIPTION
-With no options,
-\fB@TOE@\fP lists all available terminal types by primary name
-with descriptions.
-File arguments specify the directories to be scanned; if no
-such arguments are given,
-your default terminfo directory is scanned.
-If you also specify the \fB\-h\fP option,
-a directory header will be issued as each
-directory is entered.
+.B @TOE@
+.RB [ \-ahs ]
+.RB [ \-v\ \c
+.RI [ n ]]
+.RI [ directory
+\&.\|.\|.]
.PP
-There are other options intended for use by terminfo file maintainers:
-.TP
-\fB\-a\fP
-report on all of the terminal databases which ncurses would search,
-rather than only the first one that it finds.
+.B @TOE@
+.RB [ \-u | \-U ]
+.I file
+.PP
+.B "@TOE@ \-V"
+.SH DESCRIPTION
+\fB\%@TOE@\fP reports to the standard output stream the (primary) names
+and descriptions of the terminal types available to the \fIterminfo\fP
+library.
+Each \fIdirectory\fP operand is scanned;
+if none are given,
+\fB\%@TOE@\fP scans the the default \fIterminfo\fP directory.
+.SH OPTIONS
+The \fB\-h\fP option can be helpful to observe where \fB\%@TOE@\fP is
+looking for terminal descriptions.
+Other options support maintainers of \fIterminfo\fP terminal
+descriptions.
+.TP 9 \" "-u file" + 2n
+.B \-a
+lists entries from all terminal database directories that \fIterminfo\fP
+would search,
+instead of only the first that it finds.
.IP
-If the \fB\-s\fP is also given, \fB@TOE@\fP
-adds a column to the report,
-showing (like \fBconflict\fP(1)) which entries which
-belong to a given terminal database.
-An "*" marks entries which differ, and "+" marks equivalent entries.
+If the \fB\-s\fP option is also given,
+\fB\%@TOE@\fP adds a column to the report,
+showing (like \fB\%conflict\fP(1)) which entries belong to a given
+terminal database.
+An \*(``*\*('' marks entries that differ,
+and \*(``+\*('' marks equivalent entries.
.IP
-Without the \fB\-s\fP option, \fB@TOE@\fP does not attempt to merge
-duplicates in its report
+Without the \fB\-s\fP option,
+\fB\%@TOE@\fP does not attempt to merge duplicates in its report.
+.TP
+.B \-h
+writes a heading naming each each directory as it is accessed.
.TP
-\fB\-s\fP
-sort the output by the entry names.
+.B \-s
+sorts the output by the entry names.
.TP
-\fB\-u\fP \fIfile\fP
-says to write a report to the standard output,
-listing dependencies in the given terminfo/termcap source file.
-The report condenses the \*(``use\*('' relation:
-each line consists of the primary name of a terminal that
-has use capabilities,
-followed by a colon,
-followed by the
-whitespace-separated primary names of all terminals which occur in those use
-capabilities,
-followed by a newline
+.BI \-u\ file
+lists terminal type dependencies in \fIfile\fP,
+a \fIterminfo\fP entry source or \fItermcap\fP database file.
+The report summarizes the \*(``\fBuse\fP\*('' (\fIterminfo\fP) and
+\*(``\fBtc\fP\*('' (\fItermcap\fP) relations:
+each line comprises the primary name of a terminal type employing
+\fBuse\fP/\fBtc\fP capabilities,
+a colon,
+a space- and tab-separated list of primary names of terminal types thus
+named,
+and a newline.
.TP
-\fB\-U\fP \fIfile\fP
-says to write a report to the standard output,
-listing reverse dependencies in the given terminfo/termcap source file.
-The report reverses the \*(``use\*('' relation:
-each line consists of the primary name of a
-terminal that occurs in use capabilities,
-followed by a colon,
-followed by the
-whitespace-separated primary names of all terminals which depend on it,
-followed by a newline.
+.BI \-U\ file
+lists terminal type reverse dependencies in \fIfile\fP,
+a \fIterminfo\fP entry source or \fItermcap\fP database file.
+The report summarizes the \*(``\fBuse\fP\*('' (\fIterminfo\fP) and
+\*(``\fBtc\fP\*('' (\fItermcap\fP) reverse relations:
+each line comprises the primary name of a terminal type occurring in
+\fBuse\fP/\fBtc\fP capabilities,
+a colon,
+a space- and tab-separated list of primary names of terminal types
+naming them thus,
+and a newline.
.TP
-\fB\-v\fIn\fR
-specifies that (verbose) output be written to standard error,
-showing \fB@TOE@\fP's progress.
+.BR \-v\ [\c
+.IR n ]
+reports verbose status information to the standard error stream,
+showing \fB\%@TOE@\fP's progress.
.IP
-The optional parameter \fIn\fP is a number from 1 to 10,
-interpreted as for \fB@TIC@\fP(1M).
-If ncurses is built without tracing support, the optional parameter is ignored.
+The optional parameter \fIn\fP is an integer between 1 and 10 inclusive,
+interpreted as for \fB\%@TIC@\fP(1M).
+If \fIncurses\fP is built without tracing support,
+\fIn\fP is ignored.
.TP
\fB\-V\fP
-reports the version of ncurses which was used in this program,
-and exits.
+reports the version of \fIncurses\fP associated
+with this program and exits with a successful status.
.SH EXAMPLES
-Without sorting, the \fB\-a\fP option reports all of the names found
-in all of the terminal databases found by the \fBTERMINFO\fP and
-\fBTERMINFO_DIRS\fP environment variables:
-.NS
-MtxOrb162 16x2 Matrix Orbital LCD display
-MtxOrb204 20x4 Matrix Orbital LCD display
-MtxOrb Generic Matrix Orbital LCD display
-qvt101+ qume qvt 101 PLUS product
-qvt119+-25 QVT 119 PLUS with 25 data lines
-qansi-g QNX ANSI
-qvt103 qume qvt 103
-qnxw QNX4 windows
-qansi-w QNX ansi for windows
-qnxm QNX4 with mouse events
-qvt203-25-w QVT 203 PLUS with 25 by 132 columns
-qansi-t QNX ansi without console writes
-\&.\ .\ .
-.NE
+When not sorting with the \fB\-s\fP option,
+the \fB\-a\fP option reports all of the names found in all of the
+terminal database directories named in the \fB\%TERMINFO\fP and
+\fB\%TERMINFO_DIRS\fP environment variables.
+.RS 4
+.PP
+.\" toe -a | grep -E '^(xterm|vt)'
+.TS
+Lf(\*(CW)2 Lf(\*(CW).
+xterm\-color generic color xterm
+xterm\-xfree86 xterm terminal emulator (XFree86)
+xterm\-vt220 xterm emulating vt220
+xterm\-256color xterm with 256 colors
+xterm\-r6 xterm X11R6 version
+xterm\-r5 xterm R5 version
+xterm\-mono monochrome xterm
+.\" The next row overruns the line length on DWB nroff (65n).
+xterm xterm terminal emulator (X Window System)
+vt220 dec vt220
+vt102 dec vt102
+vt100 dec vt100 (w/advanced video)
+vt52 dec vt52
+.T&
+L.
+\&.\|.\|.
+.TE
+.RE
.PP
-Use the \fB\-a\fP and \fB\-s\fP options together to show where each terminal
-description was found:
-.NS
---> /usr/local/ncurses/share/terminfo
-----> /usr/share/terminfo
-*-+-: 9term Plan9 terminal emulator for X
-*---: Eterm Eterm with xterm-style color support (X Window System)
-*-*-: Eterm-256color Eterm with xterm 256-colors
-*-*-: Eterm-88color Eterm with 88 colors
-*-+-: MtxOrb Generic Matrix Orbital LCD display
-*-+-: MtxOrb162 16x2 Matrix Orbital LCD display
-*-+-: MtxOrb204 20x4 Matrix Orbital LCD display
-*-*-: NCR260VT300WPP NCR 2900_260 vt300 wide mode pc+ kybd
-*-+-: aaa ann arbor ambassador/30 lines
-*-+-: aaa+dec ann arbor ambassador in dec vt100 mode
-*-+-: aaa+rv ann arbor ambassador in reverse video
-\&.\ .\ .
-.NE
+Use the \fB\-a\fP and \fB\-s\fP options together to show where each
+terminal description was found.
+.RS 4
+.PP
+.\" toe -as | grep -E '(^-+>|:.(xterm|vt))'
+.TS
+lf(\*(CW).
+\-\-> /etc/terminfo
+\-\-\-\-> /lib/terminfo
+\-\-\-\-\-\-> /usr/share/terminfo
+.TE
+.TS
+lf(\*(CW)1 lf(\*(CW)2 lf(\*(CW).
+\-\-*\-\-\-: vt100 dec vt100 (w/advanced video)
+\-\-*\-\-\-: vt102 dec vt102
+\-\-*\-\-\-: vt220 dec vt220
+\-\-*\-\-\-: vt52 dec vt52
+.\" The next row overruns the line length on DWB nroff (65n).
+\-\-*\-\-\-: xterm xterm terminal emulator (X Window System)
+\-\-*\-\-\-: xterm\-256color xterm with 256 colors
+\-\-*\-\-\-: xterm\-color generic color xterm
+\-\-*\-\-\-: xterm\-mono monochrome xterm
+\-\-*\-\-\-: xterm\-r5 xterm R5 version
+\-\-*\-\-\-: xterm\-r6 xterm X11R6 version
+\-\-*\-\-\-: xterm\-vt220 xterm emulating vt220
+.\" The next row overruns the line length on DWB nroff (65n).
+\-\-*\-\-\-: xterm\-xfree86 xterm terminal emulator (XFree86)
+.T&
+l.
+\&.\|.\|.
+.TE
+.RE
.SH FILES
-.TP 5
-\fB\*d/?/*\fP
-Compiled terminal description database.
+.TP
+\fI\*d\fP
+compiled terminal description database
.SH HISTORY
-This utility is not provided by other implementations.
-There is no relevant X/Open or POSIX standard for \fB@TOE@\fP.
+\fB\%@TOE@\fP is not provided by other implementations.
+There is no applicable X/Open or POSIX standard for it.
+.PP
+It replaces a \fB\-T\fP option that was briefly supported by
+the \fIncurses\fP \fB\%infocmp\fP utility in 1995.
.PP
-The program name refers to a developer's pun:
-.bP
+The \fB\-a\fP and \fB\-s\fP options were added in 2006 and 2011,
+respectively.
+.PP
+The program's name originates with a developer's pun:
+.IP \(bu 4
\fBtic\fP,
-.bP
+.IP \(bu
\fBtac\fP (now \fBtack\fP),
-.bP
+.IP \(bu
\fBtoe\fP.
-.PP
-It replaced a \fB\-T\fP option which was briefly supported by
-the ncurses \fBinfocmp\fP utility in 1995.
-.PP
-The \fB\-a\fP and \fB\-s\fP options were added to
-\fB@TOE@\fP several years later (2006 and 2011, respectively).
.SH SEE ALSO
-\fB@CAPTOINFO@\fP(1M),
-\fB@INFOCMP@\fP(1M),
-\fB@INFOTOCAP@\fP(1M),
-\fB@TIC@\fP(1M),
-\fBcurses\fP(3X),
-\fBterminfo\fP(\*n).
+\fB\%@CAPTOINFO@\fP(1M),
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@INFOTOCAP@\fP(1M),
+\fB\%@TIC@\fP(1M),
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(\*n)
.PP
-This describes \fBncurses\fP
+This describes \fIncurses\fP
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
--
2.30.2
signature.asc
Description: PGP signature
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [PATCH 2/5] man/toe.1m: Revise.,
G. Branden Robinson <=