home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / clipart / gs22.zip / USE.DOC < prev    next >
Text File  |  1991-05-28  |  12KB  |  317 lines

  1.    Copyright (C) 1989, 1990, 1991 Aladdin Enterprises.  All rights reserved.
  2.    Distributed by Free Software Foundation, Inc.
  3.  
  4. This file is part of Ghostscript.
  5.  
  6. Ghostscript is distributed in the hope that it will be useful, but
  7. WITHOUT ANY WARRANTY.  No author or distributor accepts responsibility
  8. to anyone for the consequences of using it or for whether it serves any
  9. particular purpose or works at all, unless he says so in writing.  Refer
  10. to the Ghostscript General Public License for full details.
  11.  
  12. Everyone is granted permission to copy, modify and redistribute
  13. Ghostscript, but only under the conditions described in the Ghostscript
  14. General Public License.  A copy of this license is supposed to have been
  15. given to you along with Ghostscript so you can know your rights and
  16. responsibilities.  It should be in a file named COPYING.  Among other
  17. things, the copyright notice and this notice must be preserved on all
  18. copies.
  19.  
  20. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  21.  
  22. This file, use.doc, describes how to use the Ghostscript language
  23. interpreter.
  24.  
  25. For an overview of Ghostscript and a list of the documentation files, see
  26. README.  
  27.  
  28. ********
  29. ******** How to use the Ghostscript interpreter ********
  30. ********
  31.  
  32. The file name of the Ghostscript interpreter is gs.exe (MS-DOS and VMS) or
  33. gs (Unix).  To run it, you also need the initialization files gs_init.ps,
  34. gs_fonts.ps, gs_statd.ps, and symbol_e.ps; if you are going to be
  35. displaying any text, you also need uglyr.gsf and Fontmap.
  36.  
  37. To invoke the interpreter, give the command
  38.     gs <filename1> ... <filenameN>
  39. The interpreter will read in the files in sequence and execute them.
  40. After doing this, it reads further input from the primary input stream
  41. (normally the keyboard).  Each line (i.e. characters up to a <return>) is
  42. interpreted separately.  To exit from the interpreter, type quit<return>.
  43. The interpreter also exits gracefully if it encounters end-of-file.
  44. Typing the interrupt character, e.g., control-C, is also safe.
  45.  
  46. The interpreter recognizes several switches described below, which may appear
  47. anywhere in the command line and apply to all files thereafter.
  48.  
  49. Ghostscript may be built with multiple output devices.  Ghostscript
  50. normally opens the first one and directs output to it.  To use device xyz
  51. as the initial output device, include the switch
  52.     -sDEVICE=xyz
  53. in the command line.  Note that this switch must precede the first .ps
  54. file, and only its first invocation has any effect.  For example, for
  55. printer output in a normal configuration that includes an Epson printer
  56. driver, you might use the shell command
  57.     gs -sDEVICE=epson myfile.ps
  58. instead of just
  59.     gs myfile.ps
  60. Alternatively, you can type
  61.     (epson) selectdevice
  62.     (myfile.ps) run
  63. All output then goes to the printer instead of the display until further
  64. notice.  You can switch devices at any time by using the selectdevice
  65. procedure, e.g.,
  66.     (vga) selectdevice
  67. or
  68.     (epson) selectdevice
  69.  
  70. To find out what devices are available, just type
  71.     devicenames
  72. The -h and -? (help) message also lists the available devices.
  73.  
  74. File searching
  75. --------------
  76.  
  77. When looking for the initialization files (gs_*.ps), the files related to
  78. fonts, or the file for the 'run' operator, Ghostscript first tries opening
  79. the file with the name as given (i.e., using the current working directory
  80. if none is specified).  If this fails, and the file name doesn't specify
  81. an explicit directory or drive (i.e., doesn't begin with '/' on Unix
  82. systems; doesn't contain a ':' or begin with a '/' or '\' on MS-DOS
  83. systems; doesn't contain a ':' or a square bracket on VMS systems),
  84. Ghostscript will try directories in the following order:
  85.  
  86.     - The directory/ies specified by the -I switch(es) in the command
  87.       line (see below), if any;
  88.  
  89.     - The directory/ies specified by the GS_LIB environment variable,
  90.       if any;
  91.  
  92.     - The directory/ies specified by the GS_LIB_DEFAULT macro in the
  93.       Ghostscript makefile, if any.
  94.  
  95. Each of these (GS_LIB_DEFAULT, GS_LIB, and -I parameter) may be either a
  96. single directory, or a list of directories separated by a character
  97. appropriate for the operating system (':' on Unix systems, ';' on VMS
  98. systems, ';' on MS-DOS systems).
  99.  
  100. VMS-specific notes
  101. ------------------
  102.  
  103. On VMS systems, the last character of each "directory" name indicates what
  104. sort of entity the "directory" references.  If the "directory" name ends
  105. with a colon, it is taken as referring to a logical device, e.g.:
  106.         $ DEFINE GHOSTSCRIPT_DEVICE DUA1:[GHOSTSCRIPT_14]
  107.         $ DEFINE GS_LIB GHOSTSCRIPT_DEVICE:
  108. If the "directory" name ends with a closing square bracket, it is taken as
  109. referring to a real directory, e.g.:
  110.         $ DEFINE GS_LIB DUA1:[GHOSTSCRIPT]
  111.  
  112. To run Ghostscript with switches, you must type a command like
  113.  
  114.     $ gs "-dNODISPLAY"
  115.  
  116. because the C run time library will convert the command
  117. parameters/arguments to lowercase unless you enclose them in double quotes
  118. which preserves the case.
  119.  
  120. If you are on an X Windows display (for which gs is built), you can do
  121.  
  122.     $ set display/create/node="domain-name"/transport=tcpip
  123.  
  124. For example,
  125.  
  126.     $ set display/create/node="doof.city.com"/transport=tcpip
  127.  
  128. and then run Ghostscript
  129.  
  130.     $ gs
  131.  
  132. MS-DOS resources
  133. ----------------
  134.  
  135. If you are running Ghostscript on a MS-DOS machine with a display that is
  136. not EGA/VGA compatible, you must build Ghostscript with the BGI driver as
  137. the default, and you will need the appropriate .BGI file from the Borland
  138. Turbo C library.  (Ghostscript includes the EGA/VGA driver in the
  139. executable.)
  140.  
  141. If you are using the BGI driver, two additional environment variables
  142. become relevant:
  143.  
  144.     BGIPATH - defines the directory where Ghostscript will look for
  145. the appropriate BGI driver.  If BGIPATH is not defined, Ghostscript will
  146. only look in the current directory.
  147.  
  148.     BGIUSER - a string of the form nn.dname, where nn is a hexadecimal
  149. number giving a display mode and dname is the name of a file containing a
  150. user-supplied BGI driver.  If BGIUSER is defined and the BGI device is
  151. selected, Ghostscript will supply nn as the display mode and will obtain
  152. the driver from the file named dname.
  153.  
  154. X Windows resources
  155. -------------------
  156.  
  157. Ghostscript looks for the following resources under the program name
  158. "Ghostscript":
  159.  
  160.     borderWidth - the border width in pixels
  161.         default = 1
  162.     borderColor - the name of the border color
  163.         default = black
  164.     geometry - the window size and placement, WxH+X+Y
  165.         default = ???
  166.     xResolution - the number of x pixels per inch
  167.         default is computed from WidthOfScreen and WidthMMOfScreen
  168.     yResolution - the number of y pixels per inch
  169.         default is computed from HeightOfScreen and HeightMMOfScreen
  170.  
  171. To set these resources, put them in a file (such as ~/.Xdefaults) in the
  172. following form:
  173.  
  174. Ghostscript*geometry:    612x792-0+0
  175. Ghostscript*xResolution: 72
  176. Ghostscript*yResolution: 72
  177.  
  178. Then load the defaults into the X server:
  179.  
  180. % xrdb -merge ~/.Xdefaults
  181.  
  182. Normal switches
  183. ---------------
  184.  
  185.     -- filename arg1 ...
  186.         Takes the next argument as a file name as usual, but takes
  187.         all remaining arguments (even if they have the syntactic
  188.         form of switches) and defines the name ARGUMENTS in
  189.         userdict (not systemdict) as an array of those strings,
  190.         *before* running the file.  When Ghostscript finishes
  191.         executing the file, it exits back to the shell.
  192.  
  193.     -Dname=token
  194.     -dname=token
  195.         Define a name in systemdict with the given definition.
  196.         The token must be exactly one token (as defined by the
  197.         'token' operator) and must not contain any whitespace.
  198.  
  199.     -Dname
  200.     -dname
  201.         Define a name in systemdict with value=null.
  202.  
  203.     -Sname=string
  204.     -sname=string
  205.         Define a name in systemdict with a given string as value.
  206.         This is different from -d.  For example,
  207.             -dname=35
  208.         is equivalent to the program fragment
  209.             /name 35 def
  210.         whereas
  211.             -sname=35
  212.         is equivalent to
  213.             /name (35) def
  214.  
  215.     -q
  216.         Quiet startup -- suppress normal startup messages,
  217.         and also do the equivalent of -dQUIET.
  218.  
  219.     -gnumber1xnumber2
  220.         Equivalent to -dDEVICEWIDTH=number1 and
  221.         -dDEVICEHEIGHT=number2.  This is for the benefit of
  222.         devices (such as display windows) that require
  223.         (or allow) width and height to be specified.
  224.  
  225.     -Idirectories
  226.         Adds the designated list of directories at the head of the
  227.         search path for library files.
  228.  
  229.     -
  230.         This is not really a switch.  It indicates to Ghostscript
  231.         that the standard input is coming from a file or a pipe.
  232.         Ghostscript reads from stdin until reaching end-of-file,
  233.         executing it like any other file, and then continues
  234.         processing the command line.  At the end of the command
  235.         line, Ghostscript exits rather than going into its
  236.         interactive mode.
  237.  
  238. Note that gs_init.ps makes systemdict read-only, so the values of names
  239. defined with -D/d/S/s cannot be changed (although, of course, they can be
  240. superseded by definitions in userdict or other dictionaries.)
  241.  
  242. Special names
  243. -------------
  244.  
  245. Including -dNODISPLAY in the command line will suppress the normal
  246. initialization of the output device.  This may be useful when debugging.
  247. Similarly, -dNOCACHE disables character caching, and -dNOBIND disables the
  248. 'bind' operator.  -dNOPAUSE disables the prompt and pause at the end of
  249. each page; this may be desirable for applications where another program is
  250. 'driving' Ghostscript.
  251.  
  252. As described above, -sDEVICE=device selects an alternate initial output
  253. device.
  254.  
  255. For the benefit of PostScript files that think they are being printed on a
  256. hardcopy printer, gs_init.ps includes the line
  257.     (gs_statd.ps) run
  258. This file contains dummy definitions for statusdict.
  259.  
  260. Debugging switches
  261. ------------------
  262.  
  263. The -T and -Z switches only apply if the interpreter was built for a
  264. debugging configuration.
  265.  
  266.     -Mn    Force the interpreter's allocator to acquire additional
  267.         memory in units of nK, rather than the default (currently
  268.         20K on MS-DOS systems, 50K on Unix).  n is a positive
  269.         decimal integer (not exceeding 63 on MS-DOS systems).
  270.  
  271.     -Tname:rsize:format
  272.         (Only available on MS-DOS systems.)
  273.         Trace a procedure within Ghostscript.  Any number of
  274.         procedures may be traced.  rsize is the size of the value
  275.         returned by the procedure, in bytes; if omitted, the value
  276.         returned by the procedure is not printed.  format is a
  277.         printf-style template for printing the arguments; if
  278.         omitted, the arguments are printed in hex.  Note that
  279.         MS-DOS provides no way to quote spaces or commas within a
  280.         command line argument.
  281.  
  282.     -Zxxx    Turn on debugging printout.
  283.         Each of the xxx characters selects an option:
  284.         if the string is empty, all options are selected.
  285.         Case is significant.
  286.             0 = type 1 path tracer (type1imagepath)
  287.             1 = type 1 font interpreter (type1addpath)
  288.             2 = curve subdivider
  289.             a = allocator (large blocks only)
  290.               A = allocator (all calls)
  291.             b = bitmap image processor
  292.               B = bitmap images, detail
  293.             c = color/halftone mapper
  294.             d = dictionary lookup
  295.             e = error returns
  296.               E = error returns, dump C stack
  297.             f = fill algorithm (summary)
  298.               F = fill algorithm (detail)
  299.             h = halftone renderer
  300.             i = interpreter, just names
  301.               I = interpreter, everything
  302.             k = character cache
  303.               K = character cache, every access
  304.             l = command lists, bands
  305.               L = command lists, everything
  306.             m = makefont and font cache
  307.             o = outliner (stroke)
  308.             p = path tracer
  309.             q = rectangle fill
  310.             r = arc renderer
  311.             s = scanner
  312.             t = tiling algorithm
  313.             u = undo saver (for save/restore)
  314.             v = device-level output
  315.             w = LZW encoder/decoder
  316.             x = transformations
  317.