.TH CPSENCODE l l "15 Oct 2001"
.SH NAME
cpsencode \- Embed shell scripts and data files in Complete \fIPostScript\fP (CPS) file
.SH SYNOPSIS
\fBcpsencode\fP shell-script [ \fB\-e\fP ] [ \fB\-n\fP ] [ \fB\-u\fP ]
[ \fB\-v\fP ] [ \fB\-x\fP ] >> \fIPostScript\fP-file
.SH DESCRIPTION
\fBcpsencode\fP [and \fBcpsdecode\fP] provide a convenient way of
storing a UNIX script (or DOS batch file) and data files as part of
the single \fIPostScript\fP plot the script creates. Thus, given the
resulting Complete \fIPostScript\fP (CPS) file one can recreate the
original script and data at a later time.
\fBcpsencode\fP takes a shell-script file as argument and writes
the content of the script as well as the contents of any data files referred to
in the script to standard output, which you can append to the \fIPostScript\fP
file. This extra output is written after a logical EOF marker used by
\fIPostScript\fP interpreters and begins with several comments flagged
with the \fIPostScript\fP comment %%CPS. Script and data files are
then written as \fIPostScript\fP comments; by default all data files
are compressed with \fBbzip2\fP and converted to ASCII using the
UNIX uuencode algorithm.
.OPTIONS
.TP
.B \-e
Leave unEncoded. Files are not decoded from ASCII to binary or
encoded from binary to ASCII. Requires \fB\-u\fP and that all
data files are plain ASCII.
.TP
.B \-n
Dryrun. No files are embedded but we report which files would
be [compressed|encoded and] appended as \fIPostScript\fP comments.
.TP
.B \-u
Leave Uncompressed. Files are not compressed prior to the encode stage.
.TP
.B \-v
Verbose. Report the progress of encoding the script and any data files
referred to in the script [Default is silent].
.TP
.B \-x
Embed executable files. Default is to skip executable files as they
are not expected to be portable. It is better to use the special
mechanism (see below) to add in the source code of the program, as
well as any makefiles or documentation needed.
.SH SPECIAL
A special mechanism is available if you want to embed files that are
not directly used by the script. These could be hidden files that
some commands will read implicitly (say, a .cshrc file) or related
documentation files that cannot be executed in the script. You can
import such files by adding the script comment
.br
.sp
.br
.sp
in Unix shell scripts or
.br
.sp
REM CPS: \fIfilename\fP
.br
.sp
You will need one such line for each filename you require (a single
filename can contain wild cards, e.g., *.dat). Any file is only
written once so repeated references to the same file by the script or
this special mechanism will only result in one import.
.br
\fBcpsencode\fP will also look for filenames given after a leading
option flag. Thus, files that occur in options such as \fB\-X\fP\fIfile\fP,
where \fBX\fP is any character, will also be examined and, if found,
embedded in the output.
.SH EXAMPLES
Let us say you have a cshell script called Figure_8.csh which creates
the \fIPostScript\fP file Figure_8.ps. Figure_8.csh operates on several
data files in order to make the plot. You turn this plot file into a
Complete \fIPostScript\fP (CPS) file with the command
.br
.sp
\fBcpsencode \-v\fP Figure_8.csh >> Figure_8.ps
.br
.sp
Alternatively, let that be the last command in the script so that it
is automatically done by the script itself.
.br
To unscramble the CPS file, simply say
.br
.sp
\fBcpsdecode \-v\fP Figure_8.ps
.SH BUGS
\fBcpsencode\fP assumes good script etiquette so that any temporary files
created by your script are removed before \fBcpsencode\fP is called.
Otherwise they will take up unneccesary space in the Complete \fIPostScript\fP
(CPS) file. \fBcpsencode\fP will have trouble if you script changes
directories with the \fIcd\fP command since filenames become relative to
another directory. Using absolute paths name for files (starting with /,
~/. or ~user/) is bad practice since other users may not be able to
access those files.
.SH AUTHOR
Paul Wessel, Geology & Geophysics, SOEST, University of Hawaii,
1680 East-West Road, Honolulu HI 96822, USA. www.soest.hawaii.edu/wessel.