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.