Skip to content

Documentation for -T, -c, and sensible stdin #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
hackerb9 wants to merge 2 commits into from
Closed

Documentation for -T, -c, and sensible stdin #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
078932d
Update with several patches.
hackerb9 Oct 7, 2019
001c253
Undo changes that added sensible stdin and shorthand options
hackerb9 Oct 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 191 additions & 40 deletions xclip.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,90 +17,207 @@
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
.\"
.
.\" URL and email definitions from groff's an-ext.tmac file, just in
.\" case we're on a system with "classic" troff.
.
.\" Start URL.
.de UR
. ds m1 \\$1\"
. nh
. if \\n(mH \{\
. \" Start diversion in a new environment.
. do ev URL-div
. do di URL-div
. \}
..
.
.
.\" End URL.
.de UE
. ie \\n(mH \{\
. br
. di
. ev
.
. \" Has there been one or more input lines for the link text?
. ie \\n(dn \{\
. do HTML-NS "<a href=""\\*(m1"">"
. \" Yes, strip off final newline of diversion and emit it.
. do chop URL-div
. do URL-div
\c
. do HTML-NS </a>
. \}
. el \
. do HTML-NS "<a href=""\\*(m1"">\\*(m1</a>"
\&\\$*\"
. \}
. el \
\\*(la\\*(m1\\*(ra\\$*\"
.
. hy \\n(HY
..
.
.
.\" Start email address.
.de MT
. ds m1 \\$1\"
. nh
. if \\n(mH \{\
. \" Start diversion in a new environment.
. do ev URL-div
. do di URL-div
. \}
..
.
.
.\" End email address.
.de ME
. ie \\n(mH \{\
. br
. di
. ev
.
. \" Has there been one or more input lines for the link text?
. ie \\n(dn \{\
. do HTML-NS "<a href=""mailto:\\*(m1"">"
. \" Yes, strip off final newline of diversion and emit it.
. do chop URL-div
. do URL-div
\c
. do HTML-NS </a>
. \}
. el \
. do HTML-NS "<a href=""mailto:\\*(m1"">\\*(m1</a>"
\&\\$*\"
. \}
. el \
\\*(la\\*(m1\\*(ra\\$*\"
.
. hy \\n(HY
..
.
.TH XCLIP 1
.SH NAME
xclip \- command line interface to X selections (clipboard)
.SH SYNOPSIS
.B xclip
[OPTION] [FILE]...
.SH DESCRIPTION
Reads from standard in, or from one or more files, and makes the data available as an X selection for pasting into X applications. Prints current X selection to standard out.
Reads from standard input, or from one or more files, and makes the data available as an X selection for pasting into X applications. Prints current X selection to standard out.
.TP
\fB\-i\fR, \fB\-in\fR
read text into X selection from standard input or files (default)
Read text into X selection from standard input or files. (Default unless it would read from a tty.)
.TP
\fB\-o\fR, \fB\-out\fR
print the selection to standard out (generally for piping to a file or program)
Print the selection to standard out. (Default when no files are specified and standard input is a tty.)
.TP
\fB\-f\fR, \fB\-filter\fR
when xclip is invoked in the in mode with output level set to silent (the defaults), the filter option will cause xclip to print the text piped to standard in back to standard out unmodified
Reads text into the X selection and causes xclip to print any text piped to standard input back to standard out unmodified. This does not work with files. Also requires xclip be invoked in the in mode with output level set to silent (the defaults if you are piping into xclip).
.TP
\fB\-r\fR, \fB\-rmlastnl\fR
when the last character of the selection is a newline character, remove it. Newline characters that are not the last character in the selection are not affected. If the selection does not end with a newline character, this option has no effect. This option is useful for copying one-line output of programs like \fBpwd\fR to the clipboard to paste it again into the command prompt without executing the line immediately due to the newline character \fBpwd\fR appends.
\fB\-selection\fR \fIselection\fR
Specify which X selection to use, options are \(lqprimary\(rq (default), \(lqsecondary\(rq, or \(lqclipboard\(rq.
.TP
\fB\-l\fR, \fB\-loops\fR
number of X selection requests (pastes into X applications) to wait for before exiting, with a value of 0 (default) causing xclip to wait for an unlimited number of requests until another application (possibly another invocation of xclip) takes ownership of the selection
\fB\-c\fR, \fB\-clipboard\fR
Shorthand for \(lq-selection clipboard\(rq.
.TP
\fB\-t\fR, \fB\-target\fR
specify a particular data format using the given target atom. With \fB\-o\fR the special target atom name "TARGETS" can be used to get a list of valid target atoms for this selection. For more information about target atoms refer to ICCCM section 2.6.2
\fB\-t\fR, \fB\-target\fR \fItarget\fR
Specify a particular data format using the given target atom (E.g., \(lqtext/html\(rq, \(lqimage/jpeg\(rq). The default target is \(lqUTF8_STRING\(rq. On output, if a selection doesn't provide \(lqUTF8_STRING\(rq, xclip will fallback to \(lqSTRING\(rq.
.TP
\fB\-d\fR, \fB\-display\fR
X display to use (e.g. "localhost:0"), xclip defaults to the value in $\fBDISPLAY\fR if this option is omitted
\fB\-T\fR
Show all valid targets for -t. Technically, this is just shorthand for \(lq-target TARGETS\(rq. The special target atom named \(lqTARGETS\(rq contains the list of all valid target atoms for this selection. For more information about target atoms refer to ICCCM section 2.6.2.
.TP
\fB\-h\fR, \fB\-help\fR
show quick summary of options
\fB\-r\fR, \fB\-rmlastnl\fR
Remove a newline at the end of the selection. Newline characters that are not the last character are not affected. If the selection does not end with a newline character, this option has no effect. This option is useful for copying one-line output of programs like \fBpwd\fR to the clipboard to paste it again into the command prompt without executing the line immediately due to the newline character \fBpwd\fR appends.
.TP
\fB\-selection\fR
specify which X selection to use, options are "primary" to use XA_PRIMARY (default), "secondary" for XA_SECONDARY or "clipboard" for XA_CLIPBOARD
\fB\-l\fR, \fB\-loops\fR \fIn\fR
Number of X selection requests (pastes into X applications) to wait for before exiting, with a value of 0 (default) causing xclip to wait for an unlimited number of requests until another application (possibly another invocation of xclip) takes ownership of the selection.
.TP
\fB\-d\fR, \fB\-display\fR \fIdisplay\fR
X display to use (e.g. \(lqlocalhost:0\(rq), xclip defaults to the value in $\fBDISPLAY\fR if this option is omitted.
.TP
\fB\-h\fR, \fB\-help\fR
Show quick summary of options
.TP
\fB\-version\fR
show version information
Show version information.
.TP
\fB\-silent\fR
fork into the background to wait for requests, no informational output, errors only (default)
Fork into the background to wait for requests, no informational output, errors only (default).
.TP
\fB\-quiet\fR
show informational messages on the terminal and run in the foreground
Show informational messages on the terminal and run in the foreground.
.TP
\fB\-verbose\fR
provide a running commentary of what xclip is doing
Run in the foreground and provide a running commentary of what xclip is doing.
.TP
\fB\-noutf8\fR
operate in legacy (i.e. non UTF-8) mode for backwards compatibility
(Use this option only when really necessary, as the old behavior was broken)
Operate in legacy (i.e. non UTF-8) mode for backwards compatibility.
(Use this option only when really necessary, as the old behavior was broken).

.PP
xclip reads text from standard in or files and makes it available to other X applications for pasting as an X selection (traditionally with the middle mouse button). It reads from all files specified, or from standard in if no files are specified. xclip can also print the contents of a selection to standard out with the
.B
\-o
option.
xclip reads text from files or standard input and makes a copy available to other X applications for pasting as an X selection (traditionally with the middle mouse button). All files are read as input. When no files are specified, xclip checks whether standard input is a tty; if so, it switches to output mode and prints the contents of the selection to standard out. Otherwise, xclip presumes it is being piped into and reads from standard input. In short, xclip will do the right thing most of the time, but in complex cases or in carefully written shell scripts, you may want to force input or output modes with the \fB\-i\fR or \fB\-o\fR options.

xclip was designed to allow tighter integration of X applications and command line programs. The default action is to silently wait in the background for X selection requests (pastes) until another X application places data in the clipboard, at which point xclip exits silently. You can use the \fB\-verbose\fR option to prevent xclip from backgrounding itself and see if and when it receives selection requests from other X applications.

xclip was designed to allow tighter integration of X applications and command line programs. The default action is to silently wait in the background for X selection requests (pastes) until another X application places data in the clipboard, at which point xclip exits silently. You can use the \fB\-verbose\fR option to see if and when xclip actually receives selection requests from other X applications.
X keeps track of three different selections: \fIprimary\fR, \fIclipboard\fR, and \fIsecondary\fR. In general, the primary selection is used to store short-lived data, such as when the user highlights text with a mouse. The clipboard stores longer lived data and only changes when the user explicitly requests it by pressing cut or copy. Selections can store any sort of data, but usually one expects to see non-text datatypes, such as images, in the clipboard. The secondary selection is rarely used by programs, but some users find it handy as a quick way to stash a copy of the primary selection that isn't quite as ephemeral.

A selection can have multiple \(lqtargets\(rq, each of which is a different datatype. By default xclip uses the target \(lqUTF8_STRING\(rq. For example, if you copy text from a web browser, it may have the choice to paste it as either \(lqUTF8_STRING\(rq or \(lqtext/html\(rq. You can see what targets are available using the \fB-T\fR option and you can pick a specific one using \fB-t\fR.

Options can be abbreviated as long as they remain unambiguous. For example, it is possible to use \fB\-d\fR or \fB\-disp\fR instead of \fB\-display\fR. However, \fB\-v\fR couldn't be used because it is ambiguous (it could be short for \fB\-verbose\fR or \fB\-version\fR), so it would be interpreted as a filename.

Note that only the first character of the selection specified with the \fB\-selection\fR option is important. This means that "p", "sec" and "clip" would have the same effect as using "primary", "secondary" or "clipboard" respectively.
Note that only the first character of the selection specified with the \fB\-selection\fR option is important. This means that \(lqp\(rq, \(lqsec\(rq and \(lqclip\(rq would have the same effect as using \(lqprimary\(rq, \(lqsecondary\(rq or \(lqclipboard\(rq respectively.

.SH EXAMPLES
.PP
I hate man pages without examples!

.B
uptime | xclip
.PP
Put your uptime in the X selection. Then middle click in an X application to paste.
.TP
.B uptime | xclip
.IP
Put your uptime in the X selection.
Then middle click in an X application to paste.

.TP
.B xclip -loops 10 -verbose /etc/motd
.PP
.IP
Exit after /etc/motd (message of the day) has been pasted 10 times. Show how many selection requests (pastes) have been processed.

.B xclip -o > helloworld.c
.PP
.TP
.B xclip > helloworld.c
.IP
Put the contents of the selection into a file.

.TP
.B xclip -t text/html index.html
.PP
Middle click in an X application supporting HTML to paste the contents of the given file as HTML.
.IP
Copy a file with a specific MIME type. Middle click in an X application supporting HTML to paste the contents of the given file as HTML.

.TP
.B xclip -c -T
.IP
List valid data formats available on the clipboard. For example, after doing right-click \(lqCopy Image\(rq in a web browser, one might see:

.EX
TIMESTAMP
TARGETS
MULTIPLE
SAVE_TARGETS
image/png
image/tiff
image/jpeg
.EE

.TP
.B xclip -c -t image/jpeg < foo.jpg
.IP
Copy an image to the clipboard.

.TP
.B xclip -c -t image/jpeg > bar.jpg
.IP
Paste an image from the clipboard to a file.

.SH ENVIRONMENT
.TP
Expand All @@ -111,10 +228,44 @@ X display to use if none is specified with the
\-display
option.

.SH "SEE ALSO"
.PP
.IR xclip-copyfile (1),
.IR xclip-cutfile (1),
and
.IR xclip-pastefile (1)
copy and move files via the X clipboard.
.PP
.IR xsel (1)
and
.IR wl-clipboard (1)
are command line programs similar to xclip. xsel has the ability to keep a primary selection even after a program has closed. wl-clipboard works with Wayland instead of X.
.PP
.IR copyq (1),
.IR diodon (1),
.IR gpaste (1),
and
.IR xclipboard (1)
are just a few of many, many GUI clipboard managers which let you browse your clipboard's history.
.PP

.SH KNOWN BUGS
.PP
xclip is not ICCCM compliant. For example, the TIMESTAMP isn't set.
.PP
Only one target type can be chosen. Would it be useful to let users pick a different type for each file?

.SH REPORTING BUGS
Please report any bugs, problems, queries, experiences, etc. directly to the author.
Please report any bugs, problems, queries, experiences, etc. via
.UR https://github.com/astrand/xclip
github.
.UE

.SH AUTHORS
Kim Saunders <kims@debian.org>
Peter Åstrand <astrand@lysator.liu.se>
.MT astrand@lysator.liu.se
Peter \(oAstrand
.ME
.br
.MT kims@debian.org
Kim Saunders
.ME
6 changes: 4 additions & 2 deletions xcprint.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ prhelp(char *name)
"Access an X server selection for reading or writing.\n"
"\n"
" -i, -in read text into X selection from standard input or files\n"
" (default)\n"
" (default if stdin isn't a tty)\n"
" -o, -out prints the selection to standard out (generally for\n"
" piping to a file or program)\n"
" -l, -loops number of selection requests to "
Expand All @@ -46,14 +46,16 @@ prhelp(char *name)
" -h, -help usage information\n"
" -selection selection to access (\"primary\", "
"\"secondary\", \"clipboard\" or \"buffer-cut\")\n"
" -c shortcut for \"-selection clipboard\"\n"
" -noutf8 don't treat text as utf-8, use old unicode\n"
" -target use the given target atom\n"
" -T show all available targets\n"
" -rmlastnl remove the last newline character if present\n"
" -version version information\n"
" -silent errors only, run in background (default)\n"
" -quiet run in foreground, show what's happening\n"
" -verbose running commentary\n"
"\n" "Report bugs to <astrand@lysator.liu.se>\n", name);
"\n" "Report bugs to https://github.com/astrand/xclip\n", name);
exit(EXIT_SUCCESS);
}

Expand Down