summaryrefslogtreecommitdiff
path: root/Master/xemtex/doc/ghostscript/Source.htm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/xemtex/doc/ghostscript/Source.htm')
-rw-r--r--Master/xemtex/doc/ghostscript/Source.htm383
1 files changed, 383 insertions, 0 deletions
diff --git a/Master/xemtex/doc/ghostscript/Source.htm b/Master/xemtex/doc/ghostscript/Source.htm
new file mode 100644
index 00000000000..348920b4e22
--- /dev/null
+++ b/Master/xemtex/doc/ghostscript/Source.htm
@@ -0,0 +1,383 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<title>Guide to Ghostscript source code</title>
+<!-- $Id: Source.htm,v 1.13.2.11.2.5 2003/05/17 14:39:00 giles Exp $ -->
+<!-- Originally: source.txt -->
+<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
+</head>
+
+<body>
+<!-- [1.0 begin visible header] ============================================ -->
+
+<!-- [1.1 begin headline] ================================================== -->
+
+<h1>Guide to Ghostscript source code</h1>
+
+<!-- [1.1 end headline] ==================================================== -->
+
+<!-- [1.2 begin table of contents] ========================================= -->
+
+<h2>Table of contents</h2>
+
+<blockquote><ul>
+<li><a href="#Overview">Conceptual overview</a>
+<li><a href="#PostScript_interpreter">PostScript Interpreter</a>
+<li><a href="#PDF_interpreter">PDF interpreter</a>
+<li><a href="#Graphics_library">Graphics library</a>
+<ul>
+<li><a href="#Drivers">Device drivers</a>
+<li><a href="#Platform_specific_code">Platform-specific code</a>
+</ul>
+<li><a href="#Makefiles">Makefiles</a>
+</ul></blockquote>
+
+<!-- [1.2 end table of contents] =========================================== -->
+
+<!-- [1.3 begin hint] ====================================================== -->
+
+<p>For other information, see the <a href="Readme.htm">Ghostscript
+overview</a> and the documents on <a href="Make.htm">how to build
+Ghostscript</a> from source, <a href="C-style.htm">Ghostscript C coding
+guidelines</a>, <a href="Drivers.htm">drivers</a>, the
+<a href="Lib.htm">Ghostscript library</a> and <a href="Install.htm">how to
+install Ghostscript</a>.
+
+<!-- [1.3 end hint] ======================================================== -->
+
+<hr>
+
+<!-- [1.0 end visible header] ============================================== -->
+
+<!-- [2.0 begin contents] ================================================== -->
+
+<h2><a name="Overview"></a>Conceptual overview</h2>
+
+<p>
+The Ghostscript source code is divided conceptually as follows:
+
+<blockquote><table cellpadding=0 cellspacing=0>
+<tr valign=top> <th align=left colspan=4><a href="#PostScript_interpreter">PostScript interpreter</a>:
+<tr valign=top> <td>&nbsp;&nbsp;&nbsp;&nbsp;
+ <td>PostScript operators
+ <td>&nbsp;&nbsp;&nbsp;&nbsp;
+ <td><b><tt>z</tt></b>*<b><tt>.h</tt></b> and <b><tt>z</tt></b>*<b><tt>.c</tt></b>
+<tr valign=top> <td>&nbsp;
+ <td>Other interpreter code
+ <td>&nbsp;
+ <td><b><tt>i</tt></b>*<b><tt>.h</tt></b> and <b><tt>i</tt></b>*<b><tt>.c</tt></b>
+<tr valign=top> <td>&nbsp;
+ <td>PostScript code
+ <td>&nbsp;
+ <td><b><tt>gs_</tt></b>*<b><tt>.ps</tt></b>
+<tr valign=top> <th align=left colspan=4><a href="#PDF_interpreter">PDF interpreter</a>:
+<tr valign=top> <td>&nbsp;
+ <td>PostScript code
+ <td>&nbsp;
+ <td><b><tt>pdf_</tt></b>*<b><tt>.ps</tt></b>
+<tr valign=top> <th align=left colspan=4><a href="#Graphics_library">Graphics library</a>:
+<tr valign=top> <td>&nbsp;
+ <td>Main library code
+ <td>&nbsp;
+ <td><b><tt>g</tt></b>*<b><tt>.h</tt></b> and <b><tt>g</tt></b>*<b><tt>.c</tt></b>
+<tr valign=top> <td>&nbsp;
+ <td>Streams
+ <td>&nbsp;
+ <td><b><tt>s</tt></b>*<b><tt>.h</tt></b> and <b><tt>s</tt></b>*<b><tt>.c</tt></b>
+<tr valign=top> <td>&nbsp;
+ <td><a href="#Drivers">Device drivers</a>
+ <td>&nbsp;
+ <td><b><tt>gdev</tt></b>*<b><tt>.h</tt></b> and <b><tt>gdev</tt></b>*<b><tt>.c</tt></b>
+<tr valign=top> <td>&nbsp;
+ <td><a href="#Platform_specific_code">Platform-specific code</a>
+ <td>&nbsp;
+ <td><b><tt>gp</tt></b>*<b><tt>.h</tt></b> and <b><tt>gp</tt></b>*<b><tt>.c</tt></b>
+</table></blockquote>
+
+<hr>
+
+<h2><a name="PostScript_interpreter"></a>PostScript Interpreter</h2>
+
+<p>
+<b><tt>gs.c</tt></b> is the main program for the interactive language
+interpreter; <b><tt>gserver.c</tt></b> is an alternative main program that
+is a rudimentary server. If you configure Ghostscript as a server rather
+than an interactive program, you will use <b><tt>gserver.c</tt></b> instead
+of <b><tt>gs.c</tt></b>.
+
+<p>
+Files named <b><tt>z</tt></b>*<b><tt>.c</tt></b> are Ghostscript operator
+files. The names of the files generally follow the section headings of the
+operator summary in section 6.2 (Second Edition) or 8.2 (Third Edition) of
+the PostScript Language Reference Manual. Each operator XXX is implemented
+by a procedure named <b><tt>z</tt></b>XXX, for example,
+<b><tt>zfill</tt></b> and <b><tt>zarray</tt></b>.
+
+<p>
+Files named <b><tt>i</tt></b>*<b><tt>.c</tt></b>, and *<b><tt>.h</tt></b>
+other than <b><tt>g</tt></b>*<b><tt>.h</tt></b>, are the rest of the
+interpreter. See the makefile for a little more information on how the
+files are divided functionally.
+
+<p>
+The main loop of the PostScript interpreter is the <b><tt>interp</tt></b>
+procedure in <b><tt>interp.c</tt></b>. When the interpreter is reading
+from an input file, it calls the token scanner in
+<b><tt>iscan</tt></b>*<b><tt>.c</tt></b>.
+
+<p>
+<b><tt>idebug.c</tt></b> contains a lot of debugger-callable routines
+useful for printing PostScript objects when debugging.
+
+<hr>
+
+<h2><a name="PDF_interpreter"></a>PDF interpreter</h2>
+
+<p>
+The PDF interpreter is written entirely in PostScript. Its main loop is
+the <b><tt>.pdfrun</tt></b> procedure in <b><tt>pdf_base.ps</tt></b>. When
+the PDF interpreter is configured into the build, it redefines the
+"<b><tt>run</tt></b>" operator to test whether the file is a PDF file.
+This redefinition is near the beginning of <b><tt>pdf_main.ps</tt></b>.
+
+<hr>
+
+<h2><a name="Graphics_library"></a>Graphics library</h2>
+
+<p>
+Files beginning with <b><tt>gs</tt></b>, <b><tt>gx</tt></b>, or
+<b><tt>gz</tt></b> (both <b><tt>.c</tt></b> and <b><tt>.h</tt></b>), other
+than <b><tt>gs.c</tt></b> and <b><tt>gserver.c</tt></b>, are the
+Ghostscript library. Files beginning with <b><tt>gdev</tt></b> are device
+drivers or related code, also part of the library. Other files beginning
+with <b><tt>g</tt></b> are library files that don't fall neatly into either
+the kernel or the driver category.
+
+<p>
+Files named <b><tt>s</tt></b>*<b><tt>.c</tt></b> and
+<b><tt>s</tt></b>*<b><tt>.h</tt></b> are a flexible stream package,
+including the Level 2 PostScript "filters" supported by Ghostscript. See
+<b><tt>stream.h</tt></b>, <b><tt>scommon.h</tt></b>, and
+<b><tt>strimpl.h</tt></b> for all the details.
+
+<h3><a name="Drivers"></a>Device drivers</h3>
+
+<p>
+The interface between the graphics library and device drivers is the only
+really well documented one in all of Ghostscript: see the
+<a href="Drivers.htm">documentation on drivers</a>.
+
+<p>
+In addition to many real device and file format drivers listed in
+<b><tt>devs.mak</tt></b> and <b><tt>contrib.mak</tt></b>, a number of
+drivers are used for internal purposes. You can search
+<b><tt>lib.mak</tt></b> for files named
+<b><tt>gdev</tt></b>*<b><tt>.c</tt></b> to find almost all of them.
+
+<p>
+Drivers are divided into "printer" drivers, which support banding, and
+non-printer drivers, which don't. The decision whether banding is
+required is made (by default on the basis of how much memory is available)
+in the procedure <b><tt>gdev_prn_alloc</tt></b> in
+<b><tt>gdevprn.c</tt></b>: it implements this decision by filling the
+virtual procedure table for the printer device in one of two different
+ways.
+
+<p>
+A good simple "printer" (bandable) driver to read is
+<b><tt>gdevmiff.c</tt></b>: it's less than 100 lines, of which much is
+boilerplate. There are no simple non-printer drivers that actually drive
+devices: probably the simplest non-printer driver for reading is
+<b><tt>gdevm8.c</tt></b>, which implements 8-bit-deep devices that only
+store the bits in memory.
+
+<h3><a name="Platform_specific_code"></a>Platform-specific code</h3>
+
+<p>
+There are very few platform dependencies in Ghostscript. Ghostscript deals
+with them in three ways:
+
+<ul>
+<li>Files named *<b><tt>_.h</tt></b> substitute for the corresponding
+<b><tt>&lt;</tt></b>*<b><tt>.h&gt;</tt></b> file by adding conditionals
+that provide a uniform set of system interfaces on all platforms.
+
+<li>The file <b><tt>arch.h</tt></b> contains a set of
+mechanically-discovered platform properties like byte order, size of
+<b><tt>int</tt></b>, etc. These properties, <b>not</b> the names of
+specific platforms, are used to select between different algorithms or
+parameters at compile time.
+
+<li>Files named <b><tt>gp</tt></b>*<b><tt>.h</tt></b> define interfaces
+that are intended to be implemented differently on each platform, but whose
+specification is common to all platforms.
+</ul>
+
+<p>
+The platform-specific implementations of the
+<b><tt>gp</tt></b>*<b><tt>.h</tt></b> interfaces have names of the form
+"<b><tt>gp_</tt></b><em>{platform}</em><b><tt>.c</tt></b>, specifically
+(this list may be out of date):
+
+<blockquote><table cellpadding=0 cellspacing=0>
+<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Platform-specific interfaces</font><hr>
+<tr valign=bottom>
+ <th align=left>Routine
+ <td>&nbsp;&nbsp;&nbsp;&nbsp;
+ <th align=left>Platform
+<tr> <td colspan=3><hr>
+<tr valign=top> <td><b><tt>gp_dosfb.c</tt></b>
+ <td>&nbsp;
+ <td>DOS
+<tr valign=top> <td><b><tt>gp_dosfs.c</tt></b>
+ <td>&nbsp;
+ <td>DOS and MS Windows
+<tr valign=top> <td><b><tt>gp_itbc.c</tt></b>
+ <td>&nbsp;
+ <td>DOS, Borland compilers
+<tr valign=top> <td><b><tt>gp_iwatc.c</tt></b>
+ <td>&nbsp;
+ <td>DOS, Watcom or Microsoft compiler
+<tr valign=top> <td><b><tt>gp_msdos.c</tt></b>
+ <td>&nbsp;
+ <td>DOS and MS Windows
+<tr valign=top> <td><b><tt>gp_ntfs.c</tt></b>
+ <td>&nbsp;
+ <td>MS-Windows Win32s and Windows NT
+<tr valign=top> <td><b><tt>gp_os2.c</tt></b>
+ <td>&nbsp;
+ <td>OS/2
+<tr valign=top> <td><b><tt>gp_os9.c</tt></b>
+ <td>&nbsp;
+ <td>OS-9
+<tr valign=top> <td><b><tt>gp_unifs.c</tt></b>
+ <td>&nbsp;
+ <td>Unix, OS-9, and QNX
+<tr valign=top> <td><b><tt>gp_unix.c</tt></b>
+ <td>&nbsp;
+ <td>Unix and QNX
+<tr valign=top> <td><b><tt>gp_sysv.c</tt></b>
+ <td>&nbsp;
+ <td>System V Unix
+<tr valign=top> <td><b><tt>gp_vms.c</tt></b>
+ <td>&nbsp;
+ <td>VMS
+<tr valign=top> <td><b><tt>gp_win32.c</tt></b>
+ <td>&nbsp;
+ <td>MS-Windows Win32s and Windows NT
+</table></blockquote>
+
+<p>
+If you are going to extend Ghostscript to new machines or operating
+systems, check the *<b><tt>_.h</tt></b> files for <b><tt>ifdef</tt></b> on
+things other than <b><tt>DEBUG</tt></b>. You should probably plan to make
+a new makefile and a new <b><tt>gp_</tt></b>XXX<b><tt>.c</tt></b> file.
+
+<hr>
+
+<h2><a name="Makefiles"></a>Makefiles</h2>
+
+<p>
+This section is only for advanced developers who need to integrate
+Ghostscript into a larger program at build time.
+
+<p>
+NOTE: THIS SECTION IS INCOMPLETE. IT WILL BE IMPROVED IN A LATER REVISION.
+
+<p>
+The Ghostscript makefiles are meant to be organized according to the
+following two principles:
+
+<ul>
+
+<li>All the parameters that vary from platform to platform appear in the
+top-level makefile for a given platform. ("Platform" = OS + compiler +
+choice of interpreter vs. library)
+
+<li>All the rules and definitions that can meaningfully be shared among more
+than 1 platform appear in a makefile that is "included" by a makefile
+(normally the top-level makefile) for those platforms.
+</ul>
+
+<p>
+Thus, for example:
+
+<ul>
+
+<li>Rules and definitions shared by all builds are in
+<b><tt>gs.mak</tt></b>.
+
+<li>Rules and definitions specific to the library (on all platforms) are in
+<b><tt>lib.mak</tt></b>. In principle this could be merged with
+<b><tt>gs.mak</tt></b>, but we wanted to leave open the possibility that
+<b><tt>gs.mak</tt></b> might be useful with hypothetical interpreter-only
+products.
+
+<li>Stuff specific to interpreters (on all platforms) is in
+<b><tt>int.mak</tt></b>.
+
+<li>Stuff specific to all Unix platforms should be in a single
+<b><tt>unix.mak</tt></b> file, but because <b><tt>make</tt></b> sometimes
+cares about the order of definitions, and because some of it is shared with
+DV/X, it got split between <b><tt>unix-aux.mak</tt></b>,
+<b><tt>unix-end.mak</tt></b>, <b><tt>unixhead.mak</tt></b>,
+<b><tt>unixinst.mak</tt></b>, and <b><tt>unixlink.mak</tt></b>.
+
+</ul>
+
+<p>
+For MS-DOS and MS Windows builds, there should be:
+
+<ul>
+
+<li>A makefile for all MS OS (DOS or Windows) builds, for all
+ compilers and products.
+
+<li>Perhaps a makefile for all MS-DOS builds, for all compilers and
+products, although since Watcom is the only such compiler we're likely to
+support this may be overkill.
+
+<li>A makefile for all MS Windows builds, for all compilers and products.
+
+<li>A makefile for all Watcom builds (DOS or Windows), for all products.
+
+<li>A top-level makefile for the Watcom DOS interpreter product.
+
+<li>A top-level makefile for the Watcom Windows interpreter product.
+
+<li>A top-level makefile for the Watcom DOS library "product".
+
+<li>A top-level makefile for the Watcom Windows library "product".
+
+<li>A makefile for all Borland builds (DOS or Windows), for all
+ products.
+
+</ul>
+
+<p>
+and so on.
+
+<!-- [2.0 end contents] ==================================================== -->
+
+<!-- [3.0 begin visible trailer] =========================================== -->
+<hr>
+
+<p>
+<small>Copyright &copy; 1996, 1997, 1998 Aladdin Enterprises. All
+rights reserved.</small>
+
+<p>
+This software is provided AS-IS with no warranty, either express or
+implied.
+
+This software is distributed under license and may not be copied,
+modified or distributed except as expressly authorized under the terms
+of the license contained in the file LICENSE in this distribution.
+
+<p>
+<small>Ghostscript version 7.07, 17 May 2003
+
+<!-- [3.0 end visible trailer] ============================================= -->
+
+</body>
+</html>