X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=include%2FCaps.keys;h=dccb357f742a47577714b366b2ef033c2ac05b7f;hp=d9a9c4cb40fe800bc43356162865b13c3b30dd57;hb=HEAD;hpb=bf2c36c4930ac5bb04cd2b1ba209cd09b6f510ab

diff --git a/include/Caps.keys b/include/Caps.keys
index d9a9c4cb..6f8a84e3 100644
--- a/include/Caps.keys
+++ b/include/Caps.keys
@@ -30,7 +30,7 @@
 # Author: Thomas Dickey
 #    and: Ilya Zakharevich
 #
-# $Id: Caps.keys,v 1.21 2024/01/13 22:05:39 tom Exp $
+# $Id: Caps.keys,v 1.25 2024/04/20 21:05:02 tom Exp $
 #
 # This is an adaptation of ncurses' termcap/terminfo capability table, which
 # is illustrates an experimental extension to describe alt-, shift- and
@@ -155,64 +155,101 @@
 # to buy space for non-essentials Emacs is still using.  Capabilities high
 # on that hit list: rc, sc, uc.
 #
+# FORMATTING THE TABLES
+#
+# We manually specify a (minimum) column width for the capability name
+# and terminfo code columns in the tables to achieve a consistent
+# arrangement; as used here, tbl(1) cannot know the width required by
+# one table's data while formatting another's.
+#
+# The longest capability names (C variables) are
+# "enter_near_letter_quality" and "bit_image_carriage_return" (tied at
+# 25n), and the longest terminfo codes are "setcolor", "kcdelete",
+# "kcinsert", "kadelete", and "kcinsert" (8n).
+#
+# The tables are a tight fit on traditional man(7) implementations that
+# use a line length of 65n, and the "Description" column has little room
+# within which the formatter can make breaking or adjustment decisions.
+# Words like "micro_..._address" and "parm_..._micro" don't break.
+# Reducing the inter-column gaps to 2 ens gives them enough room.  --GBR
+#
 #############################################################################
 #
 # STANDARD CAPABILITIES
 #
-#%The following is a complete table of the capabilities included in a
-#%terminfo description block and available to terminfo-using code.
-#%In each line of the table,
+#%Tables of capabilities
+#%.I \%ncurses
+#%recognizes in a
+#%.I \%term\%info
+#%terminal type description and available to
+#%.IR \%term\%info -using
+#%code follow.
 #%.bP
-#%The \fBvariable\fR is the name by which the programmer (at the terminfo level)
-#%accesses the capability.
+#%The capability name identifies the symbol by which the programmer
+#%using the
+#%.I \%term\%info
+#%API accesses the capability.
 #%.bP
-#%The \fBcapname\fR (\fICap-name\fP)
-#%is the short name used in the text of the database,
-#%and is used by a person updating the database.
+#%The TI
+#%.RI ( \%term\%info )
+#%code is the short name used by a person composing or updating a
+#%terminal type entry.
 #%.IP
-#%Whenever possible, capnames are chosen to be the same as or similar to
-#%the ANSI X3.64-1979 standard (now superseded by ECMA-48, which uses
-#%identical or very similar names).
+#%Whenever possible,
+#%these codes are the same as or similar to those of the ANSI X3.64-1979
+#%standard
+#%(now superseded by ECMA-48,
+#%which uses identical or very similar names).
 #%Semantics are also intended to match those of the specification.
 #%.IP
-#%Capability names have no hard length limit, but an informal limit of 5
-#%characters has been adopted to keep them short and to allow the tabs in
-#%the source file
-#%.B Caps
+#%.I \%term\%info
+#%codes have no hard length limit,
+#%but
+#%.I \%ncurses
+#%maintains an informal one of 5 characters to keep them short and to
+#%allow the tabs in the source file
+#%.I Caps
 #%to line up nicely.
+#%(Some standard codes exceed this limit regardless.)
 #%.bP
-#%The \fBtermcap\fP (\fITcap\fP) code is the old capability name
-#%(some capabilities are new, and have names which termcap did not originate).
+#%The TC
+#%.RI ( termcap )
+#%code is that used by the corresponding API of
+#%.IR \%ncurses .
+#%(Some capabilities are new,
+#%and have names that BSD
+#%.I termcap
+#%did not originate.)
 #%.bP
-#%Finally, the \fBdescription\fP field attempts to convey the semantics of the
-#%capability.
+#%The description field attempts to convey the capability's semantics.
 #%.PP
-#%You may find some codes in the description field:
-#%.TP
-#%(P)
-#%indicates that padding may be specified
+#%The description field employs a handful of notations.
 #%.TP
-#%#[1-9]
-#%in the description field indicates that the string is passed
-#%through \fBtparm\fP(3X) with parameters as given (#\fIi\fP).
-#%.IP
-#%If no parameters are listed in the description,
-#%passing the string through \fBtparm\fP(3X) may give unexpected results,
-#%e.g., if it contains percent (%%) signs.
+#%.B (P)
+#%indicates that padding may be specified.
 #%.TP
-#%(P*)
-#%indicates that padding may vary in proportion to the number of
-#%lines affected
+#%.B (P*)
+#%indicates that padding may vary in proportion to the number of output
+#%lines affected.
 #%.TP
-#%(#\d\fIi\fP\u)
-#%indicates the \fIi\fP\uth\d parameter.
+#%.BI # i
+#%indicates the
+#%.IR i th
+#%parameter of a string capability;
+#%the programmer should pass the string to \fB\%tparm\fP(3X) with the
+#%parameters listed.
+#%.IP
+#%If the description lists no parameters,
+#%passing the string to \fB\%tparm\fP(3X) may produce unexpected
+#%behavior,
+#%for instance if the string contains percent signs.
 #%.
 #%.PP
 #%.TS
 #%center;
-#%Lb Cb S  Lb
-#%Lb Lb Lb Lb
-#%Lb Lb Lb Lx.
+#%Lb        Cb       S   Lb
+#%Lb        Lb       Lb  Lb
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 #%\&	Code	\&
 #%Boolean Capability Name	TI	TC	Description
 #%_
@@ -258,9 +295,9 @@ lpi_changes_res			lpix	bool	YG	-	-	-----	changing line pitch changes resolution
 #%.
 #%.TS
 #%center;
-#%Lb Cb S  Lb
-#%Lb Lb Lb Lb
-#%Lb Lb Lb Lx.
+#%Lb        Cb       S   Lb
+#%Lb        Lb       Lb  Lb
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 #%\&	Code	\&
 #%Numeric Capability Name	TI	TC	Description
 #%_
@@ -291,9 +328,9 @@ no_color_video			ncv	num	NC	-	-	-----	video attributes that cannot be used with
 #%.PP
 #%.TS
 #%center;
-#%Lb Cb S  Lb
-#%Lb Lb Lb Lb
-#%Lb Lb Lb Lx.
+#%Lb        Cb       S   Lb
+#%Lb        Lb       Lb  Lb
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 #%\&	Code	\&
 #%Numeric Capability Name	TI	TC	Description
 #%_
@@ -319,9 +356,9 @@ bit_image_type			bitype	num	Yp	-	-	-----	type of bit-image device
 #%.
 #%.TS
 #%center;
-#%Lb Cb S  Lb
-#%Lb Lb Lb Lb
-#%Lb Lb Lb Lx.
+#%Lb        Cb       S   Lb
+#%Lb        Lb       Lb  Lb
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 #%\&	Code	\&
 #%String Capability Name	TI	TC	Description
 #%_
@@ -387,6 +424,10 @@ key_ctab			kctab	str	kt	KEY_CTAB	0525	-B-G-*	clear-tab key
 key_dc				kdch1	str	kD	KEY_DC		0512	YB-G-	delete-character key
 key_dl				kdl1	str	kL	KEY_DL		0510	-B-G-*	delete-line key
 key_down			kcud1	str	kd	KEY_DOWN	0402	YBCGE	down-arrow key
+#%.TE
+#%.TS
+#%center;
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 key_eic				krmir	str	kM	KEY_EIC		0514	-B-G-*	sent by rmir or smir in insert mode
 key_eol				kel	str	kE	KEY_EOL		0517	-B-G-*	clear-to-end-of-line key
 key_eos				ked	str	kS	KEY_EOS		0516	-B-G-*	clear-to-end-of-screen key
@@ -449,6 +490,10 @@ prtr_on				mc5	str	po	-		-	-B-G-*	turn on printer
 repeat_char			rep	str	rp	-		-	YB-GE	repeat char #1 #2 times (P*)
 reset_1string			rs1	str	r1	-		-	-B---	reset string
 reset_2string			rs2	str	r2	-		-	-B---	reset string
+#%.TE
+#%.TS
+#%center;
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 reset_3string			rs3	str	r3	-		-	-B---	reset string
 reset_file			rf	str	rf	-		-	-B---	name of reset file
 restore_cursor			rc	str	rc	-		-	YBCG-	restore cursor to position of last save_cursor
@@ -515,6 +560,10 @@ key_resume			kres	str	&5	KEY_RESUME	0570	-----	resume key
 key_save			ksav	str	&6	KEY_SAVE	0571	-----	save key
 key_suspend			kspd	str	&7	KEY_SUSPEND	0627	-----	suspend key
 key_undo			kund	str	&8	KEY_UNDO	0630	-----	undo key
+#%.TE
+#%.TS
+#%center;
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 key_sbeg			kBEG	str	&9	KEY_SBEG	0572	-----	shifted begin key
 key_scancel			kCAN	str	&0	KEY_SCANCEL	0573	-----	shifted cancel key
 key_scommand			kCMD	str	*1	KEY_SCOMMAND	0574	-----	shifted command key
@@ -577,6 +626,10 @@ key_f39				kf39	str	FT	KEY_F(39)	-	----E	F39 function key
 key_f40				kf40	str	FU	KEY_F(40)	-	----E	F40 function key
 key_f41				kf41	str	FV	KEY_F(41)	-	----E	F41 function key
 key_f42				kf42	str	FW	KEY_F(42)	-	----E	F42 function key
+#%.TE
+#%.TS
+#%center;
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 key_f43				kf43	str	FX	KEY_F(43)	-	----E	F43 function key
 key_f44				kf44	str	FY	KEY_F(44)	-	----E	F44 function key
 key_f45				kf45	str	FZ	KEY_F(45)	-	----E	F45 function key
@@ -600,7 +653,7 @@ key_f62				kf62	str	Fq	KEY_F(62)	-	----E	F62 function key
 key_f63				kf63	str	Fr	KEY_F(63)	-	----E	F63 function key
 clr_bol				el1	str	cb	-		-	-----	Clear to beginning of line
 clear_margins			mgc	str	MC	-		-	-----	clear right and left soft margins
-set_left_margin			smgl	str	ML	-		-	-----	set left soft margin at current column.	 (ML is not in BSD termcap).
+set_left_margin			smgl	str	ML	-		-	-----	set left soft margin at current column (not in BSD \fItermcap\fP)
 set_right_margin		smgr	str	MR	-		-	-----	set right soft margin at current column
 label_format			fln	str	Lf	-		-	-----	label format
 set_clock			sclk	str	SC	-		-	-----	set clock, #1 hrs #2 mins #3 secs
@@ -733,6 +786,10 @@ change_res_horz			chr	str	ZC	-		-	-----	Change horizontal resolution to #1
 change_res_vert			cvr	str	ZD	-		-	-----	Change vertical resolution to #1
 define_char			defc	str	ZE	-		-	-----	Define a character #1, #2 dots wide, descender #3
 enter_doublewide_mode		swidm	str	ZF	-		-	-----	Enter double-wide mode
+#%.TE
+#%.TS
+#%center;
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 enter_draft_quality		sdrfq	str	ZG	-		-	-----	Enter draft-quality mode
 enter_italics_mode		sitm	str	ZH	-		-	-----	Enter italic mode
 enter_leftward_mode		slm	str	ZI	-		-	-----	Start leftward carriage motion
@@ -786,9 +843,9 @@ zero_motion			zerom	str	Zx	-		-	-----	No motion for subsequent character
 #%.PP
 #%.TS
 #%center;
-#%Lb Cb S  Lb
-#%Lb Lb Lb Lb
-#%Lb Lb Lb Lx.
+#%Lb        Cb       S   Lb
+#%Lb        Lb       Lb  Lb
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 #%\&	Code	\&
 #%String Capability Name	TI	TC	Description
 #%_
@@ -842,9 +899,9 @@ alt_scancode_esc		scesa	str	S8	-		-	-----	Alternate escape for scancode emulatio
 #%.PP
 #%.TS
 #%center;
-#%Lb Cb S  Lb
-#%Lb Lb Lb Lb
-#%Lb Lb Lb Lx.
+#%Lb        Cb       S   Lb
+#%Lb        Lb       Lb  Lb
+#%Lbw(25n)2 Lbw(8n)2 Lb2 Lx.
 #%\&	Code	\&
 #%String Capability Name	TI	TC	Description
 #%_