Import my usual \dash macro into all these man pages, and use it for

[sgt/utils] / xcopy / xcopy.but

\cfg{man-identity}{xcopy}{1}{2004-08-02}{Simon Tatham}{Simon Tatham}

\define{dash} \u2013{-}

\title Man page for \cw{xcopy}

\U NAME

\cw{xcopy} \dash read and write text to/from an X selection from the
command line

\U SYNOPSIS

\c xcopy [ -r ] [ -u | -c ] [ -C ]
\e bbbbb   bb     bb   bb     bb

\U DESCRIPTION

\cw{xcopy} is a command-line utility for manipulating the X selection.

It has two basic modes. In read mode (\cw{xcopy -r}), it connects to
your X server, retrieves the contents of the selection as plain
text, and writes it on standard output. You would then typically
redirect its output into a file, or pipe it into some other program.

In write mode (just \cw{xcopy}, if \cw{-r} is not specified), it
will read data from standard input, then connect to your X server
and place that data in the selection as plain text. So you can pipe
data into \cw{xcopy}, move to another application, and press Paste.

The X selection model requires the selection-owning client to remain
connected to the server and hand out its data on request. Therefore,
\cw{xcopy} in write mode forks off a background process which does
this. The background process terminates once it is no longer the
selection owner (i.e. as soon as you select data in another
application), or if your X session finishes. Normally you can ignore
its presence, although it might become important to be aware of it
if (for example) the \cw{xcopy} background process were to be the
last X client still connected through an SSH tunnel.

\cw{xcopy} currently only handles text data. However, it is capable
of handling it in the form of plain text, UTF-8, or compound
(multiple-character-set) text. Use the \cw{-u}, \cw{-c} and \cw{-C}
options to control this aspect of its behaviour.

\U OPTIONS

By default (if \cw{-r} is not supplied), \cw{xcopy} operates in
write mode.

\dt \cw{-r}

\dd Places \cw{xcopy} into read mode.

By default (if neither \cw{-c} nor \cw{-u} is supplied), \cw{xcopy}
reads and writes the selection using the type \cw{STRING}, which
means that the input or output data is expected to be encoded in
ISO-8859-1.

\dt \cw{-u}

\dd In read mode, causes \cw{xcopy} to request the selection using
the type \cw{UTF8_STRING}, which typically means that the returned
data will be encoded as UTF-8. In write mode, causes \cw{xcopy} to
\e{give out} the selection as type \cw{UTF8_STRING}, meaning that
the data piped in to it is expected to be encoded as UTF-8.

\dt \cw{-c}

\dd Similar to \cw{-u}, but uses the type \cw{COMPOUND_TEXT} rather
than \cw{UTF8_STRING}. \cw{COMPOUND_TEXT} is a complex
multi-character-set encoding similar to ISO 2022, and is unlikely to
be a very useful form in which to pass data to or from non-X
programs. However, it might occasionally be useful to retrieve a
compound text selection using \cw{xcopy -r -c}, and later on return
it to the X selection using \cw{xcopy -c} so it can be pasted back
into a different application.

In write mode, if \cw{xcopy} is operating in \cw{STRING} mode and a
pasting application requests the selection as \cw{COMPOUND_TEXT},
\cw{xcopy} will convert the data automatically. This is normally
what you want.

\dt \cw{-C}

\dd Suppresses conversion to compound text in write mode. This is
occasionally useful if you are pasting control characters, since the
compound text specification forbids any control characters and the
Xlib conversion functions honour this. If you are (for example)
trying to paste a sequence of editor commands into a terminal
window, you might well want to paste a string full of escape
sequences and control characters, in which case you may need to use
\cw{-C} to disable conversion to compound text.

\dt \cw{-b}

\dd Causes \cw{xcopy} to read or write the clipboard instead of the
selection. (Modern GNOME and KDE-style programs can often interact
with both. The \e{selection} is the traditional X-style storage
location which you typically copy things into just by selecting them
with the mouse, and paste with the middle mouse button. The
\e{clipboard} is a more Windows-like location which you access using
explicit Cut, Copy and Paste commands in your application.)

\dt \cw{-t}

\dd Causes \cw{xcopy}, in read mode only, to return the list of
possible target types currently stored in the selection. This is
probably only useful for debugging X applications or X selection
issues.

\dt \cw{-T}

\dd Causes \cw{xcopy}, in read mode only, to return the time stamp
for the current selection. This is probably only useful for
debugging X applications or X selection issues.

\dt \cw{-a} \e{target atom}

\dd Causes \cw{xcopy}, in read mode only, to return the selection
contents corresponding to some particular user-specified target
type. The target type can be anything listed by \cq{xcopy -r -t}.

\dt \cw{-v}

\dd Causes \cw{xcopy}, in read mode only, to produce a verbose
commentary on the progress of reading the X selection. Can be useful
for debugging interactions with other programs.

\dt \cw{-F}

\dd Causes \cw{xcopy} not to fork, when in write mode. Instead the
original \cw{xcopy} process will continue to run until the selection
is taken away from it. Probably only useful when debugging
\cw{xcopy} itself, although it's just possible that it might turn
out to be useful for some other special purpose (e.g. having the
process waiting for it know when the selection owner has changed).

\dt \cw{-d} \e{size}

\dd Alters the maximum size of data transferred in one lump by
\cw{xcopy}. (Probably most useful for diagnostic purposes.)

\dt \cw{-I}

\dd Inhibits \cw{xcopy}, in write mode, from using the \cw{INCR}
mechanism for transferring large amounts of selection data a piece at
a time and waiting for the recipient to acknowledge each chunk before
sending the next. (Just in case a client doesn't support it.)

\dt \cw{-B}

\dd Inhibits \cw{xcopy}, in write mode, from storing its data in the
persistent \q{cut buffers} on the root window as well as using the
peer-to-peer selection mechanism.

\U BUGS

Automatic conversion between compound text and UTF-8 is not
currently supported. There are Xlib functions to do it, although
they don't appear to work very well (missing out many characters
which they could have converted).

\U LICENCE

\cw{xcopy} is free software, distributed under the MIT licence. Type
\cw{xcopy --licence} to see the full licence text.

\versionid $Id$