home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 February / PCWK0296.iso / sharewar / dos / program / gs300sr1 / gs300sr1.exe / LANGUAGE.DOC < prev    next >
Text File  |  1994-07-27  |  16KB  |  388 lines
  1.    Copyright (C) 1989-1992, 1993, 1994 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17.  
  18. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  19.  
  20. This file, language.doc, describes the relationship between the Ghostscript
  21. interpreter and the PostScript language.
  22.  
  23. For an overview of Ghostscript and a list of the documentation files, see
  24. README.
  25.  
  26. The Ghostscript interpreter, except as noted below, is intended to execute
  27. properly any source program written in the (Level 2) PostScript language as
  28. defined in the December 1990 printing of the PostScript Language Reference
  29. Manual (Second Edition) published by Addison-Wesley (ISBN 0-201-18127-4).
  30. However, the interpreter is configurable in ways that can restrict it to
  31. various subsets of this language.  Specifically, the base interpreter
  32. accepts the Level 1 subset of the PostScript language, as defined in the
  33. first edition of the PostScript Language Reference Manual, ISBN
  34. 0-201-10174-2, Addison-Wesley, 1985, plus the file system, version 25.0
  35. language, and miscellaneous additions listed in sections A.1.6, A.1.7, and
  36. A.1.8 of the Second Edition respectively, including allowing a string
  37. operand for the 'status' operator.  The base interpreter may be configured
  38. by adding any combination of the following:
  39.  
  40.     - The ability to process PostScript Type 1 fonts.  This facility is
  41. normally included in the interpreter.
  42.  
  43.     - The CMYK color extensions listed in section A.1.4 of the Second
  44. Edition (including colorimage).  These facilities are only available if the
  45. color, dps, or level2 feature was selected at the time that Ghostscript was
  46. compiled and linked.
  47.  
  48.     - The Display PostScript extensions listed in section A.1.3
  49. of the Second Edition, but excluding the operators listed in section
  50. A.1.2.  These facilities are only available if the dps feature or the
  51. level2 feature was selected at the time that Ghostscript was compiled
  52. and linked.
  53.  
  54.     - The composite font extensions listed in section A.1.5 of the
  55. Second Edition, and the ability to handle Type 0 fonts.  These facilities
  56. are only available if the compfont feature or the level2 feature was
  57. selected at the time that Ghostscript was compiled and linked.
  58.  
  59.     - The PostScript Level 2 "filter" facilities, excluding the
  60. DCTEncode and DCTDecode filters.  These facilities are only available if
  61. the filter, dps, or level2 feature was selected at the time that
  62. Ghostscript was compiled and linked.
  63.  
  64.     - The PostScript Level 2 DCTEncode and DCTDecode filters.  These
  65. facilities are only available if the dct or level2 feature was selected at
  66. the time that Ghostscript was compiled and linked.
  67.  
  68.     - All the other PostScript Level 2 operators and facilities listed
  69. in section A.1.1 of the Second Edition and not listed in any of the other
  70. A.1.n sections.  These facilities are only available if the level2 feature
  71. was selected at the time that Ghostscript was compiled and linked.
  72.  
  73. Adding all of these produces a full Level 2 PostScript language
  74. interpreter.
  75.  
  76. Ghostscript also includes a number of operators defined below that are not
  77. in the PostScript language.
  78.  
  79. Ghostscript-specific additions
  80. ==============================
  81.  
  82. Miscellaneous
  83. -------------
  84.  
  85. ^Z is counted as whitespace.
  86.  
  87. run can take either a string or a file as its argument.  In the latter
  88. case, it just runs the file, closing it at the end, and trapping errors
  89. just as for the string case.
  90.  
  91. Mathematical operators
  92. ----------------------
  93.  
  94.     <number> arccos <number>
  95.         Computes the arc cosine of a number between -1 and 1.
  96.  
  97.     <number> arcsin <number>
  98.         Computes the arc sine of a number between -1 and 1.
  99.  
  100. String operators
  101. ----------------
  102.  
  103.     <state> <fromString> <toString> .type1encrypt <newState> <toSubstring>
  104.         Encrypts fromString according to the algorithm for Adobe
  105.           Type 1 fonts, writing the result into toString.
  106.           toString must be at least as long as fromString or a
  107.           rangecheck error occurs.  state is the initial state of
  108.           the encryption algorithm (a 16-bit non-negative
  109.           integer); newState is the new state of the algorithm.
  110.  
  111.     <state> <fromString> <toString> .type1decrypt <newState> <toSubstring>
  112.         Decrypts fromString according to the algorithm for Adobe
  113.           Type 1 fonts, writing the result into toString.  Other
  114.           specifications are as for type1encrypt.
  115.  
  116. Relational operators
  117. --------------------
  118.  
  119.     <number|string> <number|string> max <number|string>
  120.         Returns the larger of two numbers or strings.
  121.  
  122.     <number|string> <number|string> min <number|string>
  123.         Returns the smaller of two numbers or strings.
  124.  
  125. File operators
  126. --------------
  127.  
  128.     <string> findlibfile <foundstring> <file> true
  129.     <string> findlibfile <string> false
  130.         Opens the file of the given name for reading, searching
  131.           through directories as described in use.doc.  If the
  132.           search fails, findlibfile simply pushes false on the
  133.           stack and returns, rather than causing an error.
  134.  
  135.     <file> <integer> unread -
  136.          Pushes back the last-read character onto the front of the
  137.           file.  If the file is only open for writing, or if the
  138.           integer argument is not the same as the last character
  139.           read from the file, causes an ioerror error.  May also
  140.           cause an ioerror if the last operation on the file was not
  141.           a reading operation.
  142.  
  143.     <file> <device> writeppmfile -
  144.         Writes the contents of the device, which must be an image
  145.           device, onto the file, in Portable PixMap (ppm) format.
  146.           Does not close the file.
  147.  
  148. Path operators
  149. --------------
  150.  
  151.     <x> <y> <width> <height> rectappend -
  152.     <numarray> rectappend -
  153.     <numstring> rectappend -
  154.         Appends a rectangle or rectangles to the current path, in
  155.           the same manner as rectfill, rectclip, etc.  Only
  156.           defined if the dps option is selected.
  157.  
  158. Filters
  159. -------
  160.  
  161. Ghostscript supports all standard filters except DCTEncode and DCTDecode.
  162. Ghostscript does not support the use of a procedure as a data source or
  163. sink, only a file or a string.  In addition, Ghostscript supports the
  164. following non-standard filters:
  165.  
  166.     <target> <seed_integer> /eexecEncode filter <file>
  167.         Creates a filter for encrypting data into the
  168.           eexec encrypted format described in the
  169.           Adobe Type 1 Font Format documentation.  The
  170.           seed_integer must be 55665 for proper operation.
  171.           This filter produces binary output and does not
  172.           include the initial 4 garbage bytes.
  173.  
  174.     <source> <seed_integer> /eexecDecode filter <file>
  175.         Creates a filter for decrypting data that has been
  176.           encrypted using eexec encryption as described in the
  177.           Adobe Type 1 Font Format documentation.  The
  178.           seed_integer must be 55665 for proper operation.
  179.  
  180.     <source> <hex_boolean> /PFBDecode filter <file>
  181.         Creates a filter that decodes data in .PFB format, the
  182.           usual semi-binary representation for Type 1 font files
  183.           on IBM PC and compatible systems.  If hex_boolean is true,
  184.           binary packets are converted to hex; if false, binary
  185.           packets are not converted.
  186.  
  187. Ghostscript also supports a non-standard optional dictionary operand for
  188. the LZWDecode filter, with the following keys (all optional):
  189.  
  190.     InitialCodeLength <integer>
  191.         An integer between 2 and 11 specifying the initial number
  192. of data bits per code.  Note that the actual initial code length is 1
  193. greater than this, to allow for the reset and end-of-data code values.
  194. Default value: 8.
  195.  
  196.     FirstBitLowOrder <boolean>
  197.         If true, codes appear with their low-order bit first.
  198. Default value: false.
  199.  
  200.     BlockData <boolean>
  201.         If true, the data is broken into blocks in the manner
  202. specified for the GIF file format.  Default value: false.
  203.  
  204.     EarlyChange <integer>
  205.         If 0, codes become one bit longer one code earlier than
  206. they need to; if 1, codes become one bit longer as specified in the
  207. PostScript Language Reference Manual.  Default value: 1.
  208.  
  209. Miscellaneous operators
  210. -----------------------
  211.  
  212.     - currenttime <number>
  213.         Returns the current value of a continuously-running timer,
  214.           in minutes.  The initial value of this timer is undefined.
  215.  
  216.     <string> getenv <string> true
  217.     <string> getenv false
  218.         Looks up a name in the shell environment.  If the name is
  219.           found, returns the corresponding value and true; if the
  220.           name is not found, returns false.
  221.  
  222.     <name> <array> makeoperator <operator>
  223.         Constructs and returns a new operator that is actually the
  224.           given procedure in disguise.  The name is only used for
  225.           printing.  The operator has the executable attribute.
  226.  
  227.     <string> <boolean> .setdebug -
  228.         If the Ghostscript interpreter was built with the DEBUG
  229.           flag set, sets or resets any subset of the debugging
  230.           flags normally controlled by -Z in the command line.
  231.           Has no effect otherwise.
  232.  
  233.     - .oserrno <errno>
  234.         Returns the error code for the most recent OS error.
  235.  
  236.     - .oserror <string>
  237.         Returns the error string for the most recent OS error.
  238.  
  239. Device operators
  240. ----------------
  241.  
  242.     <device> copydevice <device>
  243.         Copies a device.
  244.  
  245.     <index> .getdevice <device>
  246.         Returns a device from the set of devices known to the
  247.           system.  The first device, which is default, is numbered
  248.           0.  If the index is out of range, causes a rangecheck
  249.           error.
  250.  
  251.     <matrix> <width> <height> <palette> makeimagedevice <device>
  252.         Makes a new device that accumulates an image in memory.
  253.           matrix is the initial transformation matrix: it must be
  254.           orthogonal (i.e., [a 0 0 b x y] or [0 a b 0 x y]).
  255.           palette is a string of 2^N or 3*2^N elements, specifying
  256.           how the 2^N possible pixel values will be interpreted.
  257.           Each element is interpreted as a gray value, or as RGB
  258.           values, multiplied by 255.  For example, if you want
  259.           a monochrome image for which 0=white and 1=black, the
  260.           palette should be <ff 00>; if you want a 3-bit deep
  261.           image with just the primary colors and their complements
  262.           (ignoring the fact that 3-bit images are not supported),
  263.           the palette might be <000000 0000ff 00ff00 00ffff
  264.           ff0000 ff00ff ffff00 ffffff>.  At present, the palette
  265.           must contain exactly 2, 4, 16, or 256 entries,
  266.           and must contain an entry for black and an entry
  267.           for white; if it contains any entries that aren't black,
  268.           white, or gray, it must contain at least the six primary
  269.           colors (red, green, blue, and their complements cyan,
  270.           magenta, and yellow); aside from this, its contents are
  271.           arbitrary.
  272.         Alternatively, palette can be null.  This is interpreted
  273.           as 24-bit-per-pixel color, where the four bytes of each
  274.           pixel are respectively R, G, and B.
  275.         Note that one can also make an image device (with the same
  276.           palette as an existing image device) by copying a device
  277.           using the copydevice operator.
  278.  
  279.     <device> <index> <string> copyscanlines <substring>
  280.         Copies one or more scan lines from an image device into a
  281.           string, starting at a given scan line in the image.
  282.           The data is in the same format as for the image
  283.           operator.  Error if the device is not an image device or
  284.           if the string is too small to hold at least one complete
  285.           scan line.  Always copies an integral number of scan
  286.           lines.
  287.  
  288.     <device> setdevice -
  289.         Sets the current device to the specified device.  Also
  290.           resets the transformation and clipping path to the
  291.           initial values for the device.
  292.  
  293.     - currentdevice <device>
  294.         Gets the current device from the graphics state.
  295.  
  296.     <device> devicename <string>
  297.         Gets the name of a device.
  298.  
  299.     <device> <matrix> deviceinitialmatrix <matrix>
  300.         Gets the initial matrix of a device, i.e., the one that
  301.           defaultmatrix would return if the device were the
  302.           current device.
  303.  
  304.     <device> getdeviceprops <mark> <name1> <value1> ... <namen> <valuen>
  305.         Gets all the properties of a device.  Currently defined
  306.           names and values for all devices are (those marked with
  307.           * will be removed in a future release):
  308.             HWBitsPerPixel <integer>
  309.                 Number of bits per pixel.
  310.             HWResolution [<float> <float>]
  311.                 X and Y resolution in pixels/inch.
  312.             * HWSize [<integer> <integer>]
  313.                 X and Y size in pixels.
  314.             InitialMatrix [<6 floats>]
  315.                 Initial transformation matrix.
  316.             * Name <string>
  317.                 Read-only.  The device name.
  318.             OutputDevice <name>
  319.                 The device name.
  320.             PageSize [<float> <float>]
  321.                 X and Y size in 1/72" units.
  322.             Colors, GrayValues, RedValues, GreenValues,
  323.               BlueValues, ColorValues
  324.                 As for the 'deviceinfo' operator of
  325.                   Display PostScript.
  326.         Some devices may only allow certain values for
  327.           HWResolution and PageSize.  The null device ignores
  328.           attempts to set PageSize; its size is always [0 0].
  329.         Red/Green/Blue/ColorValues are only defined if Colors > 1.
  330.         For printers, the following are also defined:
  331.             BufferSpace <integer>
  332.                 Buffer space for band lists, if the bitmap
  333.                   is too big to fit in RAM.
  334.             MaxBitmap <integer>
  335.                 Maximum space for a full bitmap in RAM.
  336.             OutputFile <string>
  337.                 () means send to printer directly,
  338.                   otherwise specifies the file name for
  339.                   output; a %d is replaced by the page #;
  340.                   on Unix systems, (|command) writes to a pipe
  341.             PageCount <integer>
  342.                 Read-only.  Counts the number of pages
  343.                   printed on the device.
  344.  
  345.     <mark> <name1> <value1> ... <namen> <valuen> <device>
  346.         putdeviceprops <device>
  347.         Sets properties of a device.  May cause undefined,
  348.           typecheck, rangecheck, or limitcheck errors.
  349.  
  350.     - flushpage -
  351.         On displays, flushes any buffered output, so that it
  352.           is guaranteed to show up on the screen; on printers,
  353.           has no effect.
  354.  
  355. Character operators
  356. -------------------
  357.  
  358.     <string> .type1addpath -
  359.     <string> <lsbx> <lsby> .type1addpath -
  360.         Adds the description of a character to the current
  361.           path.  The string argument is a scalable
  362.           description encoded in Adobe Type 1 format.  This
  363.           operator, like setcharwidth and setcachedevice, is
  364.           only valid in the context of a show operator.  It
  365.           uses information from the current font, in addition
  366.           to the argument(s).
  367.         The optional lsbx and lsby arguments are left side
  368.           bearing values that override the ones in the
  369.           character outline.
  370.  
  371.     <font> <char> Type1BuildChar -
  372.         This is not a new operator: rather, it is a name known
  373.           specially to the interpreter.  Whenever the interpreter
  374.           needs to render a character (during a ...show,
  375.           stringwidth, or charpath), it looks up the name
  376.           BuildChar in the font dictionary to find a procedure to
  377.           run.  If it does not find this name, and if the FontType
  378.           is 1, the interpreter instead uses the value (looked up
  379.           on the dictionary stack in the usual way) of the name
  380.           Type1BuildChar.
  381.         The standard definition of Type1BuildChar is in gs_fonts.ps.
  382.           Users should not need to redefine Type1BuildChar, except
  383.           perhaps for tracing or debugging.
  384.  
  385. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  386.  
  387. PostScript is a trademark of Adobe Systems, Incorporated.
  388.