Rough draft of revised PCL documentation

git-svn-id: http://svn.ghostscript.com/ghostpcl/trunk/ghostpcl@2070 06663e23-700e-0410-b217-a244a6096597

5 files changed, 822 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 000000000..792069616
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,18 @@
+DOCS=ghostpcl.dvi ghostpcl.pdf ghostpcl.txt
+
+# latex 2 dvi
+%.dvi : %.tex
+	latex $<
+
+# latex 2 pdf
+%.pdf : %.tex
+	pdflatex $<
+
+# pdf 2 text
+%.txt : %.pdf
+	pdftotext $<
+
+all: $(DOCS)
+
+clean:
+	rm -f $(DOCS)
diff --git a/doc/ghostpcl.dvi b/doc/ghostpcl.dvi
new file mode 100644
index 000000000..275cce0e0
--- /dev/null
+++ b/doc/ghostpcl.dvi
diff --git a/doc/ghostpcl.pdf b/doc/ghostpcl.pdf
new file mode 100644
index 000000000..394196588
--- /dev/null
+++ b/doc/ghostpcl.pdf
diff --git a/doc/ghostpcl.tex b/doc/ghostpcl.tex
new file mode 100644
index 000000000..48ae97dac
--- /dev/null
+++ b/doc/ghostpcl.tex
@@ -0,0 +1,416 @@
+\documentclass[10pt]{article}
+\usepackage{fullpage, graphicx, url, textcomp, hyperref, qtree}
+\setlength{\parskip}{1ex}
+\setlength{\parindent}{0ex}
+\title{GhostPCL5e, GhostPCL5c, and GhostPXL}
+\begin{document}
+\section*{GhostPCL}
+This page discusses configuration, compilation and running of the 
+GhostPCL family of products:  \emph{PCL5E}, \emph{PCL5C},
+\emph{PCLXL}, and \emph{HPGL/2} with \emph{RTL}, additionally a scaled
+down \emph{PJL} (Printer Job Language) interpreter is provided.  All
+of the PCL products use the Ghostscript Graphic Library for graphics,
+imaging and driver support.  A brief tour of the Ghostscript
+documentation \url{www.ghostscript.com/doc/} will be helpful to
+understand this document.  The relevant ghostscript version used by
+PCL can be found in gs/src/version.mak.  The following is a short
+overview of GhostPCL, immediately followed by a ``hands on''
+discussion of how to build and run the software.
+
+GhostPCL is PCL technology; it is not intended to be a finished
+software application but a collection of software components that will
+ultimately be included in a software application or a real time
+embedded system.  Generally the GhostPCL languages are compliant with
+the Genoa (now QualityLogic) Functional Test Suite and the Genoa
+Application Test suite.  Also each language should run the
+corresponding Genoa Comprehensive Evaluation Test (CET) without
+egregious errors.
+
+For printer customers we have GhostSwitch.  GhostSwitch integrates
+Ghostscript's Postscript and PDF interpreter with GhostPCL in a
+language switching environment with auto language sensing and PJL job
+control as found on many modern printers.
+
+In this document and the software, PCL6 refers to technology that
+supports both PCL5 and PCLXL languages.
+
+\subsection*{Quick Start For Unix environment with GCC.}
+\begin{tabbing}
+\= tar zxvf ghostpcl-xxx.tar.gz; cd ghostpcl-xxx   \= \# unpack the release and go to the release directory \footnotemark[1]\\
+\> make fonts                                      \> \# install the fonts. \footnotemark[2]\\
+\> make product                                    \> \# compile and link pcl6 \\.
+\> make test                                       \> \# test pcl6 (optional). \\
+\> make install                                    \> \# install it \\
+\end{tabbing}
+\footnotetext[1]{If tar ``z''' option is not supported: gunzip ghostpcl-xxx.tar.gz; tar xvf ghostpcl-xxx.tar.}
+\footnotetext[2]{See  Fonts  to configure this differently.}
+\subsection*{Supported development environments}
+\begin{itemize}
+\item Windows NT and '95 with Microsoft Visual C/C++
+\item Linux with gcc
+\item Unix environments without GCC
+\end{itemize}
+
+\subsection*{Unpacking the source}
+
+The source code will either be on CD-ROM (without any archiving or
+compression) or in a archived compressed format.  Zip is used for
+Windows environments and compressed tar format for Unix environments. 
+If you have a CD-ROM release you will want to replicate the directory
+structure from the CD-ROM to a development directory on a hard drive. 
+The compile process does not require a special directory name.  If you
+have obtained the archived compressed version use:
+
+ For Windows:
+
+ pkunzip -d $<$archive\_name$>$\\
+
+ For Unix:: 
+
+ gunzip $<$archive\_name.gz$>$\\ 
+ tar xvf $<$archive\_name$>$ 
+ 
+ After unpacking the result should be a directory hierarchy which is
+ briefly described next.
+
+\subsection*{Brief Overview of Directory Hierarchy}
+\begin{description}
+  
+\item[pcl] Source code for the PCL interpreter.  Files beginning with
+  ``pc'' handle pcl state, text and rules.  ``rt'' files implement pcl's
+  raster language RTL and the ``pg'' source code files are for HPGL/2.
+  
+\item[pxl] Source code for the PCL-XL interpreter.  This is an
+  entirely different language than PCL; all files in this subdirectory
+  are prefixed with ``px''
+  
+\item[pl] This subdirectory contains code that can be shared by PCL
+  and PXL\@.  In particular font scaling code, the printer job language
+  (PJL) and the language switching machinery are in this subdirectory.
+  All files in this directory are prefixed with pl.
+  
+\item[common] PCL and PXL shared makefiles.  The subdirectory is an
+  historical artifact from when PCL and PXL had separate makefiles.
+  The files could be shared by both makefile.  It does contain the
+  makefile to build the ghostscript graphics library.
+
+
+\item[tools] miscellaneous tools and test files.
+  
+\item[tools/GOT] GOT means graphical object tagging.  The system is
+  able to classify high level graphical objects (text, images and
+  vectors) and store this information in the framebuffer along with
+  the output data.  The tools in these directories are used to unpack
+  a framebuffer that has been tagged for display in a viewable format.
+  
+\item[tools/viewer] The Java pcl viewer is a sample graphical user
+  interface for the GhostPCL system.
+  
+\item[language\_switch] top level makefiles for building a share
+  language environment.  This is where the shared language environment
+  which includes \emph{PostScript} and PDF can be built.
+  
+\item[gs] Ghostscript branch, refer to the documentation at
+  \url{www.ghostscript.com/doc/} for more information about
+  ghostscript.
+  
+\item[main] The ``workhorse'' makefiles of the system.  These are also
+  most likely to need modification to add/remove devices, choose a
+  font scaler, and set directory locations.
+
+\item[urwfonts] 80 URW TrueType fonts.
+
+\end{description}
+
+This directory structure is the default, but the directories can be
+rearranged with minor modifications to the makefiles.
+
+\subsection*{Building with Microsoft Visual C/C++}
+The PCL tools are known to build with Visual C/C++ 4.0, 5.0 and 6.0. 
+There are 2 ways of building the PCL components with Microsoft Visual
+C/C++:  Convert the current makefile environment to a Visual C/C++
+project ; or compile the source directly using nmake.  The following
+steps take you through converting the supplied makefile environment to
+a Visual C++ project:
+
+\begin{itemize}
+\item  Unpack the source code, see Unpacking the source.
+
+\item  Start MSVC++.
+  
+\item Open main/pcl6\_msvc.mak and MSVC++ should wrap the makefile
+  automatically and create an MSVC project.
+  
+\item Set the project setting (Alt F7).  Cryptically a setting to
+  create a debug build can be set up as follows:
+
+\textbf{NMAKE /f pcl6\_msvc.mak DEBUG=1 DEVSTUDIO=c:$\backslash$progra~1$\backslash$micros~3}\footnote{DEBUG=1/0 on/off will require you manually clean;  del main$\backslash$obj$\backslash$*.*}
+
+Now set the name of the executable for debuggging,
+$.$$\backslash$obj$\backslash$pcl6.exe, and set the program argument to
+be any pcl6 options wanted and the name of the pcl file.
+\item Now PCL6 is set to be compiled, debugged and use other features
+  of the MSVC++ IDE.\footnote{Dos hackers can start up a dos window,
+    set the DEVSTUDIO environment variable, and use the same make
+    commands as above (the DEVSTUDIO variable should be set to the top
+    level of the Microsoft Developer Studio, e\.g\. set
+    DEVSTUDIO=c:$\backslash$progra~1$\backslash$devstu~1'' or NMAKE /f
+    pcl6\_msvc.mak DEBUG=1
+    DEVSTUDIO=c:$\backslash$progra~1$\backslash$micros~3)}
+
+\end{itemize}
+
+This will build both the PCL and XL language and supporting language
+switching code.
+
+\subsection*{Building with Linux and GCC}
+
+The pcl tools have been compiled on Linux using GCC.  It is easiest to
+simply use the instructions provided in the section Quick Start For
+Unix environment with GCC.
+
+\subsection*{Building on a generic UNIX platform}
+
+The PCL tools have been compiled on Solaris with the Sun Development
+Tools and SGI with the native SGI C compiler.  We only provide
+makefiles for the gcc tools and assume users can customize the gcc
+makefiles such that they work with vendor's compilers.  For the Sun
+Development tools the following workaround is sufficient to build the
+software:
+
+\begin{itemize}
+\item change to the main subdirectory.
+\item make CC\_=cc CCLD=cc $\backslash$ CCAUX=cc CFLAGS=-g CC\_NO\_WARN=cc GCFLAGS= 
+\end{itemize}
+
+If you intend to do development using the software a dedicated
+makefile should be constructed.
+
+\subsection*{Customizing the build process}
+
+The build process is completely configurable.  Here is a list of
+things that are user will most like be interested in customizing.  To
+change any of these see the appropriate makefile for your platform in
+the ``main'' subdirectory
+
+\begin{itemize}
+\item  Directory location of source directories.
+\item  Directory location of objects, executables, and other compile time generated files.
+\item  Selection of devices.
+\item  Directory location of PJL  filesystem volume 0 and 1
+\item  The font scaling technology.
+\begin{itemize}
+\item  Defaults to /tmp/pjl0 and /tmp/pjl1
+\item  Edit pl/pl.mak  PJL\_VOLUME\_0 and PJL\_VOLUME\_1 to match desired root
+\end{itemize}
+
+\end{itemize}
+
+All of these can be configured in the top level makefile or can be
+specified on the make command line.
+
+The following make targets are available: 
+\begin{description}
+\item[debug] build tools with symbols and debugging information
+\item[product] builds optimized code.
+\item[pg-fp] builds profiling code for hardware with floating point.
+\item[pg-nofp] builds profiling code for hardware with no floating point (i\.e\. with floating point emulation software).
+\end{description}
+
+\subsection*{Building only one Language}
+PCL or PCL-XL can be built together in a language switching
+environment or each can be built alone with the supporting PJL
+interpreter.  The simplest way to implement one language is simply to
+remove the unwanted implementation from the pdl implementation table
+located in pl/plimpl.c:
+
+
+For example, this is the default table with two implementations: PCL and XL. 
+
+\begin{tabbing}
+\hspace{.5in}\=\hspace{.5in}\=\\
+\> /* Zero-terminated list of pointers to implementations */\\
+\> pl\_interp\_implementation\_t const * const pdl\_implementation[] = \{ \\ 
+\> \> \&pcl\_implementation, \\ 
+\> \> \&pxl\_implementation, \\ 
+\> \> 0 \\ 
+\> \};
+\end{tabbing}
+
+If you only wish to use one interpreter remove the unwanted one and
+recompile the code.
+
+\subsection*{Running the products.}
+\begin{quote}
+Few things are harder to put up with than a good example.
+\emph{Mark Twain}
+\end{quote}
+
+
+All options supplied to the interpreter in the following examples are
+described in the  Ghostscript documentation
+\url{www.ghostscript.com/doc/}
+
+
+\textbf{pcl6 mypcl.pcl}
+
+
+ 
+ Interpret a pcl file called mypcl.pcl and render it to the default
+ device.  For now the default device on systems with x11 is a full
+ color x11 display, other system default to laserjet 4 output suitable
+ for a monochrome laser printer.
+
+
+\textbf{pcl6 -dTextAlphaBits=4 mypcltext.pcl}
+
+When rendering pcl text at low (screen) resolution display device use
+the TextAlphaBits option to enable anti-aliasing.  GhostPCL does not
+support hinting of TrueType fonts because of patent issues.
+
+
+\textbf{pcl6 -sDEVICE=x11 mypcl.pcl}
+
+Interpret a pcl file called mypcl.pcl and render to the x11 device.
+
+\textbf{pcl6 -sDEVICE=ljet4 -sOutputFile=''$|$ lpr'' -dNOPAUSE mypcl.pcl}
+
+Interpret mypcl.pcl and send the Laserjet 4 formatted output to the
+command lpr, lpr should then send it to a real printer.  Note this is
+for unix systems.
+
+
+\textbf{pcl6 -sDEVICE=pcxcmyk -sOutputFile=''pcxpage.\%d'' -dNOPAUSE mypcl.pcl}
+
+
+
+Interpret mypcl.pcl and generate CMYK output. Pages are to be put in
+files named pcxpage.1, pcxpage.2, pcxpage.3, etc.
+
+
+\textbf{pcl6 -r72 -sDEVICE=x11mono mypcl.pcl -r100 -sDEVICE=x11 mypcl.pcl}
+
+
+
+Render a pcl file at 72dpi on the monochrome X11 device, then render
+the same file at 100 dpi  on color X11 device.  This demonstrates
+on-the-fly device switching.
+
+
+\textbf{pcl6 -sDEVICE=bmpamono -sOutputFile=foo.bmp mypcl.pcl}
+
+
+
+The bmpamono (1 bit)  and bmpa16m (full color) run asynchronously.  In
+short, the language and graphics library produce bands in one thread
+while the device renders the bands in a second thread.
+
+
+\textbf{pcl6 -sDEVICE=pdfwrite -sOutputFile=mypcl.pdf mypcl.pcl}
+
+Convert the pcl file mypcl.pcl to PDF with output written to
+mypcl.pdf.
+
+\textbf{pcl6}
+
+Simply running the interpreter should generate some useful information
+about the available options and devices.   
+
+\subsection*{PCL Personality}
+
+The PCL emulation comes in three flavors: PCL5E, PCL5C, and RTL.  The
+PCL5E personality thresholds colors to black and white irrespective of
+the color parameters of the output device.  PCL5C is the color
+personality, used with a monochrome device it will grayscale colors. 
+The RTL personality can be used to print HPGL/2 RTL plot files.
+
+\textbf{pcl6 -PRTL myrtl.rtl}
+
+run the interpreter with the rtl personality.
+
+
+\textbf{pcl6 -PPCL5E -sDEVICE=ljet4 mypcl.pcl}
+
+run the interpreter with the pcl5e personality.  This will threshold
+colors to black and white (ljet4 is a 1 bit device).
+
+
+\textbf{pcl6 -PPCL5C -sDEVICE=ljet4 mypcl.pcl}
+
+run the interpreter with the pcl5c personality.  This will grayscale
+colors on the 1 bit output device.  If not set on the command line the
+pcl interpreter personality will be set to PCL5E if the output device
+is 1 bit per pixel otherwise it is set to PCL5C.  RTL must be
+explicitly set on the command line.  RTL always grayscales and never
+thresholds colors to black and white.
+
+
+\subsection*{Fonts}
+
+The release is packaged with 80 high quality URW TrueType fonts.  For
+commercial use of the GhostPCL technology these fonts can be licensed
+from Artifex.  The fonts are searched for in either the fonts,
+/windows/fonts, or a directory specified with the PCLFONTSOURCE
+environment variable.
+
+Fonts and a font scaler from a third-party vendor such as  Agfa  or 
+Bitstream  may also be used.  There is an existing interface for
+integrating the AGFA Universal Font Scaler Technology, several Artifex
+customers currently use this solution.  The software can use Hewlett
+Packard FONTSMART version 1.5 or Windows TrueType fonts, using either
+of these font solutions require minor PCL code modifications.
+
+
+\subsection*{PCL Code changes required to use other TrueType fonts.}
+
+
+To use a new set of TrueType fonts requires modifying the C code in
+the file pl/plftable.c.  The C structure resident\_table contains a
+list of Windows TrueType font names.  In the released package these
+names will correspond with the Windows True Type font names in the URW
+font set.  To use a different font set these names must be replaced
+with the new font names and the code (at least the plftable.c module)
+should be recompiled and linked.  The file tools/fontpage.pcl can be
+run to display font samples and the pcl escape sequences required to
+select the fonts in a pcl stream.
+
+\subsection*{Using the language switching build}
+
+For printer and embedded device users we provide a complete language
+switching solution consisting of PCL/HPGL2, PCLXL, PS, PDF, with Job
+Control.  For host based user we strongly recommend that you use
+GhostPCL and Ghostscript separately as the shared language has
+particular feature well suited to printer environment but the same
+feature may produce unexpected results on host based environments.
+
+\subsection*{Building the Language Switch Environment}
+
+At this time, we have makefile support for Microsoft Visual C and
+Linux with gcc.  For the Microsoft Visual C the use the instructions
+in the section Building with Microsoft Visual C, but this time you
+will wrap the makefile pspcl6\_gcc.mak which is located in the
+directory language\_switch.  For Linux the makefile targets for the
+language switch build are exactly the same except each target is
+prefixed with ``ls''.  So using the pattern from the ``Quick Start''
+section we have:
+
+\subsection*{Quick Start For Unix environment with GCC.}
+\begin{tabbing}
+\= tar zxvf ghostpcl-xxx.tar.gz; cd ghostpcl-xxx   \= \# unpack the release and go to the release directory.\\
+\> make ls\_fonts                                  \> \# install the fonts.\\
+\> make ls\_product                                \> \# compile and link pspcl6.\\
+\> make ls\_test                                   \> \# test pspcl6 (optional).\\
+\> make ls\_install                                \> \# install it.\\
+\end{tabbing}
+
+\subsection*{Reporting bugs}
+
+If you find a bug or have comments about this documentation, please
+send  mail to bug-pcl@ghostscript.com.
+
+\subsection*{Trademark Credits}
+
+\emph{PostScript} is a registered trademark of Adobe Systems Inc.
+\emph{PCL} is a registered trademark of Hewlett-Packard Company.
+
+\end{document}
diff --git a/doc/ghostpcl.txt b/doc/ghostpcl.txt
new file mode 100644
index 000000000..0c013e1da
--- /dev/null
+++ b/doc/ghostpcl.txt
@@ -0,0 +1,388 @@
+GhostPCL
+
+This page discusses configuration, compilation and running of the GhostPCL family of products: PCL5E,
+PCL5C, PCLXL, and HPGL/2 with RTL, additionally a scaled down PJL (Printer Job Language) interpreter
+is provided. All of the PCL products use the Ghostscript Graphic Library for graphics, imaging and driver
+support. A brief tour of the Ghostscript documentation www.ghostscript.com/doc/ will be helpful to
+understand this document. The relevant ghostscript version used by PCL can be found in gs/src/version.mak.
+The following is a short overview of GhostPCL, immediately followed by a "hands on" discussion of how to
+build and run the software.
+
+GhostPCL is PCL technology; it is not intended to be a finished software application but a collection of
+software components that will ultimately be included in a software application or a real time embedded
+system. Generally the GhostPCL languages are compliant with the Genoa (now QualityLogic) Functional
+Test Suite and the Genoa Application Test suite. Also each language should run the corresponding Genoa
+Comprehensive Evaluation Test (CET) without egregious errors.
+
+For printer customers we have GhostSwitch. GhostSwitch integrates Ghostscript's Postscript and PDF
+interpreter with GhostPCL in a language switching environment with auto language sensing and PJL job
+control as found on many modern printers.
+
+In this document and the software, PCL6 refers to technology that supports both PCL5 and PCLXL lan-
+guages.
+
+
+Quick Start For Unix environment with GCC.
+
+tar zxvf ghostpcl-xxx.tar.gz; cd ghostpcl-xxx # unpack the release and go to the release directory 1
+make fonts                                           # install the fonts. 2
+make product                                         # compile and link pcl6
+.make test                                           # test pcl6 (optional).
+make install                                         # install it
+
+
+
+
+
+Supported development environments
+
+    Windows NT and '95 with Microsoft Visual C/C++
+
+    Linux with gcc
+
+    Unix environments without GCC
+
+
+Unpacking the source
+
+The source code will either be on CD-ROM (without any archiving or compression) or in a archived com-
+pressed format. Zip is used for Windows environments and compressed tar format for Unix environments.
+If you have a CD-ROM release you will want to replicate the directory structure from the CD-ROM to a
+development directory on a hard drive. The compile process does not require a special directory name. If
+you have obtained the archived compressed version use:
+
+For Windows:
+
+pkunzip -d <archive name>
+
+
+  1If tar "z"' option is not supported: gunzip ghostpcl-xxx.tar.gz; tar xvf ghostpcl-xxx.tar.
+  2See Fonts to configure this differently.
+
+
+
+
+                                                              1
+
+
+For Unix::
+
+gunzip <archive name.gz>
+tar xvf <archive name>
+
+After unpacking the result should be a directory hierarchy which is briefly described next.
+
+
+Brief Overview of Directory Hierarchy
+
+pcl Source code for the PCL interpreter. Files beginning with "pc" handle pcl state, text and rules. "rt"
+     files implement pcl's raster language RTL and the "pg" source code files are for HPGL/2.
+
+pxl Source code for the PCL-XL interpreter. This is an entirely different language than PCL; all files in
+     this subdirectory are prefixed with "px"
+
+pl This subdirectory contains code that can be shared by PCL and PXL. In particular font scaling code,
+     the printer job language (PJL) and the language switching machinery are in this subdirectory. All files
+     in this directory are prefixed with pl.
+
+common PCL and PXL shared makefiles. The subdirectory is an historical artifact from when PCL and
+     PXL had separate makefiles. The files could be shared by both makefile. It does contain the makefile
+     to build the ghostscript graphics library.
+
+tools miscellaneous tools and test files.
+
+tools/GOT GOT means graphical object tagging. The system is able to classify high level graphical objects
+     (text, images and vectors) and store this information in the framebuffer along with the output data.
+     The tools in these directories are used to unpack a framebuffer that has been tagged for display in a
+     viewable format.
+
+tools/viewer The Java pcl viewer is a sample graphical user interface for the GhostPCL system.
+
+language switch top level makefiles for building a share language environment. This is where the shared
+     language environment which includes PostScript and PDF can be built.
+
+gs Ghostscript branch, refer to the documentation at www.ghostscript.com/doc/ for more information
+     about ghostscript.
+
+main The "workhorse" makefiles of the system. These are also most likely to need modification to add/remove
+     devices, choose a font scaler, and set directory locations.
+
+urwfonts 80 URW TrueType fonts.
+
+
+This directory structure is the default, but the directories can be rearranged with minor modifications to
+the makefiles.
+
+
+Building with Microsoft Visual C/C++
+
+The PCL tools are known to build with Visual C/C++ 4.0, 5.0 and 6.0. There are 2 ways of building the PCL
+components with Microsoft Visual C/C++: Convert the current makefile environment to a Visual C/C++
+project ; or compile the source directly using nmake. The following steps take you through converting the
+supplied makefile environment to a Visual C++ project:
+
+
+    Unpack the source code, see Unpacking the source.
+
+    Start MSVC++.
+
+
+
+                                                      2
+
+
+    Open main/pcl6 msvc.mak and MSVC++ should wrap the makefile automatically and create an MSVC
+      project.
+
+    Set the project setting (Alt F7). Cryptically a setting to create a debug build can be set up as follows:
+      NMAKE /f pcl6 msvc.mak DEBUG=1 DEVSTUDIO=c:\progra 1\micros 31
+
+      Now set the name of the executable for debuggging, .\obj\pcl6.exe, and set the program argument to
+      be any pcl6 options wanted and the name of the pcl file.
+
+    Now PCL6 is set to be compiled, debugged and use other features of the MSVC++ IDE.2
+
+This will build both the PCL and XL language and supporting language switching code.
+
+
+Building with Linux and GCC
+
+The pcl tools have been compiled on Linux using GCC. It is easiest to simply use the instructions provided
+in the section Quick Start For Unix environment with GCC.
+
+
+Building on a generic UNIX platform
+
+The PCL tools have been compiled on Solaris with the Sun Development Tools and SGI with the native SGI
+C compiler. We only provide makefiles for the gcc tools and assume users can customize the gcc makefiles
+such that they work with vendor's compilers. For the Sun Development tools the following workaround is
+sufficient to build the software:
+
+
+    change to the main subdirectory.
+
+    make CC =cc CCLD=cc \ CCAUX=cc CFLAGS=-g CC NO WARN=cc GCFLAGS=
+
+If you intend to do development using the software a dedicated makefile should be constructed.
+
+
+Customizing the build process
+
+The build process is completely configurable. Here is a list of things that are user will most like be interested
+in customizing.    To change any of these see the appropriate makefile for your platform in the "main"
+subdirectory
+
+
+    Directory location of source directories.
+
+    Directory location of objects, executables, and other compile time generated files.
+
+    Selection of devices.
+
+    Directory location of PJL filesystem volume 0 and 1
+
+    The font scaling technology.
+
+        ­ Defaults to /tmp/pjl0 and /tmp/pjl1
+
+        ­ Edit pl/pl.mak PJL VOLUME 0 and PJL VOLUME 1 to match desired root
+
+  1DEBUG=1/0 on/off will require you manually clean; del main\obj\*.*
+  2Dos hackers can start up a dos window, set the DEVSTUDIO environment variable, and use the same make com-
+mands as above (the DEVSTUDIO variable should be set to the top level of the Microsoft Developer Studio, e gset
+DEVSTUDIO=c:\progra 1\devstu 1" or NMAKE /f pcl6 msvc.mak DEBUG=1 DEVSTUDIO=c:\progra 1\micros 3)
+
+
+
+
+
+                                                        3
+
+
+All of these can be configured in the top level makefile or can be specified on the make command line.
+
+The following make targets are available:
+
+
+debug build tools with symbols and debugging information
+
+product builds optimized code.
+
+pg-fp builds profiling code for hardware with floating point.
+
+pg-nofp builds profiling code for hardware with no floating point (ie 
+                                                                         with floating point emulation software).
+
+
+Building only one Language
+
+PCL or PCL-XL can be built together in a language switching environment or each can be built alone
+with the supporting PJL interpreter. The simplest way to implement one language is simply to remove the
+unwanted implementation from the pdl implementation table located in pl/plimpl.c:
+
+For example, this is the default table with two implementations: PCL and XL.
+
+
+
+            /* Zero-terminated list of pointers to implementations */
+            pl interp implementation t const * const pdl implementation[] = {
+                    &pcl implementation,
+                    &pxl implementation,
+                    0
+            };
+
+
+If you only wish to use one interpreter remove the unwanted one and recompile the code.
+
+
+Running the products.
+
+      Few things are harder to put up with than a good example. Mark Twain
+
+
+All options supplied to the interpreter in the following examples are described in the Ghostscript documen-
+tation www.ghostscript.com/doc/
+
+pcl6 mypcl.pcl
+
+Interpret a pcl file called mypcl.pcl and render it to the default device. For now the default device on systems
+with x11 is a full color x11 display, other system default to laserjet 4 output suitable for a monochrome laser
+printer.
+
+pcl6 -dTextAlphaBits=4 mypcltext.pcl
+
+When rendering pcl text at low (screen) resolution display device use the TextAlphaBits option to enable
+anti-aliasing. GhostPCL does not support hinting of TrueType fonts because of patent issues.
+
+pcl6 -sDEVICE=x11 mypcl.pcl
+
+Interpret a pcl file called mypcl.pcl and render to the x11 device.
+
+pcl6 -sDEVICE=ljet4 -sOutputFile="| lpr" -dNOPAUSE mypcl.pcl
+
+Interpret mypcl.pcl and send the Laserjet 4 formatted output to the command lpr, lpr should then send it
+to a real printer. Note this is for unix systems.
+
+pcl6 -sDEVICE=pcxcmyk -sOutputFile="pcxpage.%d" -dNOPAUSE mypcl.pcl
+
+Interpret mypcl.pcl and generate CMYK output. Pages are to be put in files named pcxpage.1, pcxpage.2,
+pcxpage.3, etc.
+
+
+                                                        4
+
+
+pcl6 -r72 -sDEVICE=x11mono mypcl.pcl -r100 -sDEVICE=x11 mypcl.pcl
+
+Render a pcl file at 72dpi on the monochrome X11 device, then render the same file at 100 dpi on color X11
+device. This demonstrates on-the-fly device switching.
+
+pcl6 -sDEVICE=bmpamono -sOutputFile=foo.bmp mypcl.pcl
+
+The bmpamono (1 bit) and bmpa16m (full color) run asynchronously. In short, the language and graphics
+library produce bands in one thread while the device renders the bands in a second thread.
+
+pcl6 -sDEVICE=pdfwrite -sOutputFile=mypcl.pdf mypcl.pcl
+
+Convert the pcl file mypcl.pcl to PDF with output written to mypcl.pdf.
+
+pcl6
+
+Simply running the interpreter should generate some useful information about the available options and
+devices.
+
+
+PCL Personality
+
+The PCL emulation comes in three flavors: PCL5E, PCL5C, and RTL. The PCL5E personality thresholds
+colors to black and white irrespective of the color parameters of the output device. PCL5C is the color
+personality, used with a monochrome device it will grayscale colors. The RTL personality can be used to
+print HPGL/2 RTL plot files.
+
+pcl6 -PRTL myrtl.rtl
+
+run the interpreter with the rtl personality.
+
+pcl6 -PPCL5E -sDEVICE=ljet4 mypcl.pcl
+
+run the interpreter with the pcl5e personality. This will threshold colors to black and white (ljet4 is a 1 bit
+device).
+
+pcl6 -PPCL5C -sDEVICE=ljet4 mypcl.pcl
+
+run the interpreter with the pcl5c personality. This will grayscale colors on the 1 bit output device. If not
+set on the command line the pcl interpreter personality will be set to PCL5E if the output device is 1 bit per
+pixel otherwise it is set to PCL5C. RTL must be explicitly set on the command line. RTL always grayscales
+and never thresholds colors to black and white.
+
+
+Fonts
+
+The release is packaged with 80 high quality URW TrueType fonts. For commercial use of the GhostPCL
+technology these fonts can be licensed from Artifex. The fonts are searched for in either the fonts, /win-
+dows/fonts, or a directory specified with the PCLFONTSOURCE environment variable.
+
+Fonts and a font scaler from a third-party vendor such as Agfa or Bitstream may also be used. There is
+an existing interface for integrating the AGFA Universal Font Scaler Technology, several Artifex customers
+currently use this solution. The software can use Hewlett Packard FONTSMART version 1.5 or Windows
+TrueType fonts, using either of these font solutions require minor PCL code modifications.
+
+
+PCL Code changes required to use other TrueType fonts.
+
+To use a new set of TrueType fonts requires modifying the C code in the file pl/plftable.c. The C structure
+resident table contains a list of Windows TrueType font names. In the released package these names will
+correspond with the Windows True Type font names in the URW font set. To use a different font set these
+names must be replaced with the new font names and the code (at least the plftable.c module) should be
+recompiled and linked. The file tools/fontpage.pcl can be run to display font samples and the pcl escape
+sequences required to select the fonts in a pcl stream.
+
+
+                                                      5
+
+
+Using the language switching build
+
+For printer and embedded device users we provide a complete language switching solution consisting of
+PCL/HPGL2, PCLXL, PS, PDF, with Job Control. For host based user we strongly recommend that you
+use GhostPCL and Ghostscript separately as the shared language has particular feature well suited to printer
+environment but the same feature may produce unexpected results on host based environments.
+
+
+Building the Language Switch Environment
+
+At this time, we have makefile support for Microsoft Visual C and Linux with gcc. For the Microsoft Visual
+C the use the instructions in the section Building with Microsoft Visual C, but this time you will wrap the
+makefile pspcl6 gcc.mak which is located in the directory language switch. For Linux the makefile targets
+for the language switch build are exactly the same except each target is prefixed with "ls". So using the
+pattern from the "Quick Start" section we have:
+
+
+Quick Start For Unix environment with GCC.
+
+tar zxvf ghostpcl-xxx.tar.gz; cd ghostpcl-xxx # unpack the release and go to the release directory.
+make ls fonts                                # install the fonts.
+make ls product                              # compile and link pspcl6.
+make ls test                                 # test pspcl6 (optional).
+make ls install                              # install it.
+
+
+
+
+Reporting bugs
+
+If you find a bug or have comments about this documentation, please send mail to bug-pcl@ghostscript.com.
+
+
+Trademark Credits
+
+PostScript is a registered trademark of Adobe Systems Inc. PCL is a registered trademark of Hewlett-Packard
+Company.
+
+
+
+
+
+                                                     6
+
+