From c971c428f31a4b1c37d0d1058ff7a75a4c215960 Mon Sep 17 00:00:00 2001 From: Jacob Nevins Date: Sun, 4 Feb 2018 12:27:17 +0000 Subject: [PATCH] Update copy and paste documentation. Rewrite the "Using PuTTY" section for 'clipboard-generality', and also explain why we default to mouse-based selection, interaction with other applications via PRIMARY when running PuTTY on Unix, and bracketed-paste mode. Also add lots of index terms. --- doc/config.but | 45 ++++++++++++++++++++++++--------------------- doc/index.but | 19 ++++++++++++++++++- doc/using.but | 48 ++++++++++++++++++++++++++++++++---------------- 3 files changed, 74 insertions(+), 38 deletions(-) diff --git a/doc/config.but b/doc/config.but index 79036582..f22a9667 100644 --- a/doc/config.but +++ b/doc/config.but @@ -1405,7 +1405,7 @@ disabled. \cfg{winhelp-topic}{selection.buttons} PuTTY's copy and paste mechanism is by default modelled on the Unix -\c{xterm} application. The X Window System uses a three-button mouse, +\i\c{xterm} application. The X Window System uses a three-button mouse, and the convention is that the \i{left button} \I{selecting text}selects, the \i{right button} extends an existing selection, and the \i{middle button} pastes. @@ -1474,21 +1474,24 @@ you have to hold down Alt to get the \e{normal} behaviour. Here you can configure which clipboard(s) are written or read by PuTTY's various copy and paste actions. -The X Window System provides multiple clipboards (or \q{selections}), -and many applications support more than one of them by a different -user interface mechanism. +The X Window System (which underlies most Unix graphical interfaces) +provides multiple clipboards (or \q{\i{selections}}), and many +applications support more than one of them by a different user +interface mechanism. -The two most commonly used selections are called \cq{PRIMARY} and -\cq{CLIPBOARD}; in applications supporting both, the usual behaviour -is that \cw{PRIMARY} is used by mouse-only actions (selecting text -automatically copies it to \cw{PRIMARY}, and middle-clicking pastes -from \cw{PRIMARY}), whereas \cw{CLIPBOARD} is used by explicit Copy -and Paste menu items or keypresses such as Ctrl-C and Ctrl-V. +The two most commonly used selections are called \cq{\i{PRIMARY}} and +\cq{\I{CLIPBOARD selection}CLIPBOARD}; in applications supporting both, +the usual behaviour is that \cw{PRIMARY} is used by mouse-only actions +(selecting text automatically copies it to \cw{PRIMARY}, and +\i{middle-clicking} pastes from \cw{PRIMARY}), whereas \cw{CLIPBOARD} +is used by explicit Copy and Paste menu items or keypresses such as +\i{Ctrl-C} and \i{Ctrl-V}. -On other platforms, where there is a single system clipboard, PuTTY -provides a second clipboard-like facility by permitting you to paste -the text you last selected in \e{this window}, whether or not it is -currently also in the system clipboard. +On other platforms such as Windows, where there is a single system +clipboard, PuTTY provides a second clipboard-like facility by permitting +you to paste the text you last selected in \e{this window}, whether or +not it is currently also in the system clipboard. This is not enabled +by default. \S2{config-selection-autocopy} \q{Auto-copy selected text} @@ -1512,15 +1515,15 @@ will \e{also} be placed in \cq{CLIPBOARD} at the same time. PuTTY has three user-interface actions which can be configured to paste into the terminal (not counting menu items). You can click whichever mouse button (if any) is configured to paste (see -\k{config-mouse}); you can press Shift-Ins; or you can press -Ctrl-Shift-V, although that action is not enabled by default. +\k{config-mouse}); you can press \i{Shift-Ins}; or you can press +\i{Ctrl-Shift-V}, although that action is not enabled by default. You can configure which of the available clipboards each of these actions pastes from (including turning the paste action off completely). On platforms with a single system clipboard, the available options are to paste from that clipboard or to paste from -PuTTY's internal memory of the last selected text within that window. -On X, the standard options are \cw{CLIPBOARD} or \cw{PRIMARY}. +PuTTY's internal memory of the \i{last selected text} within that +window. On X, the standard options are \cw{CLIPBOARD} or \cw{PRIMARY}. (\cw{PRIMARY} is conceptually similar in that it \e{also} refers to the last selected text \dash just across all applications instead of @@ -1528,11 +1531,11 @@ just this window.) The two keyboard options each come with a corresponding key to copy \e{to} the same clipboard. Whatever you configure Shift-Ins to paste -from, Ctrl-Ins will copy to the same location; similarly, Ctrl-Shift-C -will copy to whatever Ctrl-Shift-V pastes from. +from, \i{Ctrl-Ins} will copy to the same location; similarly, +\i{Ctrl-Shift-C} will copy to whatever Ctrl-Shift-V pastes from. On X, you can also enter a selection name of your choice. For example, -there is a rarely-used standard selection called \cq{SECONDARY}, which +there is a rarely-used standard selection called \cq{\i{SECONDARY}}, which Emacs (for example) can work with if you hold down the Meta key while dragging to select or clicking to paste; if you configure a PuTTY keyboard action to access this clipboard, then you can interoperate diff --git a/doc/index.but b/doc/index.but index 0877ee90..96d57809 100644 --- a/doc/index.but +++ b/doc/index.but @@ -73,7 +73,7 @@ from SSH and Telnet \IM{three-button mouse} mouse, three-button \IM{left mouse button}{left button} left mouse button -\IM{middle mouse button}{middle button} middle mouse button +\IM{middle mouse button}{middle button}{middle-clicking} middle mouse button \IM{right mouse button}{right button} right mouse button \IM{selecting words}{word-by-word selection} selecting whole words @@ -92,6 +92,18 @@ from SSH and Telnet \IM{right mouse button, with Ctrl} right mouse button, with Ctrl \IM{right mouse button, with Ctrl} Ctrl, with right mouse button +\IM{selections} selections, multiple +\IM{selections} clipboards, multiple + +\IM{PRIMARY} \c{PRIMARY} selection +\IM{PRIMARY} selection, \c{PRIMARY} + +\IM{CLIPBOARD selection} \c{CLIPBOARD} selection +\IM{CLIPBOARD selection} selection, \c{CLIPBOARD} + +\IM{SECONDARY} \c{SECONDARY} selection +\IM{SECONDARY} selection, \c{SECONDARY} + \IM{system menu} system menu \IM{system menu} menu, system \IM{system menu} window menu @@ -342,6 +354,11 @@ saved sessions from \IM{remote-controlled printing} printing, remote-controlled \IM{remote-controlled printing} passthrough printing +\IM{Control-H} Control-H +\IM{Control-H} Ctrl-H +\IM{Control-?} Control-? +\IM{Control-?} Ctrl-? + \IM{Home and End keys} Home key \IM{Home and End keys} End key diff --git a/doc/using.but b/doc/using.but index f5e3b57b..1f31b7c4 100644 --- a/doc/using.but +++ b/doc/using.but @@ -21,27 +21,31 @@ the \I{Windows clipboard}Windows \i{clipboard}, so that you can paste (for example) URLs into a web browser, or paste from a word processor or spreadsheet into your terminal session. -PuTTY's copy and paste works entirely with the \i{mouse}. In order -to copy text to the clipboard, you just click the \i{left mouse -button} in the \i{terminal window}, and drag to \I{selecting text}select -text. When you let go of the button, the text is \e{automatically} -copied to the clipboard. You do not need to press Ctrl-C or -Ctrl-Ins; in fact, if you do press Ctrl-C, PuTTY will send a Ctrl-C -character down your session to the server where it will probably -cause a process to be interrupted. +By default, PuTTY's copy and paste works entirely with the \i{mouse}. +(This will be familiar to people who have used \i\c{xterm} on Unix.) +In order to copy text to the clipboard, you just click the \i{left +mouse button} in the \i{terminal window}, and drag to +\I{selecting text}select text. When you let go of the button, the text +is \e{automatically} copied to the clipboard. You do not need to press +\i{Ctrl-C} or \i{Ctrl-Ins}; in fact, if you do press Ctrl-C, PuTTY will +send a Ctrl-C character down your session to the server where it will +probably cause a process to be interrupted. -Pasting is done using the right button (or the middle mouse button, -if you have a \i{three-button mouse} and have set it up; see +Pasting into PuTTY is done using the right button (or the middle mouse +button, if you have a \i{three-button mouse} and have set it up; see \k{config-mouse}). (Pressing \i{Shift-Ins}, or selecting \q{Paste} from the \I{right mouse button, with Ctrl}Ctrl+right-click \i{context menu}, have the same effect.) When you click the \i{right mouse button}, PuTTY will read whatever is in -the Windows clipboard and paste it into your session, \e{exactly} as -if it had been typed at the keyboard. (Therefore, be careful of -pasting formatted text into an editor that does automatic indenting; -you may find that the spaces pasted from the clipboard plus the -spaces added by the editor add up to too many spaces and ruin the -formatting. There is nothing PuTTY can do about this.) +the Windows clipboard and paste it into your session. By default, this +behaves \e{exactly} as if the clipboard contents had been typed at the +keyboard; therefore, be careful of pasting formatted text into an +editor that does automatic \i{indenting}, as you may find that the spaces +pasted from the clipboard plus the spaces added by the editor add up +to too many spaces and ruin the formatting. (Some remote applications +can ask PuTTY to identify text that is being pasted, to avoid this +sort of problem; but if your application does not, there is nothing +PuTTY can do to avoid this.) If you \i{double-click} the left mouse button, PuTTY will \I{selecting words}select a whole word. If you double-click, hold @@ -69,6 +73,15 @@ middle mouse button to paste, then the right mouse button does this instead.) Click the button on the screen, and you can pick up the nearest end of the selection and drag it to somewhere else. +If you are running PuTTY itself on Unix (not just using it to connect +to a Unix system from Windows), by default you will likely have to use +similar mouse actions in other applications to paste the text you +copied from PuTTY, and to copy text for pasting into PuTTY; actions +like \i{Ctrl-C} and Ctrl-V will likely not behave as you expect. +\K{config-clipboards} explains why this is, and how you can change the +behaviour. (On Windows there is only a single selection shared with other +applications, so this confusion does not arise.) + It's possible for the server to ask to \I{mouse reporting}handle mouse clicks in the PuTTY window itself. If this happens, the \i{mouse pointer} will turn into an arrow, and using the mouse to copy and paste will only @@ -76,6 +89,9 @@ work if you hold down Shift. See \k{config-features-mouse} and \k{config-mouseshift} for details of this feature and how to configure it. +You can customise much of this behaviour, for instance to enable copy +and paste from the keyboard; see \k{config-selection}. + \S{using-scrollback} \I{scrollback}Scrolling the screen back PuTTY keeps track of text that has scrolled up off the top of the