From d2bcf2d01c52b23fea69b1492d437404eb67f7ff Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kazkylheku@vtech.ca>
Date: Tue, 13 Apr 2021 21:15:04 -0700
Subject: doc: implement typesetting of keystrokes.

This commit relies on parallel improvements
in man2html, up through commit
ac186529b6b5f80906c3215a67c98505db7bb156
"Implement .M2HT request for HTML passthrough."

* genman.txr: Add CSS block targetting the kbd element,
providing 3D styling for keyboard input.

* txr.1: Define two new macros, .key and .keyn.
These are defined in three different ways: in man page
output, we put square brackets around keystrokes.
In typeset groff output, we put a square border around
them using a box macro cribbed from groff documentation.
In HTML, we use .M2HT to wrap a <kbd> tag around the
keystrokes. Documentatio is updated to use these macros
for all keystrokes. We no longer separate keystroke
sequence elements with commas.
---
 genman.txr |  12 ++
 txr.1      | 535 ++++++++++++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 435 insertions(+), 112 deletions(-)

diff --git a/genman.txr b/genman.txr
index 89aec557..07db7e04 100644
--- a/genman.txr
+++ b/genman.txr
@@ -194,6 +194,18 @@ dl.items dt {
   float: left;
   padding-right: 1ex;
 }
+kbd {
+  background-color: #eee;
+  border-radius: 3px;
+  border: 1px solid #b4b4b4;
+  box-shadow: 0 1px 1px rgba(0, 0, 0, .2), 0 2px 0 0 rgba(255, 255, 255, .7) inset;
+  color: #333;
+  display: inline-block;
+  font-weight: 700;
+  line-height: 1;
+  padding: 2px 4px;
+  white-space: nowrap;
+}
 </style>
 <script type="text/javascript">
 var xpanded = false;
diff --git a/txr.1 b/txr.1
index f9d718fd..9aa776c2 100644
--- a/txr.1
+++ b/txr.1
@@ -364,6 +364,46 @@
 .  gets \\$*
 .  IP "\\*s"
 ..
+.\" keystrokes
+.ie \n(M2 \{\
+.de key
+.M2HT <kbd>\\$1</kbd>
+..
+.de keyn
+.M2HT <kbd>\\$1</kbd>\\$2
+..
+.\}
+.el \{\
+.  ie n \{\
+.    de key
+[\\$1]
+.    .
+.    de keyn
+[\\$1]\\$2
+.    .
+.  \}
+.  el \{\
+.  \" Box macro from Groff manual with $2 added
+.    de box
+.      nr @wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l (\\n[@wd]u + .4m) 0'\
+\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l -(\\n[@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\\$1\
+\h'.2m'\\$2
+.    .
+.    de key
+.  box "\\$1" ""
+.    .
+.    de keyn
+.  box "\\$1" "\\$2"
+.    .
+.  \}
+.\}
 .\" TXR name
 .ds TX \f[B]TXR\f[]
 .ds TL \f[B]TXR Lisp\f[]
@@ -67714,8 +67754,9 @@ character-at-a-time input. However, most input translations are preserved,
 except that the conversion of CR characters to NL is disabled.  The
 signal-generating characters are processed in this mode. This latter feature of
 the configuration is the likely inspiration for the word "cbreak". Unless
-otherwise configured, the interrupt character corresponds to the Ctrl-C key,
-and "break" is another term for an interactive interruption.
+otherwise configured, the interrupt character corresponds to the
+.key Ctrl-C
+key, and "break" is another term for an interactive interruption.
 
 .coNP Methods @ string-encode and @ string-decode
 .synb
@@ -76658,7 +76699,9 @@ interpreted as editing commands or other special characters, or else are
 inserted into the editing buffer. However, control characters which don't
 correspond to commands are silently rejected.
 
-The carriage return character generated by the Enter key indicates that a
+The carriage return character generated by the
+.key Enter
+key indicates that a
 complete line has been entered, and it is to be interpreted. The listener
 parses the line as a \*(TL expression, evaluates it, and prints the resulting
 value. If the evaluation of the line throws an exception, the listener
@@ -76678,14 +76721,20 @@ such a line
 entered into the history.
 
 The listener does not allow lines containing certain bad syntax to be submitted
-with Enter.  If the buffer contains an expression with unbalanced parentheses
-or brackets, or unterminated literals, then Enter generates a newline character
+with
+.keyn Enter .
+If the buffer contains an expression with unbalanced parentheses
+or brackets, or unterminated literals, then
+.key Enter
+generates a newline character
 which is inserted into the buffer. In that situation, if that newline character
 is being added at the very end of the buffer, the listener flashes the
 exclamation mark character (!) two times to warn the user that line has not
 been submitted: no computation is taking place, and the listener is waiting for
 more input.  It is possible to force the submission of an unbalanced line using
-the sequence Ctrl-X, Ctrl-F.
+the sequence
+.key Ctrl-X
+.keyn Ctrl-F .
 
 .SS* Limitations
 
@@ -76712,7 +76761,9 @@ environment variable is ignored.
 
 .SS* Ways to Quit
 
-Pressing Ctrl-D in a completely empty command line terminates the listener.
+Pressing
+.key Ctrl-D
+in a completely empty command line terminates the listener.
 Another way to quit is to enter the
 .code :quit
 keyword symbol. When the form input into the listener consists of this symbol,
@@ -76751,13 +76802,16 @@ The previous remark about not saving the listener history applies here also.
 
 .SS* Interrupting Evaluation
 
-Ctrl-C typed while editing a command line is interpreted as an editing command
+.key Ctrl-C
+typed while editing a command line is interpreted as an editing command
 which causes that command line to be canceled. The listener prints the string
 .str ** intr
 and repeats the same prompt.
 
 If a command line is submitted for evaluation, the evaluation might take
-a long time or block for input. In these situations, typing Ctrl-C will issue
+a long time or block for input. In these situations, typing
+.key Ctrl-C
+will issue
 an interrupt signal. The listener has installed a handler for this signal which
 generates an exception of type
 .code error
@@ -76765,7 +76819,9 @@ which is caught by the listener. The exception's message is the string
 .str intr
 so that the listener ends up printing
 .str intr **
-like in the case of the Ctrl-C editing command. In this situation, though new
+like in the case of the
+.key Ctrl-C
+editing command. In this situation, though new
 command line prompt is issued with an incremented number, and the exception
 is recorded as a value.
 
@@ -76891,32 +76947,54 @@ or that is immediately to the right of an I-beam cursor.
 
 .NP* Move Left and Right
 
-Moving within the line is achieved using the left and right arrow keys.  In
-addition, Ctrl-B ("back") and Ctrl-F ("forward") perform this movement.
+Moving within the line is achieved using the left and right arrow keys
+.key \[<-]
+and
+.keyn \[->] .
+In addition,
+.key Ctrl-B
+("back") and
+.key Ctrl-F
+("forward") perform this movement.
 
 .NP* Jump to Beginning and End of Line
 
-The Ctrl-A command moves to the beginning of the line. ("A" is the beginning
-of the alphabet). The Ctrl-E ("end") command jumps to the end of the line,
+The
+.key Ctrl-A
+command moves to the beginning of the line. ("A" is the beginning
+of the alphabet). The
+.key Ctrl-E
+("end") command jumps to the end of the line,
 such that the last character of the line is to the left of the cursor
 position. On terminals which have the Home and End keys, these may also
-be used instead of Ctrl-A and Ctrl-E.
+be used instead of
+.key Ctrl-A
+and
+.keyn Ctrl-E .
 
 In line mode, these commands move the cursor to the beginning or end of the
 edit buffer.
 
 In multiline mode, if the cursor is not already at the beginning of a physical
-line, then Ctrl-A moves it to the first character of the physical line.
-Otherwise, Ctrl-A moves the cursor to the beginning of the edit buffer.
+line, then
+.key Ctrl-A
+moves it to the first character of the physical line.
+Otherwise,
+.key Ctrl-A
+moves the cursor to the beginning of the edit buffer.
 
 Similarly, in multiline mode, if the cursor not already at the end of a
-physical line, Ctrl-E moves it there. Otherwise, the cursor moves to the
+physical line,
+.key Ctrl-E
+moves it there. Otherwise, the cursor moves to the
 end of the edit buffer.
 
 .NP* Jump to Matching Parenthesis
 
 If the cursor is on an opening or closing parenthesis, brace or bracket,
-the Ctrl-] command tries to jump to the matching character. The logic for
+the
+.key Ctrl-]
+command tries to jump to the matching character. The logic for
 finding the matching character is identical to that of the Parenthesis Matching
 feature. If no matching character is found, then no movement takes place.
 
@@ -76933,14 +77011,19 @@ outer one.  Otherwise, if the two characters have opposite orientation (one is
 opening and the other closing), then the one which is to the right of the
 cursor position is chosen.
 
-Note: the Ctrl-] character can be produced on some terminals using Ctrl-5
+Note: the
+.key Ctrl-]
+character can be produced on some terminals using
+.key Ctrl-5
 (using the keyboard home row 5, not the numeric keypad 5). This the same
 key which produces the % character when Shift is used. The % character is
 used in the Vi editor for parenthesis matching.
 
 .NP* Character Swap
 
-The Ctrl-T (twiddle) command exchanges the character under the cursor with the
+The
+.key Ctrl-T
+(twiddle) command exchanges the character under the cursor with the
 previous character.
 
 .NP* Delete Character Left
@@ -76949,29 +77032,44 @@ The Backspace key erases the character to the left of the cursor, and moves the
 cursor to the position which that character occupied.
 
 It doesn't matter whether this key generates ASCII
-characters 8 (BS) or 127 (DEL): either one is acceptable. The Ctrl-H command
+characters 8 (BS) or 127 (DEL): either one is acceptable. The
+.key Ctrl-H
+command
 also performs the same action, since it corresponds to ASCII BS.
 
 .NP* Delete Character Right
 
-The Ctrl-D command deletes the character under the cursor, if the cursor
+The
+.key Ctrl-D
+command deletes the character under the cursor, if the cursor
 is block-shaped, or to the right of the cursor if the cursor is an I-beam.
 the cursor maintains its current character position relative to the
-start of the line. In multiline mode, if Ctrl-D is at the end of a line that
+start of the line. In multiline mode, if
+.key Ctrl-D
+is at the end of a line that
 is not the last line, it deletes the newline character, causing the
 following line to be joined to the end of the current line.
-If the cursor is at the end of the buffer, then Ctrl-D does nothing,
+If the cursor is at the end of the buffer, then
+.key Ctrl-D
+does nothing,
 except if the buffer is completely empty, in which case it is a quit
 indication.  The Delete key, if available on the terminal, is a near synonym of
-Ctrl-D. It performs all the same functions, except that it does not
+.keyn Ctrl-D .
+It performs all the same functions, except that it does not
 act as a quit indication; Delete has no effect  when the buffer is empty.
 
-When a visual selection is in effect, then Ctrl-D and Del delete
+When a visual selection is in effect, then
+.key Ctrl-D
+and
+.key Del
+delete
 that selection, and copy it to the clipboard.
 
 .NP* Delete Word Left
 
-The Ctrl-W ("word") command deletes the word to the left of the cursor
+The
+.key Ctrl-W
+("word") command deletes the word to the left of the cursor
 position. More precisely, this command first deletes any consecutive whitespace
 characters (spaces or tabs) to the left of the cursor. Then, it deletes
 consecutive non-whitespace characters. Material under the cursor or to the
@@ -76979,41 +77077,67 @@ right remains. The deleted material is copied into the clipboard.
 
 .NP* Delete to Beginning of Line
 
-The Ctrl-U ("undo typing") command is a "super backspace" operation: it deletes
+The
+.key Ctrl-U
+("undo typing") command is a "super backspace" operation: it deletes
 all characters to the left of the cursor position. The cursor is moved to
-the leftmost position. In multiline mode, Ctrl-U deletes only to the beginning of the current
+the leftmost position. In multiline mode,
+.key Ctrl-U
+deletes only to the beginning of the current
 physical line, not all the way to the first position of the buffer.
-Ctrl-U copies the deleted material into the clipboard.
+.key Ctrl-U
+copies the deleted material into the clipboard.
 
 .NP* Delete to End of Line
 
-The Ctrl-K ("kill") command deletes the character under the cursor position
+The
+.key Ctrl-K
+("kill") command deletes the character under the cursor position
 and all subsequent characters. The cursor position doesn't change.
-In multiline mode, Ctrl-K deletes only until the end of the current
+In multiline mode,
+.key Ctrl-K
+deletes only until the end of the current
 physical line, not the entire buffer.
-The material deleted by Ctrl-K is copied into the clipboard.
+The material deleted by
+.key Ctrl-K
+is copied into the clipboard.
 
 .NP* Verbatim Character Insert
 
-The Ctrl-V ("verbatim") command places the listener's input editor into
+The
+.key Ctrl-V
+("verbatim") command places the listener's input editor into
 a mode in which the next character is interpreted literally and inserted
-into the line, even if that character is a special character such as Enter,
+into the line, even if that character is a special character such as
+.keyn Enter ,
 or a command character.
 
 .NP* Verbatim Insert Mode
-The two-character sequence Ctrl-X, Ctrl-V ("extended verbatim", "super paste")
+The two-character sequence
+.key Ctrl-X
+.key Ctrl-V
+("extended verbatim", "super paste")
 enters into an verbatim insert mode useful for entry of free-form text. It is
 particularly useful in multiline mode. In this mode, almost every character
-is inserted verbatim, including Enter.  The only commands recognized are:
-Ctrl-X, which terminates this mode, Backspace (both ASCII BS and DEL
-variants) and arrow key navigation. Enter inserts a line break, which
+is inserted verbatim, including
+.keyn Enter .
+The only commands recognized are:
+.keyn Ctrl-X ,
+which terminates this mode,
+.key Backspace
+(whether that key generates ASCII BS or DEL) and arrow key navigation.
+.key Enter
+inserts a line break, which
 appears as such in multiline mode, or as
 .code ^M
 in line mode.
 
 .NP* Delete Current Line
 
-The Ctrl-X, Ctrl-K command sequence may be used in multiline mode
+The
+.key Ctrl-X
+.key Ctrl-K
+command sequence may be used in multiline mode
 to delete the entire physical line under the cursor. Any lines below that
 line move up to close the gap. In line mode, the command has no effect,
 other than canceling select mode.  The deleted line, including the
@@ -77030,32 +77154,54 @@ The number of lines retained may be customized using the
 .code *listener-hist-len*
 variable.
 
-If the up arrow is used while editing a line, the contents of the line are
+If the
+.key \[ua]
+key is used while editing a line, the contents of the line are
 placed into a temporary save area.  The line display is then updated to
-show the most recent line of history.  Using the up arrow key additional times
+show the most recent line of history.  Using
+.key \[ua] additional times
 will recall successively less recent lines.
 
-The down arrow key navigates in the opposite direction: from older lines to
-newer lines. When the down arrow key is invoked on the most recent history line,
+The
+.key \[da]
+key navigates in the opposite direction: from older lines to
+newer lines. When
+.key \[da]
+is invoked on the most recent history line,
 then the current line is restored from the temporary save area.
 
-Instead of the up and down arrow keys, the commands Ctrl-P ("previous")
-and Ctrl-N ("next") may be used.
+Instead of
+.key \[ua]
+and
+.keyn \[da] ,
+the commands
+.key Ctrl-P
+("previous")
+and
+.key Ctrl-N
+("next") may be used.
 
-If the Enter key is pressed while a recalled history line is showing, then that
+If the
+.key Enter
+key is pressed while a recalled history line is showing, then that
 line will be submitted as if it were a newly composed line.  The originally
 edited line which had been placed in the save area is discarded.
 
 When a recalled line is showing, it may be edited. There are two important
-behaviors to note here. If a recalled history line is edited, and then the
-up/down arrow keys or a navigation command is used to show a different
+behaviors to note here. If a recalled history line is edited, and then
+.key \[ua]
+or
+.key \[da]
+or a navigation command is used to show a different
 history line, or to restore the original current line, then the edit is made
 permanent: the edited line replaces its original version in the same
 position in the history.  This feature allows corrections to be made to the
 history.
 
 The edit is recorded in the line's undo history as a single change; if the
-edited line is visited again, then a single Ctrl-O command will revert all the
+edited line is visited again, then a single
+.key Ctrl-O
+command will revert all the
 edits that were made.
 
 However, if a recalled line is edited and submitted without navigating to
@@ -77069,7 +77215,9 @@ history line.
 
 .NP* History Search
 It is possible to search backwards through the history interactively
-for a line containing a substring. The Ctrl-R command is used to initiate
+for a line containing a substring. The
+.key Ctrl-R
+command is used to initiate
 search.  The command prompt is replaced with the prefix
 .code search:
 next to which a pair of empty square brackets appears, indicating
@@ -77080,7 +77228,9 @@ In search mode, characters may be typed. They accumulate inside the search
 box, and constitute the string to search for. The listener instantly
 navigates to the most recent line which contains a substring match for the
 search string, and places the cursor on the first character of the
-match. Control characters entered directly are ignored. The Ctrl-V command be
+match. Control characters entered directly are ignored. The
+.key Ctrl-V
+command be
 used to add a character verbatim, as in edit mode.
 
 To remove characters from the search box, Backspace can be used. The
@@ -77094,61 +77244,109 @@ when search mode is initiated. Searches work backward in history from
 that line. If search text is edited by deleting characters and then
 adding new ones, the new search proceeds from the home position.
 
-The Ctrl-R command can be used in search mode. It registers the currently
+The
+.key Ctrl-R
+command can be used in search mode. It registers the currently
 showing line as the new home position, and then repeats the search using the
 existing search text backwards from the new position. If the search text
-is empty, Ctrl-R has no effect.
+is empty,
+.key Ctrl-R
+has no effect.
 
-The Ctrl-C command leaves search mode at any time and causes the
+The
+.key Ctrl-C
+command leaves search mode at any time and causes the
 listener to resume editing the original input at the original character
-position. The Enter key accepts the result of a search and submits it
+position. The
+.key Enter
+key accepts the result of a search and submits it
 as if it were a newly composed line.
 
 Navigation and editing keys may be used in search mode. A navigation or editing
 key immediately cancels search mode, and is processed in edit mode, using
 whatever line was located by the search, at the matching character position.
 
-The Ctrl-L (Clear Screen and Refresh), as well as Ctrl-Z
+The
+.key Ctrl-L
+(Clear Screen and Refresh), as well as
+.key Ctrl-Z
 (Suspend to Background) commands are available in search mode. Their effects
 takes place without leaving search mode.
 
-Navigating to a history line manually using the up and down arrow keys (or
-Ctrl-P/Ctrl-N) has the same net effect same as locating that line using
-Ctrl-R search.
+Navigating to a history line manually using
+.key \[ua]
+or
+.key \[da]
+(or
+.key Ctrl-P
+and
+.keyn Ctrl-N )
+has the same net effect same as locating that line using
+.key Ctrl-R
+search.
 
 .NP* Submit and Stay in History
 
-Normally when the Enter key is used on a recalled history line,
+Normally when the
+.key Enter
+key is used on a recalled history line,
 the next time the listener is reentered, it jumps back to the
 newest history position where a new line is about to be composed.
 
-The alternative command sequence Ctrl-X, Enter provides a useful alternative
+The alternative command sequence
+.key Ctrl-X
+.key Enter
+provides a useful alternative
 behavior. After the submitted line is processed, the listener doesn't jump to
 the newest history position. Instead, it stays in the history, advancing
 forward by one position to the successor of the submitted line.
 
-Ctrl-X, Enter can be used to conveniently submit a range of lines
+.key Ctrl-X
+.key Enter
+can be used to conveniently submit a range of lines
 from the history, one by one, in their original order.
 
 .NP* Insert Previous Word
 
-The equivalent command sequences Ctrl-X, w and Ctrl-X, Ctrl-W insert
+The equivalent command sequences
+.key Ctrl-X
+.key w
+and
+.key Ctrl-X
+.key Ctrl-W
+insert
 a word from the previous line at the cursor position. A word is defined
 as a sequence of non-whitespace characters, separated from other words
 by whitespace. By default, the last word of the previous line is inserted.
-Between the Ctrl-X and Ctrl-W or w, a decimal number can be entered.
+Between the
+.key Ctrl-X
+and the following
+.key Ctrl-W
+or
+.keyn w ,
+a decimal number can be entered.
 The number 1 specifies that the last word is to be inserted, 2 specifies
 the second last word, 3 the third word from the right and so on.
 Only the most recent three decimal digits are retained, so the number can range
 from 0 to 999. A value of 0, or a value which exceeds the number of words
-causes the Ctrl-W or w to do nothing. Note that "previous line" means
+causes the
+.key Ctrl-W
+or
+.key w
+to do nothing. Note that "previous line" means
 relative to the current location in the history. If the 42nd most recent
 history line is currently recalled, this command takes material from the 43rd
 history line.
 
 .NP* Insert Previous Atom
 
-The equivalent command sequences Ctrl-X, a and Ctrl-X, Ctrl-A insert
+The equivalent command sequences
+.key Ctrl-X
+.key a
+and
+.key Ctrl-X
+.key Ctrl-A
+insert
 an atom from the previous line at the cursor position. A line only
 makes atoms available if it expresses a valid \*(TX form, free of syntax
 errors. A line containing only whitespace or a comment makes no atoms
@@ -77158,20 +77356,41 @@ specified in the previous line. The line is flattened into atoms
 as if by the
 .code flatcar
 function. By default, the last atom is extracted. A numeric argument
-typed between the Ctrl-X and Ctrl-A or a can be used to select a
+typed between the
+.key Ctrl-X
+and
+.key Ctrl-A
+or a can be used to select a
 atoms by position from the end. The number 1 specifies the last atom,
 2 the second last and so on.
 Only the most recent three decimal digits are retained, so the number can range
 from 0 to 999. A value of 0, or a value which exceeds the number of words
-causes the Ctrl-A or a to do nothing.  Note that "previous line"
-has the same meaning as for the Ctrl-X, Ctrl-W (insert previous word) command.
+causes the
+.key Ctrl-A
+or a to do nothing.  Note that "previous line"
+has the same meaning as for the
+.key Ctrl-X
+.key Ctrl-W
+(insert previous word) command.
 
 .NP* Insert Previous Line
 
-The command sequences Ctrl-X, Ctrl-R ("repeat") and Ctrl-X, r, which are
+The command sequences
+.key Ctrl-X
+.key Ctrl-R
+("repeat") and
+.key Ctrl-X
+.keyn r ,
+which are
 equivalent, insert an entire line of history into the current buffer. By
 default, the previous line is inserted. A less recent line can be selected by
-typing a numeric argument between the Ctrl-X and the Ctrl-R/r. The immediately
+typing a numeric argument between the
+.key Ctrl-X
+and the
+.key Ctrl-R
+or
+.keyn r .
+The immediately
 previous history line is numbered 1, the one before it 2 and so on.
 If this command is used during history navigation, it references previous
 lines relative to the currently recalled history line.
@@ -77180,9 +77399,16 @@ lines relative to the currently recalled history line.
 
 If the Tab key is pressed while editing a line, it is interpreted as a
 request for completion. There is a second completion command: the
-sequence Ctrl-X, Tab.
+sequence
+.key Ctrl-X
+.keyn Tab .
 
-When completion is invoked with Tab or Ctrl-X, Tab, the listener looks at a few
+When completion is invoked with
+.key Tab
+or
+.key Ctrl-X
+.keyn Tab ,
+the listener looks at a few
 of the trailing characters to the left of the cursor position to determine the
 applicable list of completions. Completions are determined from among the \*(TL symbols which have
 global variable, function, macro and symbolic macro bindings, as well
@@ -77199,7 +77425,12 @@ immediately precede the prefix, then only those symbols are considered
 which are methods: that is, each is the static slot of at least one structure,
 in which that static slots holds a function.
 
-The difference between Tab and Ctrl-X, Tab is that Tab completion looks only for
+The difference between
+.key Tab
+and
+.key Ctrl-X
+.key Tab
+is that Tab completion looks only for
 prefix matches among the eligible identifiers. Thus it is a pure completion in
 the sense that it suggests additional material that may follow what has been
 typed. If the buffer contains
@@ -77213,7 +77444,10 @@ and
 .codn list-str .
 It will not suggest identifiers which rewrite the
 .code list
-prefix.  By contrast, the Ctrl-X, Tab completion suggests not only pure
+prefix.  By contrast, the
+.key Ctrl-X
+.key Tab
+completion suggests not only pure
 completions but also alternatives to the partial identifier, by looking for
 substring matches. For instance
 .code copy-list
@@ -77229,11 +77463,17 @@ editing mode.
 If completions are found, listener enters into completion selection mode.
 The first available completion is placed into the line as if it had been typed
 in.  The other completions may be viewed one by one using the Tab key.
-(Note that the Ctrl-X is not used, only Tab, even if completion mode had been
-entered via Ctrl-X, Tab).
+(Note that the
+.key Ctrl-X
+is not used, only Tab, even if completion mode had been
+entered via
+.key Ctrl-X
+.keyn Tab ).
 When the completions are exhausted, the original uncompleted line is shown
 again, and Tab can continue to be used to cycle through the completions again.
-In completion mode, the Ctrl-C character acts as a command to cancel completion mode
+In completion mode, the
+.key Ctrl-C
+character acts as a command to cancel completion mode
 and return to editing the original uncompleted line. Any other input character causes
 the listener to keep the currently shown completion, and return to edit mode,
 where that character is immediately processed as if it had been typed in
@@ -77241,7 +77481,10 @@ edit mode.
 
 .NP* Edit with External Editor
 
-The two character command Ctrl-X, Ctrl-E launches an external editor to
+The two character command
+.key Ctrl-X
+.key Ctrl-E
+launches an external editor to
 edit the current command line. The command line is stored in a temporary
 file first, and the editor is invoked on this file. When the editor
 terminates, the file is read into the editing buffer.
@@ -77268,7 +77511,9 @@ content is handled properly. (See the following section, Multiline Mode).
 
 .NP* Undo Editing
 
-The listener provides an undo feature.  The Ctrl-O command ("old", "oops")
+The listener provides an undo feature.  The
+.key Ctrl-O
+command ("old", "oops")
 restores the edit buffer contents and cursor position to a previous state.
 
 There is a single undo history which records up the 200 most recent edit
@@ -77277,7 +77522,9 @@ appears that each line has its own, independent undo history.
 Undoing the edits in one line has no effect on the undo history of another
 line.
 
-Undo also records edits for lines that have been canceled with Ctrl-C, and are
+Undo also records edits for lines that have been canceled with
+.key Ctrl-C
+and are
 not entered into the history, making it possible to recall canceled lines.
 
 The undo history is lost when \*(TX terminates.
@@ -77293,7 +77540,9 @@ buffer. This is in contrast to the way new edits work. New edits are not
 committed to history until navigation takes place to a different history line.
 
 Also note that when new edits are performed on a historic line and it is
-submitted with Enter without navigating to another line, the undo information
+submitted with
+.key Enter
+without navigating to another line, the undo information
 for those edits is retained, and belongs to the newly submitted line.  The
 historic line hasn't actually been modified, and so it has no new undo
 information.  However, if a historic line is edited, and then navigation takes
@@ -77311,7 +77560,9 @@ of their usual target, or upon both the target and the selection.
 
 .NP* Making a Selection
 
-The Ctrl-S command enters into visual selection mode and marks the
+The
+.key Ctrl-S
+command enters into visual selection mode and marks the
 starting point of the selection, which is considered the position
 immediately to the left of the current character.
 
@@ -77321,7 +77572,9 @@ tracks the movement.
 
 The selected text is displayed in reverse video.
 
-Typing Ctrl-S again while in visual selection mode cancels
+Typing
+.key Ctrl-S
+again while in visual selection mode cancels
 the mode.
 
 Tab completion, history navigation, history search and editing in an external
@@ -77348,14 +77601,18 @@ between characters, and that these characters are included in the selection.
 .NP* Selection Endpoint Toggle
 
 In visual selection, the starting point of the selection remains fixed, while
-the ending point tracks the movement of the cursor. The Ctrl-^ command will
+the ending point tracks the movement of the cursor. The
+.key Ctrl-^
+command will
 exchange the two points. The effect is that the cursor jumps to the opposite
 end of the selection. That end is now the ending point which tracks the cursor
 movement.
 
 .NP* Visual Copy
 
-The Ctrl-Y command ("yank") copies the selected text into a clipboard buffer.
+The
+.key Ctrl-Y
+command ("yank") copies the selected text into a clipboard buffer.
 The previous contents of the clipboard buffer, if any, are discarded.
 
 Unlike the history, the clipboard buffer is not persisted.
@@ -77363,17 +77620,24 @@ If \*(TX terminates, it is lost.
 
 .NP* Visual Cut
 
-If the Ctrl-D command is invoked while a selection is in effect, then
+If the
+.key Ctrl-D
+command is invoked while a selection is in effect, then
 instead of deleting the character under the cursor, it deletes the
 selection, and copies it to the clipboard. The Delete key has the same
 effect.
 
-Ctrl-D and Del have no effect on the clipboard when visual selection is not in
+.key Ctrl-D
+and
+.key Del
+have no effect on the clipboard when visual selection is not in
 effect, and they operate on just one character.
 
 .NP* Clipboard Paste
 
-The Ctrl-Q command ("quote the clipboard") inserts text from the clipboard
+The
+.key Ctrl-Q
+command ("quote the clipboard") inserts text from the clipboard
 at the current cursor position. The cursor position is updated to
 be immediately after the inserted text.  The clipboard text remains available
 for further pasting.
@@ -77383,15 +77647,21 @@ session, then this command has no effect.
 
 .NP* Clipboard Swap Paste
 
-The Ctrl-X, Ctrl-Q command sequence ("exchange quote") exchanges the
+The
+.key Ctrl-X
+.key Ctrl-Q
+command sequence ("exchange quote") exchanges the
 selected text with the contents of the clipboard. The selection is
-copied into the clipboard as if by Ctrl-Y and replaced by the
+copied into the clipboard as if by
+.key Ctrl-Y
+and replaced by the
 previous contents of the clipboard.
 
 If the clipboard has not yet been used in the current session,
 
 If nothing has been yet been copied to the clipboard in the current
-session, then this command behaves like Ctrl-Y:
+session, then this command behaves like
+.keyn Ctrl-Y :
 text is yanked into the clipboard, but not deleted.
 
 .NP* Visual Replace
@@ -77402,8 +77672,12 @@ selection is first deleted and visual mode is canceled. Then the insertion
 takes place and visual mode is canceled. The effect is that the newly inserted
 text replaces the selected text.
 
-This applies to the Clipboard Paste (Ctrl-Q) command also. If a
-selection is effect when Ctrl-Q is invoked, the selected text
+This applies to the Clipboard Paste
+.key Ctrl-Q
+command also. If a
+selection is effect when
+.key Ctrl-Q
+is invoked, the selected text
 is replaced with the clipboard buffer contents.
 
 When a selection is replaced in this manner, the contents
@@ -77413,22 +77687,32 @@ of the clipboard are unaffected.
 
 In visual mode, it is possible to issue commands which delete text.
 
-One such command is Ctrl-D. Its special behavior in selection mode,
+One such command is
+.keyn Ctrl-D .
+Its special behavior in selection mode,
 Visual Cut, is described above.
 
-The Backspace key and Ctrl-H also have a special behavior in select mode. If
+The
+.key Backspace
+key and
+.key Ctrl-H
+also have a special behavior in select mode. If
 the cursor is at the rightmost endpoint of the selection, then these commands
 delete the selection and nothing else.  If the cursor is at the leftmost
 endpoint of the selection, then these commands delete the selection, and take
 their usual effect of deleting a character also.  In both cases, selection mode
 is canceled. The clipboard is not affected.
 
-The Ctrl-W command for deleting the previous word, when used in visual
+The
+.key Ctrl-W
+command for deleting the previous word, when used in visual
 selection mode, deletes the selection and cancels selection mode,
 and then deletes the word before the selection. Only the deleted
 selection is copied into the clipboard, not the deleted word.
 
-All other deletion commands such as Ctrl-K simply cancel visual
+All other deletion commands such as
+.key Ctrl-K
+simply cancel visual
 selection mode and take their usual effect.
 
 .SS* Multiline Mode
@@ -77439,7 +77723,9 @@ This is determined by the special variable
 whose default value is
 .code t
 (multiline mode).  It is possible to toggle between
-line mode and multiline mode using the Ctrl-J command.
+line mode and multiline mode using the
+.key Ctrl-J
+command.
 
 In line mode, all input given to a single prompt appears to be on a single
 line. When the line becomes longer than the screen width, it scrolls
@@ -77459,14 +77745,20 @@ Because carriage returns are not line terminators in text files,
 lines which contain embedded carriage returns are correctly saved
 into and retrieved from the persistent history file.
 
-When Enter is typed in multiline mode, the listener tries to determine whether
+When
+.key Enter
+is typed in multiline mode, the listener tries to determine whether
 the current input, taken as a whole, is an incomplete expression which requires
 closing punctuation for elements like compound expressions and string literals.
 
-If the input appears incomplete, then the Enter is inserted verbatim at
+If the input appears incomplete, then the
+.key Enter
+is inserted verbatim at
 the current cursor position, rather than signaling that the line is
-being submitted for evaluation. The Ctrl-X, Enter command sequence also has
-this behavior.
+being submitted for evaluation. The
+.key Ctrl-X
+.key Enter
+command sequence also has this behavior.
 
 .SS* Reading Forms Directly from the Terminal
 
@@ -77479,7 +77771,8 @@ If the
 keyword is entered into the listener, it will temporarily suspend
 interactive editing and allow the \*(TL parser to read
 directly from standard input. The reading stops when an error occurs,
-or EOF is indicated by entering Ctrl-D.
+or EOF is indicated by entering
+.keyn Ctrl-D .
 
 In direct parsing mode, each expression which is read is evaluated, but its
 value is not printed. However, the value of the last form evaluated is returned
@@ -77495,13 +77788,17 @@ command which triggers this parsing mode appears in the history.
 
 .SS* Clear Screen and Refresh
 
-The Ctrl-L command clears the screen and redraws the line being edited.
+The
+.key Ctrl-L
+command clears the screen and redraws the line being edited.
 This is useful when the display is disturbed by the output of some
 background process, or serial line noise.
 
 .SS* Suspend to Background
 
-The Ctrl-Z ("Zzzz... (sleep)") command causes \*(TX to be placed into the
+The
+.key Ctrl-Z
+("Zzzz... (sleep)") command causes \*(TX to be placed into the
 background in a suspended, and control returned to the system shell.
 
 Bringing the suspended \*(TX back into the foreground is achieved with a shell
@@ -77519,11 +77816,25 @@ user to lose interactive control over that \*(TX instance.
 
 .SS* Editing Help
 
-The Ctrl-X, ? command shows a summary of commands, in a four-line
+The
+.key Ctrl-X
+.key ?
+command shows a summary of commands, in a four-line
 display which temporarily replaces the editing area. The help text
-is divided into several pages. Ctrl-C dismisses the display, and
-returns to editing. The Ctrl-P, left arrow and up arrow keys return
-to the previous screen. The Ctrl-Z and Ctrl-L commands are available,
+is divided into several pages.
+.key Ctrl-C
+dismisses the display, and
+returns to editing. The
+.keyn Ctrl-P ,
+.key \[<-]
+and
+.key \[ua]
+keys return
+to the previous screen. The
+.key Ctrl-Z
+and
+.key Ctrl-L
+commands are available,
 having their usual meaning of suspending and refreshing the display.
 Any other key advances to the next screen.
 Advancing from the last screen, dismisses the display, and returns
-- 
cgit v1.2.3