TempNewImagePackage/src/documentation/content/xdocs/postscript.xml - xmlgraphics-commons - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
   <header>
     <title>Tools for Adobe PostScript</title>
   </header>
   <body>
     <section id="overview">
       <title>Overview</title>
       <p>
         Apache XML Graphics Commons contains various tools for writing and processing Adobe
         PostScript files. This includes:
       </p>
       <ul>
         <li>A PostScript generator class which helps writing PostScript files from scratch.</li>
         <li>Two Graphics2D implementations, one for plain PostScript and one for writing
           Encapsulated PostScript (EPS).</li>
         <li>A DSC-parser/processor: Parse, post-process and change DSC-compliant PostScript files.</li>
       </ul>
       <note>
         We don't currently include a PostScript interpreter though we would love to have one. A
         Java-based PostScript interpreter to keep an eye on is the one from the
         <a href="http://foray.sourceforge.net">FOray project</a>.
       </note>
     </section>
     <section id="generator">
       <title>The PostScript generator</title>
       <p>
         The "PSGenerator" class can help writing PostScript files. It deals with things like
         escaping, saving/tracking/restoring graphics state, writing DSC comments and tracking of
         DSC resources.
       </p>
       <p>
         You will rarely interact with the PS generator itself, as it is probably more interesting
         to generate a PostScript file using Java2D which is described in the following section.
       </p>
     </section>
     <section id="java2d">
       <title>Java2D: Graphics2D implementation for generating PostScript and EPS</title>
       <p>
         We provide two classes (PSDocumentGraphics2D and EPSDocumentGraphics2D) which you can use
         to generated complete PostScript files using normal Java2D means. The difference between
         the two classes is that the EPS variant creates a fully compliant Encapsulated
         PostScript file while the PS variant simply creates a normal DSC-compliant level 2
         PostScript file. It depends on your requirement which variant you choose. The PS variant
         is mostly for printing purposes while the EPS variant is better suited for inclusion in
         other documents.
       </p>
       <section id="creating-eps">
         <title>Creating an EPS file</title>
         <p>
           Creating an EPS file using the Graphics2D implementation is easy. Instantiate
           EPSDocumentGraphics2D, set a GraphicContext and set up the output document. Here's an
           example:
         </p>
         <source><![CDATA[
 import org.apache.xmlgraphics.java2d.ps.EPSDocumentGraphics2D;

 [..]

 EPSDocumentGraphics2D g2d = new EPSDocumentGraphics2D(false);
 g2d.setGraphicContext(new org.apache.xmlgraphics.java2d.GraphicContext());

 //Set up the document size
 g2d.setupDocument(out, 400, 200); //400pt x 200pt
 //out is the OutputStream to write the EPS to

 g2d.drawRect(10, 10, 50, 50); //paint a rectangle using normal Java2D calls

 g2d.finish(); //Wrap up and finalize the EPS file
         ]]></source>
         <p>
           A complete example for generating an EPS files can be found in the
           <a href="http://svn.apache.org/viewvc/xmlgraphics/commons/trunk/examples/java/java2d/ps/">"examples" directory</a>
           in the distribution.
         </p>
       </section>
     </section>
     <section id="dsc">
       <title>DSC parser/processor</title>
       <p>
         Many PostScript files use special comments to structure a document. This allows manipulation
         of PostScript files without interpreting them. These special comments are defined in the
         <a href="http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf">Document Structuring Conventions</a>.
         The code in Commons is designed to work with DSC 3.0. For details on how DSC is used,
         please take a look at the DSC specification.
       </p>
       <p>
         The DSC support in Commons was primarily developed to implement resource optimization
         features in <a href="ext:fop">Apache FOP</a>'s PostScript output support. Resources like
         images which are used repeatedly in a document should not be written to the PostScript
         file each time it is used. Instead it is written once at the beginning of the file as a
         PostScript form. The form is then called whenever the image needs painting.
       </p>
       <p>
         But the DSC parser could potentially be used for other purposes. The most obvious is
         extracting a subset of pages from a DSC-compliant file. Assume you want to print only
         page 45 to 57 of a particular document. There's an example that demonstrates exactly this.
         Check out the "examples" directory in the distribution. Other potential use cases for the
         DSC parser are:
       </p>
       <ul>
         <li>Patching PostScript files, for example, adding OMR marks for automatic packaging</li>
         <li><a href="http://en.wikipedia.org/wiki/Imposition">Imposition</a> (2-up, n-up, rotation, etc.)</li>
         <li>EPS graphic extraction</li>
         <li>Inspecting the page count</li>
         <li>etc. etc.</li>
       </ul>
       <p>
         The DSC parser (DSCParser) was designed as a pull parser, i.e. you fetch new events from
         the parser inspecting them and acting on them as they are found. If you prefer to work
         with a push parser, you can pass the DSCParser a DSCHandler implementation and the parser
         will send you all the events.
       </p>
       <p>
         The best example to understand how to use the DSC parser is the PageExtractor class
         that implements the page extraction functionality mentioned above.
       </p>
       <note>
         The DSC parser is not considered feature-complete. The basic infrastructure is there but,
         for example, not all DSC comments are available as concrete Java classes. If you need
         to extend the DSC parser for your own use cases, please send us your patches.
       </note>
     </section>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
	<document>
	<header>
	<title>Tools for Adobe PostScript</title>
	</header>
	<body>
	<section id="overview">
	<title>Overview</title>
	<p>
	Apache XML Graphics Commons contains various tools for writing and processing Adobe
	PostScript files. This includes:
	</p>
	<ul>
	<li>A PostScript generator class which helps writing PostScript files from scratch.</li>
	<li>Two Graphics2D implementations, one for plain PostScript and one for writing
	Encapsulated PostScript (EPS).</li>
	<li>A DSC-parser/processor: Parse, post-process and change DSC-compliant PostScript files.</li>
	</ul>
	<note>
	We don't currently include a PostScript interpreter though we would love to have one. A
	Java-based PostScript interpreter to keep an eye on is the one from the
	<a href="http://foray.sourceforge.net">FOray project</a>.
	</note>
	</section>
	<section id="generator">
	<title>The PostScript generator</title>
	<p>
	The "PSGenerator" class can help writing PostScript files. It deals with things like
	escaping, saving/tracking/restoring graphics state, writing DSC comments and tracking of
	DSC resources.
	</p>
	<p>
	You will rarely interact with the PS generator itself, as it is probably more interesting
	to generate a PostScript file using Java2D which is described in the following section.
	</p>
	</section>
	<section id="java2d">
	<title>Java2D: Graphics2D implementation for generating PostScript and EPS</title>
	<p>
	We provide two classes (PSDocumentGraphics2D and EPSDocumentGraphics2D) which you can use
	to generated complete PostScript files using normal Java2D means. The difference between
	the two classes is that the EPS variant creates a fully compliant Encapsulated
	PostScript file while the PS variant simply creates a normal DSC-compliant level 2
	PostScript file. It depends on your requirement which variant you choose. The PS variant
	is mostly for printing purposes while the EPS variant is better suited for inclusion in
	other documents.
	</p>
	<section id="creating-eps">
	<title>Creating an EPS file</title>
	<p>
	Creating an EPS file using the Graphics2D implementation is easy. Instantiate
	EPSDocumentGraphics2D, set a GraphicContext and set up the output document. Here's an
	example:
	</p>
	<source><![CDATA[
	import org.apache.xmlgraphics.java2d.ps.EPSDocumentGraphics2D;

	[..]

	EPSDocumentGraphics2D g2d = new EPSDocumentGraphics2D(false);
	g2d.setGraphicContext(new org.apache.xmlgraphics.java2d.GraphicContext());

	//Set up the document size
	g2d.setupDocument(out, 400, 200); //400pt x 200pt
	//out is the OutputStream to write the EPS to

	g2d.drawRect(10, 10, 50, 50); //paint a rectangle using normal Java2D calls

	g2d.finish(); //Wrap up and finalize the EPS file
	]]></source>
	<p>
	A complete example for generating an EPS files can be found in the
	<a href="http://svn.apache.org/viewvc/xmlgraphics/commons/trunk/examples/java/java2d/ps/">"examples" directory</a>
	in the distribution.
	</p>
	</section>
	</section>
	<section id="dsc">
	<title>DSC parser/processor</title>
	<p>
	Many PostScript files use special comments to structure a document. This allows manipulation
	of PostScript files without interpreting them. These special comments are defined in the
	<a href="http://partners.adobe.com/public/developer/en/ps/5001.DSC_Spec.pdf">Document Structuring Conventions</a>.
	The code in Commons is designed to work with DSC 3.0. For details on how DSC is used,
	please take a look at the DSC specification.
	</p>
	<p>
	The DSC support in Commons was primarily developed to implement resource optimization
	features in <a href="ext:fop">Apache FOP</a>'s PostScript output support. Resources like
	images which are used repeatedly in a document should not be written to the PostScript
	file each time it is used. Instead it is written once at the beginning of the file as a
	PostScript form. The form is then called whenever the image needs painting.
	</p>
	<p>
	But the DSC parser could potentially be used for other purposes. The most obvious is
	extracting a subset of pages from a DSC-compliant file. Assume you want to print only
	page 45 to 57 of a particular document. There's an example that demonstrates exactly this.
	Check out the "examples" directory in the distribution. Other potential use cases for the
	DSC parser are:
	</p>
	<ul>
	<li>Patching PostScript files, for example, adding OMR marks for automatic packaging</li>
	<li><a href="http://en.wikipedia.org/wiki/Imposition">Imposition</a> (2-up, n-up, rotation, etc.)</li>
	<li>EPS graphic extraction</li>
	<li>Inspecting the page count</li>
	<li>etc. etc.</li>
	</ul>
	<p>
	The DSC parser (DSCParser) was designed as a pull parser, i.e. you fetch new events from
	the parser inspecting them and acting on them as they are found. If you prefer to work
	with a push parser, you can pass the DSCParser a DSCHandler implementation and the parser
	will send you all the events.
	</p>
	<p>
	The best example to understand how to use the DSC parser is the PageExtractor class
	that implements the page extraction functionality mentioned above.
	</p>
	<note>
	The DSC parser is not considered feature-complete. The basic infrastructure is there but,
	for example, not all DSC comments are available as concrete Java classes. If you need
	to extend the DSC parser for your own use cases, please send us your patches.
	</note>
	</section>
	</body>
	</document>