home *** CD-ROM | disk | FTP | other *** search
/ swCHIP 1991 January / swCHIP_95-1.bin / utility / gs333ini / gs3.33 / language.doc < prev    next >
Text File  |  1995-12-09  |  18KB  |  467 lines
  1.    Copyright (C) 1989, 1995 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
  21. Ghostscript interpreter and the PostScript language.  This file describes
  22. version 3.33 of Ghostscript.
  23.  
  24. For an overview of Ghostscript and a list of the documentation files, see
  25. README.
  26.  
  27. The Ghostscript interpreter, except as noted below, is intended to execute
  28. properly any source program written in the (Level 2) PostScript language as
  29. defined in the December 1990 printing of the PostScript Language Reference
  30. Manual (Second Edition) published by Addison-Wesley (ISBN 0-201-18127-4).
  31. However, the interpreter is configurable in ways that can restrict it to
  32. various subsets of this language.  Specifically, the base interpreter
  33. accepts the Level 1 subset of the PostScript language, as defined in the
  34. first edition of the PostScript Language Reference Manual, ISBN
  35. 0-201-10174-2, Addison-Wesley, 1985, plus the file system, version 25.0
  36. language, and miscellaneous additions listed in sections A.1.6, A.1.7, and
  37. A.1.8 of the Second Edition respectively, including allowing a string
  38. operand for the 'status' operator.  The base interpreter may be configured
  39. by adding any combination of the following:
  40.  
  41.     - The ability to process PostScript Type 1 fonts.  This facility is
  42. normally included in the interpreter.
  43.  
  44.     - The CMYK color extensions listed in section A.1.4 of the Second
  45. Edition (including colorimage).  These facilities are only available if the
  46. color, dps, or level2 feature was selected at the time that Ghostscript was
  47. compiled and linked.
  48.  
  49.     - The Display PostScript extensions listed in section A.1.3
  50. of the Second Edition, but excluding the operators listed in section
  51. A.1.2.  These facilities are only available if the dps feature or the
  52. level2 feature was selected at the time that Ghostscript was compiled
  53. and linked.
  54.  
  55.     - The composite font extensions listed in section A.1.5 of the
  56. Second Edition, and the ability to handle Type 0 fonts.  These facilities
  57. are only available if the compfont feature or the level2 feature was
  58. selected at the time that Ghostscript was compiled and linked.
  59.  
  60.     - The PostScript Level 2 "filter" facilities aside from DCTEncode
  61. and DCTDecode filters.  These facilities are only available if the filter,
  62. dps, or level2 feature was selected at the time that Ghostscript was
  63. compiled and linked.
  64.  
  65.     - The PostScript Level 2 DCTEncode and DCTDecode filters.  These
  66. facilities are only available if the dct or level2 feature was selected at
  67. the time that Ghostscript was compiled and linked.
  68.  
  69.     - All the other PostScript Level 2 operators and facilities listed
  70. in section A.1.1 of the Second Edition and not listed in any of the other
  71. A.1.n sections.  These facilities are only available if the level2 feature
  72. was selected at the time that Ghostscript was compiled and linked.
  73.  
  74. Adding all of these produces a full Level 2 PostScript language
  75. interpreter.
  76.  
  77. Ghostscript also includes a number of operators defined below that are not
  78. in the PostScript language.
  79.  
  80. Implementation limits
  81. =====================
  82.  
  83. The following implementation limits correspond to those in Table B.1 and
  84. B.2 of the Second Edition.  Those marked with * are different from the ones
  85. in the Second Edition.
  86.  
  87. Architectural limits
  88. --------------------
  89.  
  90. integer        32-bit two's complement integer
  91. real        single-precision IEEE float
  92. *array
  93.     On 16-bit systems:    8191 elements
  94.     On 32-bit systems:    65535 elements
  95. *dictionary
  96.     On 16-bit systems:    8190 elements
  97.     On 32-bit systems:    65534 elements
  98. *string        65535 characters
  99. *name        16383 characters
  100. filename    100 characters
  101. *save level    none (capacity of memory)
  102. *gsave level    none (capacity of memory)
  103.  
  104. Typical memory limits in Level 1
  105. --------------------------------
  106.  
  107. userdict        200
  108. FontDirectory        100
  109. *operand stack        800
  110. dictionary stack    20
  111. execution stack        250
  112. *interpreter level    none (capacity of memory)
  113. *path            none (capacity of memory)
  114. dash            11
  115. *VM            capacity of memory
  116. *file            determined by operating system
  117. *image            65535 values (samples x components) for 1, 2, 4,
  118.               or 8-bit samples; 32767 values for 12-bit samples
  119.  
  120. Other differences in VM consumption
  121. -----------------------------------
  122.  
  123. Packed array elements occupy either 2 bytes or 8 bytes.  The average
  124. element size is probably about 5 bytes.
  125.  
  126. Names occupy 12 bytes plus the space for the string.
  127.  
  128. Ghostscript-specific additions
  129. ==============================
  130.  
  131. Miscellaneous
  132. -------------
  133.  
  134. ^D and ^Z are self-delimiting tokens, like [ and ].  They are initially
  135. defined as empty procedures so that they will be ignored in the input
  136. stream.
  137.  
  138. run can take either a string or a file as its argument.  In the latter
  139. case, it just runs the file, closing it at the end, and trapping errors
  140. just as for the string case.
  141.  
  142. Mathematical operators
  143. ----------------------
  144.  
  145.     <number> arccos <number>
  146.         Computes the arc cosine of a number between -1 and 1.
  147.  
  148.     <number> arcsin <number>
  149.         Computes the arc sine of a number between -1 and 1.
  150.  
  151. String operators
  152. ----------------
  153.  
  154.     <state> <fromString> <toString> .type1encrypt <newState> <toSubstring>
  155.         Encrypts fromString according to the algorithm for Adobe
  156.           Type 1 fonts, writing the result into toString.
  157.           toString must be at least as long as fromString or a
  158.           rangecheck error occurs.  state is the initial state of
  159.           the encryption algorithm (a 16-bit non-negative
  160.           integer); newState is the new state of the algorithm.
  161.  
  162.     <state> <fromString> <toString> .type1decrypt <newState> <toSubstring>
  163.         Decrypts fromString according to the algorithm for Adobe
  164.           Type 1 fonts, writing the result into toString.  Other
  165.           specifications are as for type1encrypt.
  166.  
  167. Relational operators
  168. --------------------
  169.  
  170.     <number|string> <number|string> max <number|string>
  171.         Returns the larger of two numbers or strings.
  172.  
  173.     <number|string> <number|string> min <number|string>
  174.         Returns the smaller of two numbers or strings.
  175.  
  176. File operators
  177. --------------
  178.  
  179.     <string> findlibfile <foundstring> <file> true
  180.     <string> findlibfile <string> false
  181.         Opens the file of the given name for reading, searching
  182.           through directories as described in use.doc.  If the
  183.           search fails, findlibfile simply pushes false on the
  184.           stack and returns, rather than causing an error.
  185.  
  186.     <file> <integer> unread -
  187.          Pushes back the last-read character onto the front of the
  188.           file.  If the file is only open for writing, or if the
  189.           integer argument is not the same as the last character
  190.           read from the file, causes an ioerror error.  May also
  191.           cause an ioerror if the last operation on the file was not
  192.           a reading operation.
  193.  
  194.     <file> <device> writeppmfile -
  195.         Writes the contents of the device, which must be an image
  196.           device, onto the file, in Portable PixMap (ppm) format.
  197.           Does not close the file.
  198.  
  199. Path operators
  200. --------------
  201.  
  202.     <x> <y> <width> <height> rectappend -
  203.     <numarray> rectappend -
  204.     <numstring> rectappend -
  205.         Appends a rectangle or rectangles to the current path, in
  206.           the same manner as rectfill, rectclip, etc.  Only
  207.           defined if the dps option is selected.
  208.  
  209. Filters
  210. -------
  211.  
  212. Ghostscript supports all the standard PostScript Level 2 filters.  In
  213. addition, Ghostscript supports the following non-standard filters:
  214.  
  215.     <target> <seed_integer> /eexecEncode filter <file>
  216.         Creates a filter for encrypting data into the
  217.           eexec encrypted format described in the
  218.           Adobe Type 1 Font Format documentation.  The
  219.           seed_integer must be 55665 for proper operation.
  220.           This filter produces binary output and does not
  221.           include the initial 4 garbage bytes.
  222.  
  223.     <source> <seed_integer> /eexecDecode filter <file>
  224.         Creates a filter for decrypting data that has been
  225.           encrypted using eexec encryption as described in the
  226.           Adobe Type 1 Font Format documentation.  The
  227.           seed_integer must be 55665 for proper operation.
  228.  
  229.     <source> <hex_boolean> /PFBDecode filter <file>
  230.         Creates a filter that decodes data in .PFB format, the
  231.           usual semi-binary representation for Type 1 font files
  232.           on IBM PC and compatible systems.  If hex_boolean is true,
  233.           binary packets are converted to hex; if false, binary
  234.           packets are not converted.
  235.  
  236. Various versions of Ghostscript may also support other non-standard filters
  237. for experimental purposes.  The current version includes the following
  238. non-standard filters, which are not documented further.  No guarantee is
  239. made that these filters will exist in compatible form, or at all, in future
  240. versions.
  241.  
  242.     <target/source> <string> ByteTranslateEncode/Decode
  243.     <target> <int> BigStringEncode
  244.     <target/source> BCPEncode/Decode
  245.     <target/source> TBCPEncode/Decode
  246.     <target/source> <dict> BoundedHuffmanEncode/Decode
  247.         FirstBitLowOrder <bool> false
  248.         MaxCodeLength <int> 16
  249.         EndOfData <bool> true
  250.         EncodeZeroRuns <int> 256
  251.         Tables <int_array>
  252.     <target/source> <dict> BWBlockSortEncode/Decode
  253.         BlockSize <int> 16384
  254.     <target/source> MoveToFrontEncode/Decode
  255.  
  256. Ghostscript also supports a non-standard optional dictionary operand for
  257. the LZWDecode filter, with the following keys (all optional):
  258.  
  259.     InitialCodeLength <integer>
  260.         An integer between 2 and 11 specifying the initial number
  261. of data bits per code.  Note that the actual initial code length is 1
  262. greater than this, to allow for the reset and end-of-data code values.
  263. Default value: 8.
  264.  
  265.     FirstBitLowOrder <boolean>
  266.         If true, codes appear with their low-order bit first.
  267. Default value: false.
  268.  
  269.     BlockData <boolean>
  270.         If true, the data is broken into blocks in the manner
  271. specified for the GIF file format.  Default value: false.
  272.  
  273.     EarlyChange <integer>
  274.         If 0, codes become one bit longer one code earlier than
  275. they need to; if 1, codes become one bit longer as specified in the
  276. PostScript Language Reference Manual.  Default value: 1.
  277.  
  278. Virtual memory operators
  279. ------------------------
  280.  
  281.     <save> .forgetsave -
  282.         Cancels the effect of a save -- makes it as though the
  283.           save never happened.
  284.  
  285. Miscellaneous operators
  286. -----------------------
  287.  
  288.     - currenttime <number>
  289.         Returns the current value of a continuously-running timer,
  290.           in minutes.  The initial value of this timer is undefined.
  291.  
  292.     <string> getenv <string> true
  293.     <string> getenv false
  294.         Looks up a name in the shell environment.  If the name is
  295.           found, returns the corresponding value and true; if the
  296.           name is not found, returns false.
  297.  
  298.     <name> <array> makeoperator <operator>
  299.         Constructs and returns a new operator that is actually the
  300.           given procedure in disguise.  The name is only used for
  301.           printing.  The operator has the executable attribute.
  302.  
  303.     <string> <boolean> .setdebug -
  304.         If the Ghostscript interpreter was built with the DEBUG
  305.           flag set, sets or resets any subset of the debugging
  306.           flags normally controlled by -Z in the command line.
  307.           Has no effect otherwise.
  308.  
  309.     - .oserrno <errno>
  310.         Returns the error code for the most recent OS error.
  311.  
  312.     - .oserror <string>
  313.         Returns the error string for the most recent OS error.
  314.  
  315. Device operators
  316. ----------------
  317.  
  318.     <device> copydevice <device>
  319.         Copies a device.
  320.  
  321.     <index> .getdevice <device>
  322.         Returns a device from the set of devices known to the
  323.           system.  The first device, which is default, is numbered
  324.           0.  If the index is out of range, causes a rangecheck
  325.           error.
  326.  
  327.     <matrix> <width> <height> <palette> makeimagedevice <device>
  328.         Makes a new device that accumulates an image in memory.
  329.           matrix is the initial transformation matrix: it must be
  330.           orthogonal (i.e., [a 0 0 b x y] or [0 a b 0 x y]).
  331.           palette is a string of 2^N or 3*2^N elements, specifying
  332.           how the 2^N possible pixel values will be interpreted.
  333.           Each element is interpreted as a gray value, or as RGB
  334.           values, multiplied by 255.  For example, if you want
  335.           a monochrome image for which 0=white and 1=black, the
  336.           palette should be <ff 00>; if you want a 3-bit deep
  337.           image with just the primary colors and their complements
  338.           (ignoring the fact that 3-bit images are not supported),
  339.           the palette might be <000000 0000ff 00ff00 00ffff
  340.           ff0000 ff00ff ffff00 ffffff>.  At present, the palette
  341.           must contain exactly 2, 4, 16, or 256 entries,
  342.           and must contain an entry for black and an entry
  343.           for white; if it contains any entries that aren't black,
  344.           white, or gray, it must contain at least the six primary
  345.           colors (red, green, blue, and their complements cyan,
  346.           magenta, and yellow); aside from this, its contents are
  347.           arbitrary.
  348.         Alternatively, palette can be null.  This is interpreted
  349.           as 24-bit-per-pixel color, where the four bytes of each
  350.           pixel are respectively R, G, and B.
  351.         Note that one can also make an image device (with the same
  352.           palette as an existing image device) by copying a device
  353.           using the copydevice operator.
  354.  
  355.     <device> <index> <string> copyscanlines <substring>
  356.         Copies one or more scan lines from an image device into a
  357.           string, starting at a given scan line in the image.
  358.           The data is in the same format as for the image
  359.           operator.  Error if the device is not an image device or
  360.           if the string is too small to hold at least one complete
  361.           scan line.  Always copies an integral number of scan
  362.           lines.
  363.  
  364.     <device> setdevice -
  365.         Sets the current device to the specified device.  Also
  366.           resets the transformation and clipping path to the
  367.           initial values for the device.
  368.  
  369.     - currentdevice <device>
  370.         Gets the current device from the graphics state.
  371.  
  372.     <device> getdeviceprops <mark> <name1> <value1> ... <namen> <valuen>
  373.         Gets all the properties of a device.  Currently defined
  374.           names and values for all devices are:
  375.             BitsPerPixel <integer>
  376.                 Usually read-only.  Number of bits per pixel.
  377.             .HWMargins [<4 floats>]
  378.                 Size of non-imageable regions around edges
  379.                   of page, in 1/72" units.
  380.             HWSize [<integer> <integer>]
  381.                 X and Y size in pixels.
  382.             Name <string>
  383.                 Read-only.  The device name.
  384.                   Currently, same as OutputDevice.
  385.             Colors, GrayValues, RedValues, GreenValues,
  386.               BlueValues, ColorValues
  387.                 As for the 'deviceinfo' operator of
  388.                   Display PostScript.
  389.         In addition, the following are defined per Adobe's
  390.           documentation for the setpagedevice operator:
  391.             Duplex (if supported)
  392.             HWResolution
  393.             ImagingBBox
  394.             Margins
  395.             NumCopies (for printers only)
  396.             Orientation (if supported)
  397.             OutputDevice
  398.             PageSize
  399.             ProcessColorModel
  400.         Some devices may only allow certain values for
  401.           HWResolution and PageSize.  The null device ignores
  402.           attempts to set PageSize; its size is always [0 0].
  403.         Red/Green/Blue/ColorValues are only defined if Colors > 1.
  404.         For printers, the following are also defined:
  405.             BufferSpace <integer>
  406.                 Buffer space for band lists, if the bitmap
  407.                   is too big to fit in RAM.
  408.             MaxBitmap <integer>
  409.                 Maximum space for a full bitmap in RAM.
  410.             OutputFile <string>
  411.                 () means send to printer directly,
  412.                   otherwise specifies the file name for
  413.                   output; a %d is replaced by the page #;
  414.                   on Unix systems, (|command) writes to a pipe
  415.             OpenOutputFile <boolean>
  416.                 If true, open the device's output file
  417.                   when the device is opened, rather than
  418.                   waiting until the first page is ready to
  419.                   print.
  420.             .PageCount <integer>
  421.                 Read-only.  Counts the number of pages
  422.                   printed on the device.
  423.  
  424.     <mark> <name1> <value1> ... <namen> <valuen> <device>
  425.         putdeviceprops <device>
  426.         Sets properties of a device.  May cause undefined,
  427.           typecheck, rangecheck, or limitcheck errors.
  428.  
  429.     - flushpage -
  430.         On displays, flushes any buffered output, so that it
  431.           is guaranteed to show up on the screen; on printers,
  432.           has no effect.
  433.  
  434. Character operators
  435. -------------------
  436.  
  437.     <string> .type1addpath -
  438.     <string> <lsbx> <lsby> .type1addpath -
  439.         Adds the description of a character to the current
  440.           path.  The string argument is a scalable
  441.           description encoded in Adobe Type 1 format.  This
  442.           operator, like setcharwidth and setcachedevice, is
  443.           only valid in the context of a show operator.  It
  444.           uses information from the current font, in addition
  445.           to the argument(s).
  446.         The optional lsbx and lsby arguments are left side
  447.           bearing values that override the ones in the
  448.           character outline.
  449.  
  450.     <font> <char> Type1BuildChar -
  451.         This is not a new operator: rather, it is a name known
  452.           specially to the interpreter.  Whenever the interpreter
  453.           needs to render a character (during a ...show,
  454.           stringwidth, or charpath), it looks up the name
  455.           BuildChar in the font dictionary to find a procedure to
  456.           run.  If it does not find this name, and if the FontType
  457.           is 1, the interpreter instead uses the value (looked up
  458.           on the dictionary stack in the usual way) of the name
  459.           Type1BuildChar.
  460.         The standard definition of Type1BuildChar is in gs_fonts.ps.
  461.           Users should not need to redefine Type1BuildChar, except
  462.           perhaps for tracing or debugging.
  463.  
  464. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  465.  
  466. PostScript is a trademark of Adobe Systems, Incorporated.
  467.