About this manual ================== clipboard 2.0 manual written by Mac-arena the Bored Zo this manual is written in setext. Purpose ========= clipboard is a program for copying and pasting from the Mac OS X command-line. Building and installing ========================= Before you can use clipboard, you must build it from sources and optionally install it. * First, obtain the clipboard source distribution, if you haven't already. This file should be named something like "clipboard-20.tbz" or "clipboard-20.tgz". The word ~TARBALL~ is used in place of the filename below; where you see ~TARBALL~, type the filename instead. * Unpack the archive. If the filename ends in .tbz, .bz, or .bz2, use "bunzip2 ~TARBALL~". If it ends in .tgz or .gz, use "gunzip ~TARBALL~". The resulting file should have a name like "clipboard-20.tar" (I'll use ~TARFILE~ here); type "tar xf ~TARFILE~". * Change your working directory so you are in the distribution directory. Assuming this is named "clipboard-20", type "cd clipboard-20". * Build the executable by typing "buildit". There are preprocessor_macros_ you can place after the word "buildit" to include or exclude certain features. * Install the executable. Type "buildit --install". If you wish the executable to be installed in someplace other than /usr/local/bin, you can pass the directory name after the build command. For example, "buildit --install /usr/bin". Preprocessor macros --------------------- This is a list of the preprocessor macros you can supply to the build process to influence the resulting program. If your compiler is gcc, append each of these to -D, for example "-DBUFSIZE=1048576 -DNO_ESCALATE". Other compilers should work similarly. * NO_ESCALATE Turns off escalated allocation. Escalated allocation is recommended if you intend to copy large amounts of data to the clipboard and you don't want to copy from a file using the -c option. With this, clipboard starts by reading a fixed amount (64 K by default) and doubles that amount every time it increases the buffer size when reading from stdin. Thus, the increment will be 64 K for the first read, 64 K for the second read, 128 K, 256 K, etc. * USE_FD Turns on an experimental feature: file-descriptor I/O. Normally, clipboard uses file streams. My own comparisons between FDs and streams has not revealed a significant difference in performance, but YMMV. * NOARGSUPPORT Turns off support for command-line arguments. All I/O must then be done through stdin and stdout (i.e. the pipeline). * NOCLIPCAT Turns off the feature by which, when copying multiple things, they will all be copied to the clipboard together at the end of processing (after any command- line flags have been processed). You should specify this if you turn off argument support (with NOARGSUPPORT); the clipcat feature isn't very useful otherwise (in fact, without argument support, the clipcat code never runs). * BUFSIZE=~N~ Specify a buffer increment of ~N~ bytes. When reading from stdin, clipboard will read ~N~ bytes at a time. Doesn't apply to direct-from-file operations or stdout. When escalated allocation is present, this is the initial increment. * DEBUG Turns on lots of messages which tell you what clipboard is doing. You generally should not enable this directly; instead, use the --debug option to the build script. Build script syntax --------------------- buildit [~option~] [~version~] [compile-options] You can specify one ~option~ from the list below, or no option. The ~version~, if specified, must have the decimal removed (for example, "20" == 2.0), and is used to identify the source file and output name. If you specify no version, it will attempt to compile clipboard.c as clipboard. If you do specify a version, it will attempt to compile clipboard-VERSION.c as clipboard-VERSION. The ~compile-options~ are passed to the compiler during the build phase. Build script options ---------------------- * --debug Turns on a large number of messages, turns on debugging symbols, and turns off the automatic stripping of the executable. Makes the program unuseful for shell scripts, and very large (about a MB). * --no-optimisation/no-optimization Turns off optimisation. Normally, clipboard is built with -O2. Implied by --debug. Not recommended for the general public. * --optimise=N/--optimize=N Sets optimisation (-O) to N. In GCC 3.3, N can be 0, 1, 2, nothing (--optimise=), or 's'. See the compiler documentation for appropriate values for the -O flag. * --fast=CPU Uses gcc3's -fast option to build an executable that is as fast as possible. Requires a CPU argument that can be fed to the -mcpu= and -mtune= options. As of 2004/GCC 3.3, acceptable values are G3, G4, and G5. * --profilable Includes profiling symbols in the executable, so you can use a profiler (e.g. gprof) to see a breakdown of where CPU time is being spent. Not recommended for the general public. * --install Assumes the program has already been built and attempt to install it - in /usr/local/bin by default. You can supply a different location using the BINDIR environment variable. If the directory does not exist, it will be created. If the directory does exist but you do not have permission to write there, the installation will be sudone and you will be asked for your password. Usage ======= Usually, you can use clipboard with no arguments, and it will figure out whether you want to copy, paste, or both. % ps xww | clipboard > processes.txt However, clipboard also accepts a number of arguments, short and long. * -c, --copy, -x, --cut, -w Copy from stdin to the clipboard (i.e., write to the clipboard). "--cut"/"-x" is included for completeness, but what clipboard actually does is arguable. * -v, --paste, -r Paste from the clipboard to stdout (i.e., read from the clipboard). * -b, --clear Clear the clipboard. * -t, --translate-newlines Turn on newline translation - that is, translation of line-feeds (UNIX newlines) into carriage-returns (Mac newlines) and vice versa. Opposite of -T/--no-translate-newlines. This is the default. * -T, --no-translate-newlines Turn off newline translation. Opposite of -t/--translate-newlines. * -?, -h, --help Prints a thorough description of options. * -f Specify a file to read/write instead of stdin/stdout. This option is actually ignored; a filename is accepted with or without -f. * -s~NUM~ Sets the initial buffer size to ~NUM~ bytes. See the discussion of the NO_ESCALATE macro above. For each copy or paste option, you can specify zero or more options, and optionally a file name. For example: % clipboard -c ~/Documents/log1.txt -c ~/Documents/log2.txt -v ~/Documents/log-all.txt This would copy log1.txt and log2.txt to the clipboard (both, in order) and paste through stdout into log-all.txt. The same semantics work for the paste command, but not the clear command (because it has no use for files). One thing worth noting: If you're going to copy from a file, use the -c option and specify the pathname on the command-line - _don't_ simply redirect it in through stdin. * WRONG: % clipboard < ~/Documents/log-all.txt * RIGHT: % clipboard -c ~/Documents/log-all.txt The latter command can reduce the time taken by a third if log-all.txt is large. Date and URL ============== 15 April 2004 http://boredzo.fourx.org/clipboard/manual.etx