Move some of my more useful utilities out from my all-purpose

[sgt/utils] / xcopy / xcopy.but

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

\C{xcopy-manpage} Man page for \cw{xcopy}

\H{xcopy-manpage-name} NAME

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

\H{xcopy-manpage-synopsis} SYNOPSIS

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

\H{xcopy-manpage-description} 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.

\H{xcopy-manpage-options} 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.

\H{xcopy-manpage-bugs} BUGS

Occasionally \cw{xcopy -r} completely fails to notice selection data
owned by another process. I have not yet reproduced this reliably;
if anyone can, some work with \cw{xmon}(1) would be much
appreciated...

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).