acme: shift button 3 for reverse search

An experiment. Let's see if it's any good.
Also document the Mac conventions in devdraw(3).

3 files changed, 79 insertions, 17 deletions

diff --git a/man/man1/0intro.1 b/man/man1/0intro.1
index 8c520d9d..ad851a5f 100644
--- a/man/man1/0intro.1
+++ b/man/man1/0intro.1
@@ -29,7 +29,7 @@ conventionally
 When programs need to access files in the tree,
 they expect the
 .B $PLAN9
-environment variable 
+environment variable
 to contain the name of the root of the tree.
 See
 .MR install (1)
@@ -57,7 +57,7 @@ expect Plan 9 regular expressions
 (see
 .MR regexp (7) ),
 which are closest to what Unix calls extended regular expressions.
-Because of these differences, it is not recommended to put 
+Because of these differences, it is not recommended to put
 .B $PLAN9/bin
 before the usual system
 .B bin
@@ -99,6 +99,11 @@ The argument is one of
 \fL'\fIxmin ymin xmax ymax\fL'\fR,
 \fRor
 \fIxmin\fL,\fIymin\fL,\fIxmax\fL,\fIymax\fR.
+See
+.MR devdraw (1)
+and
+.MR keyboard (7)
+for details about typing and clicking in graphical applications.
 .PP
 The
 .MR plumber (4)
@@ -135,7 +140,7 @@ is an experimental client for acme.
 Some programs rely on large databases that would be
 cumbersome to include in every release.
 Scripts are provided that download these databases separately.
-These databases can be downloaded separately.  
+These databases can be downloaded separately.
 See
 .B $PLAN9/dict/README
 and
@@ -148,7 +153,7 @@ and
 (see
 .MR 9c (1) )
 provide a simple interface to the underlying system compiler and linker,
-similar to the 
+similar to the
 .I 2c
 and
 .I 2l
@@ -201,7 +206,7 @@ cannot)
 and dump data structures,
 but that it is the extent to which they have been developed and exercised.
 .SS Porting programs
-The vast majority of the familiar Plan 9 programs 
+The vast majority of the familiar Plan 9 programs
 have been ported, including the Unicode-aware
 .MR troff (1) .
 .PP
@@ -222,7 +227,7 @@ is in progress; see
 .SS Porting to new systems
 Porting the tree to new operating systems or architectures
 should be straightforward, as system-specific code has been
-kept to a minimum.  
+kept to a minimum.
 The largest pieces of system-specific code are
 .BR <u.h> ,
 which must include the right system files and
@@ -231,7 +236,7 @@ and
 .IR libthread ,
 which must implement spin locks, operating system thread
 creation, and context switching routines.
-Portable implementations of these using 
+Portable implementations of these using
 .B <pthread.h>
 and
 .B <ucontext.h>
@@ -259,7 +264,7 @@ so that the Unix
 utility can handle it.
 Some systems, for example Debian Linux,
 deduce the man page locations from the search path, so that
-adding 
+adding
 .B $PLAN9/bin
 to your path is sufficient to cause
 .B $PLAN9/man
diff --git a/man/man1/acme.1 b/man/man1/acme.1
index 852a8f7f..bb2c89d6 100644
--- a/man/man1/acme.1
+++ b/man/man1/acme.1
@@ -588,6 +588,9 @@ not just
 or
 .BR 127 .
 (There is an easier way to locate literal text; see below.)
+If shift is held down during the selection or click,
+any leading regular expression search defaults to
+searching backward in the text instead of forward.
 .PP
 If the text is a file name followed by a colon and an address,
 .I acme
@@ -608,6 +611,8 @@ moved there.  Thus, to search for occurrences of a word in a file,
 just click button 3 on the word.  Because of the rule of using the
 selection as the button 3 action, subsequent clicks will find subsequent
 occurrences without moving the mouse.
+If shift is held down during the selection or click,
+the search looks backward in the file.
 .PP
 In all these actions, the mouse motion is not done if the text is a null string
 within a non-null selected string in the tag, so that (for example) complex regular expressions
diff --git a/man/man1/devdraw.1 b/man/man1/devdraw.1
index da36b8e2..e606b3e2 100644
--- a/man/man1/devdraw.1
+++ b/man/man1/devdraw.1
@@ -2,7 +2,7 @@
 .SH NAME
 devdraw \- draw device simulator
 .SH SYNOPSIS
-invoked via 
+invoked via
 .I initdraw
 (see
 .MR graphics (3) )
@@ -10,19 +10,71 @@ invoked via
 .I Devdraw
 serves a custom graphics protocol and is the only program
 that talks directly to X window servers.
-On Macintosh, setting
-.BI devdrawretina
-to
-.BI 1
-will cause
-.I devdraw
-to use all available physical pixels on a retina display.
+.PP
+.SS "Apple macOS
+.PP
+On macOS, because a laptop trackpad click only has one button (the trackpad itself)
+Option-click is button 2, and Command-click is button 3.
+While the main mouse button is held down,
+Control, Option, and Command serve as simulated buttons 1, 2, 3 for chording in
+.MR acme (4) .
+For example, the 1-3 pasting chord in acme can be executed by
+highlighting text while holding down the trackpad button
+and then, while still holding down the button, pressing the Command key.
+.PP
+As usual, buttons 4 and 5 represent a scroll wheel.
+Two-finger scrolling on the trackpad sends those button events.
+.PP
+Holding down shift while clicking adds 5 to the button number.
+For example, Command-Click is button 3, so Command-Shift-Click is button 8.
+Most programs do not respond to those buttons; one notable exception is
+.MR acme (1) ,
+which interprets button 8 (shifted button 3) as a reverse search.
+.PP
+Typing Command-F toggles full screen mode.
+.PP
+.I Devdraw
+automatically detects high-resolution (retina) displays.
+For debugging, typing Command-R toggles retina mode.
+.PP
+Other than the special cases mentioned above,
+holding down Command while typing a character
+.B Kcmd
+(0xF100)
+plus that character.
+Some programs (notably
+.IR acme (1))
+recognize standard keyboard shortcuts such as
+Command-Z (undo), Command-Shift-Z (redo),
+Command-X (cut), and Command-V (paste).
+.SS "X Windows
+.PP
+On Unix systems, Control-click is mouse button 2,
+and Alt-click is mouse button 3.
+While the main mouse button is held down,
+Control and Alt serve as simulated buttons 2, 3 for chording in
+.MR acme (4) .
+For example, the 1-3 pasting chord in acme can be executed by
+highlighting text while holding down the trackpad button
+and then, while still holding down the button, pressing the Alt key.
+.PP
+Because the Control and Alt keys have other meanings
+(see
+.MR keyboard (7)
+for the Alt key's meaning)
+and there is no third modifier key like on the Mac,
+there is no way to type
+.B Kcmd
+variants,
+so there is no access to keyboard shortcuts for
+undo, redo, cut, and paste.
 .SH SOURCE
 .B \*9/src/cmd/devdraw
 .SH "SEE ALSO
 .MR draw (3) ,
 .MR drawfcall (3) ,
-.MR graphics (3)
+.MR graphics (3) ,
+.MR keyboard (7)
 .SH BUGS
 .I Devdraw
 should probably present a standard 9P server