mdw@git.distorted.org.uk Git - sgt/utils/blob - xcopy/xcopy.but

   1 \cfg{man-identity}{xcopy}{1}{2004-08-02}{Simon Tatham}{Simon Tatham}
   2 \cfg{man-mindepth}{1}
   3
   4 \C{xcopy-manpage} Man page for \cw{xcopy}
   5
   6 \H{xcopy-manpage-name} NAME
   7
   8 \cw{xcopy} - read and write text to/from an X selection from the
   9 command line
  10
  11 \H{xcopy-manpage-synopsis} SYNOPSIS
  12
  13 \c xcopy [ -r ] [ -u | -c ] [ -C ]
  14 \e bbbbb   bb     bb   bb     bb
  15
  16 \H{xcopy-manpage-description} DESCRIPTION
  17
  18 \cw{xcopy} is a command-line utility for manipulating the X selection.
  19
  20 It has two basic modes. In read mode (\cw{xcopy -r}), it connects to
  21 your X server, retrieves the contents of the selection as plain
  22 text, and writes it on standard output. You would then typically
  23 redirect its output into a file, or pipe it into some other program.
  24
  25 In write mode (just \cw{xcopy}, if \cw{-r} is not specified), it
  26 will read data from standard input, then connect to your X server
  27 and place that data in the selection as plain text. So you can pipe
  28 data into \cw{xcopy}, move to another application, and press Paste.
  29
  30 The X selection model requires the selection-owning client to remain
  31 connected to the server and hand out its data on request. Therefore,
  32 \cw{xcopy} in write mode forks off a background process which does
  33 this. The background process terminates once it is no longer the
  34 selection owner (i.e. as soon as you select data in another
  35 application), or if your X session finishes. Normally you can ignore
  36 its presence, although it might become important to be aware of it
  37 if (for example) the \cw{xcopy} background process were to be the
  38 last X client still connected through an SSH tunnel.
  39
  40 \cw{xcopy} currently only handles text data. However, it is capable
  41 of handling it in the form of plain text, UTF-8, or compound
  42 (multiple-character-set) text. Use the \cw{-u}, \cw{-c} and \cw{-C}
  43 options to control this aspect of its behaviour.
  44
  45 \H{xcopy-manpage-options} OPTIONS
  46
  47 By default (if \cw{-r} is not supplied), \cw{xcopy} operates in
  48 write mode.
  49
  50 \dt \cw{-r}
  51
  52 \dd Places \cw{xcopy} into read mode.
  53
  54 By default (if neither \cw{-c} nor \cw{-u} is supplied), \cw{xcopy}
  55 reads and writes the selection using the type \cw{STRING}, which
  56 means that the input or output data is expected to be encoded in
  57 ISO-8859-1.
  58
  59 \dt \cw{-u}
  60
  61 \dd In read mode, causes \cw{xcopy} to request the selection using
  62 the type \cw{UTF8_STRING}, which typically means that the returned
  63 data will be encoded as UTF-8. In write mode, causes \cw{xcopy} to
  64 \e{give out} the selection as type \cw{UTF8_STRING}, meaning that
  65 the data piped in to it is expected to be encoded as UTF-8.
  66
  67 \dt \cw{-c}
  68
  69 \dd Similar to \cw{-u}, but uses the type \cw{COMPOUND_TEXT} rather
  70 than \cw{UTF8_STRING}. \cw{COMPOUND_TEXT} is a complex
  71 multi-character-set encoding similar to ISO 2022, and is unlikely to
  72 be a very useful form in which to pass data to or from non-X
  73 programs. However, it might occasionally be useful to retrieve a
  74 compound text selection using \cw{xcopy -r -c}, and later on return
  75 it to the X selection using \cw{xcopy -c} so it can be pasted back
  76 into a different application.
  77
  78 In write mode, if \cw{xcopy} is operating in \cw{STRING} mode and a
  79 pasting application requests the selection as \cw{COMPOUND_TEXT},
  80 \cw{xcopy} will convert the data automatically. This is normally
  81 what you want.
  82
  83 \dt \cw{-C}
  84
  85 \dd Suppresses conversion to compound text in write mode. This is
  86 occasionally useful if you are pasting control characters, since the
  87 compound text specification forbids any control characters and the
  88 Xlib conversion functions honour this. If you are (for example)
  89 trying to paste a sequence of editor commands into a terminal
  90 window, you might well want to paste a string full of escape
  91 sequences and control characters, in which case you may need to use
  92 \cw{-C} to disable conversion to compound text.
  93
  94 \H{xcopy-manpage-bugs} BUGS
  95
  96 Occasionally \cw{xcopy -r} completely fails to notice selection data
  97 owned by another process. I have not yet reproduced this reliably;
  98 if anyone can, some work with \cw{xmon}(1) would be much
  99 appreciated...
 100
 101 Automatic conversion between compound text and UTF-8 is not
 102 currently supported. There are Xlib functions to do it, although
 103 they don't appear to work very well (missing out many characters
 104 which they could have converted).