NAME
cpsencode - Embed shell scripts and data files in Complete
PostScript (CPS) file
SYNOPSIS
cpsencode shell-script [ -e ] [ -n ] [ -u ] [ -v ] [ -x ] >>
PostScript-file
DESCRIPTION
cpsencode [and cpsdecode] provide a convenient way of stor-
ing a UNIX script (or DOS batch file) and data files as part
of the single PostScript plot the script creates. Thus,
given the resulting Complete PostScript (CPS) file one can
recreate the original script and data at a later time.
cpsencode 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 PostScript file. This extra
output is written after a logical EOF marker used by
PostScript interpreters and begins with several comments
flagged with the PostScript comment %%CPS. Script and data
files are then written as PostScript comments; by default
all data files are compressed with bzip2 and converted to
ASCII using the UNIX uuencode algorithm.
-e Leave unEncoded. Files are not decoded from ASCII to
binary or encoded from binary to ASCII. Requires -u
and that all data files are plain ASCII.
-n Dryrun. No files are embedded but we report which
files would be [compressed|encoded and] appended as
PostScript comments.
-u Leave Uncompressed. Files are not compressed prior to
the encode stage.
-v Verbose. Report the progress of encoding the script
and any data files referred to in the script [Default
is silent].
-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.
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
#CPS: filename
in Unix shell scripts or
REM CPS: filename
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.
cpsencode will also look for filenames given after a leading
option flag. Thus, files that occur in options such as
-Xfile, where X is any character, will also be examined and,
if found, embedded in the output.
EXAMPLES
Let us say you have a cshell script called Figure_8.csh
which creates the PostScript 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 PostScript (CPS)
file with the command
cpsencode -v Figure_8.csh >> Figure_8.ps
Alternatively, let that be the last command in the script so
that it is automatically done by the script itself.
To unscramble the CPS file, simply say
cpsdecode -v Figure_8.ps
BUGS
cpsencode assumes good script etiquette so that any tem-
porary files created by your script are removed before
cpsencode is called. Otherwise they will take up unnec-
cesary space in the Complete PostScript (CPS) file. cpsen-
code will have trouble if you script changes directories
with the cd 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.
AUTHOR
Paul Wessel, Geology & Geophysics, SOEST, University of
Hawaii, 1680 East-West Road, Honolulu HI 96822, USA.
www.soest.hawaii.edu/wessel.