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
       storing 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  exe­
              cutable  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 pro­
              gram, 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 implic­
       itly (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


       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 lead­
       ing 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.   Fig­
       ure_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 tempo­
       rary  files  created  by  your  script  are removed before
       cpsencode is called.  Otherwise they will take up unnecce­
       sary  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.



15 Oct 2001                     l                    CPSENCODE(l)