slight improvements/updates to info

information shuffling git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194609 13f79535-47bb-0310-9956-ffa450edef68
author: Keiron Liddle <keiron@apache.org> 2001-12-17 10:19:34 +0000
committer: Keiron Liddle <keiron@apache.org> 2001-12-17 10:19:34 +0000
commit: 010d64304dd62265ebcd076fba92720daf2e0950 (patch)
tree: e984bae7141334cedafcbac7934f9e603a70ab99 /docs/xml-docs
parent: 2117e3c29113281c400889d61a2bd6926039a6c3 (diff)
download: xmlgraphics-fop-010d64304dd62265ebcd076fba92720daf2e0950.tar.gz
xmlgraphics-fop-010d64304dd62265ebcd076fba92720daf2e0950.zip
5 files changed, 130 insertions, 51 deletions
diff --git a/docs/xml-docs/fop/download.xml b/docs/xml-docs/fop/download.xml
index 13489c370..454c58532 100644
--- a/docs/xml-docs/fop/download.xml
+++ b/docs/xml-docs/fop/download.xml
@@ -2,9 +2,16 @@
 
 
 <!-- Download FOP -->
+<document>
+    <header>
+        <title>Download</title>
+        <subtitle>Downloading FOP</subtitle>
+        <authors>
+        </authors>
+    </header>
 
+    <body>
 <s1 title="Downloading FOP">
-  <s2 title="">
     <p>You can download the latest release version from the <jump 
        href="http://xml.apache.org/dist/fop/">distribution directory</jump>. </p>
     <p>The file contains also the documentation (including some example fo files) and the source.  </p>
@@ -18,6 +25,7 @@
        interested in embedding FOP in a Java application of your own, see 
        <jump href="embedding.html">Embedding FOP</jump>.
     </p>
-  </s2>
 </s1>
+    </body>
+</document>
 
diff --git a/docs/xml-docs/fop/fonts.xml b/docs/xml-docs/fop/fonts.xml
index 2e8832e65..0164e6520 100644
--- a/docs/xml-docs/fop/fonts.xml
+++ b/docs/xml-docs/fop/fonts.xml
@@ -9,6 +9,10 @@
 		<p>Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe
 		Type 1 fonts and Truetype fonts. No other font types (Type 3, etc.) are supported at this time.
 		</p>
+    <note><p>
+        The Font is simply embedded into the PDF file, it is not converted.
+        If it is a Windows font then it will only be displayed properly on Windows.
+    </p></note>
 	</s2>
 	<s2 title="Adding additional Type 1 fonts">
 		<p>As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP
@@ -23,12 +27,12 @@
 			<p>
 				<code>org.apache.fop.fonts.apps.PFMReader pfm-file xml-file</code>
 			</p>
-			<p>Note: The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and
+			<note><p>The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and
 			calculations which are only an approximation to the real values. FontBBox and Italic Angle can be found in
 			the human-readable part of the PFB file. The PFMReader tool does not yet interpret PFB files, so if you want
 			to be correct, you may have to adjust the values in the XML file manually. The constructed values however
 			appear to have no visible influence.
-			</p>
+			</p></note>
 		</s3>
 		<s3 title="Register the fonts within FOP">
 			<p>
diff --git a/docs/xml-docs/fop/involved.xml b/docs/xml-docs/fop/involved.xml
index 299e86540..6f52297f3 100644
--- a/docs/xml-docs/fop/involved.xml
+++ b/docs/xml-docs/fop/involved.xml
@@ -1,18 +1,44 @@
 <?xml version="1.0" standalone="no"?>
 
-
-
 <!-- getting involved -->
 
+<document>
+    <header>
+        <title>Getting Involved</title>
+        <subtitle>How to Get Involved in FOP</subtitle>
+        <authors>
+        </authors>
+    </header>
+
+    <body>
 <s1 title="Getting involved">
-<!--  <p>Our main website <jump href="http://xml.apache.org/overview.html">xml.apache.org</jump> 
-     has a detailed description how to get involved. </p> The following is just a brief outline 
-     containing the addresses concerning Fop.</p>-->
-  <s2 title="Read the Status file">
-  <p>The Status file contains the list of features people are working on at the moment. 
-     And an outline what steps are next.</p>
+  <p>
+There are many different levels where people can get involved. The
+development of FOP and the related plans and tasks are discussed on
+the dev mailing list. Users can help or get issues resolved by
+contributing information and examples to the developers.
+</p>
+
+  <s2 title="Get familiar with the Fop related standards">
+  <p>
+At the moment Fop is mainly a tool to render XSL:FO files to pdf.
+Therefore if you want to contribute to Fop you should become
+familiar with these standards. You can find links under
+<jump href="resources.html">Resources</jump>.
+</p>
+  </s2>
+  <s2 title="Fop's Design">
+    <p>
+The design for FOP is specified under the
+<jump href="design/index.html">Design</jump> section.
+    </p>
+    <p>
+This is where the information on how FOP is development and designed
+internally will be kept.
+    </p>
   </s2>
-  <s2 title="Subscribe to the fop discussion list">
+
+  <s2 title="Subscribe to the fop developers list">
   <p>You can subscribe to fop-dev@xml.apache.org by sending an email 
         to <jump href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</jump></p>
   <p>Sending bug reports and feature requests to the list is a welcome and important contribution to 
@@ -53,16 +79,7 @@
   </p>
   </s2>
 
-  <s2 title="Get familiar with the Fop related standards">
-  <p>At the moment Fop is mainly a tool to render XSL:FO files to pdf. Therefore if you want to contribute to Fop you should become
-     familiar with these standards. You can find their internet addresses on our <jump href="specs.html">website</jump>.</p>
-  </s2>
-  <s2 title="Fop's architecture">
-  <p>A bird's eye view on the way Fop operates can be found in the document <jump href="architecture.html">FOP Mechanics</jump></p>
-  <p>If you want to extend the functionality of FOP by adding new formatting objects, you should do the following: </p>
-  <p>1. FO Object: Write a class which contains the description of your formatting object and put it into the package fop.fo.flow, fop.fo.pagination (if it is a property it goes to fop.fo.properties. The classes in this package are generated via an xslt stylesheet located in codegen/properties.xml)</p>
-  <p>2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it is a property you need to add it to fop.fo.PropertyListBuilder)</p>
-  <p>3. Area: Either your need can be fulfilled within one of the existing classes in fop.layout, then just add the code to handle the new fo/property or you must write a new one.</p>
-  <p>4. Renderer: Choose the renderer you are interested in. If you worked on an existing layout class you must add code to handle the new features to the already existing area specific method in the renderer class. Otherwise you have to add a new method. </p>
-  </s2>
 </s1>
+    </body>
+</document>
+
diff --git a/docs/xml-docs/fop/output.xml b/docs/xml-docs/fop/output.xml
index 865c95644..b97f8dfb3 100644
--- a/docs/xml-docs/fop/output.xml
+++ b/docs/xml-docs/fop/output.xml
@@ -7,6 +7,8 @@
         <title>Output</title>
         <subtitle>Notes about Output Formats: Renderers</subtitle>
         <authors>
+            <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
+            <person name="Art Welch"/>
         </authors>
     </header>
 
@@ -34,7 +36,7 @@ output format and associated data and flow.
     </p>
     <p>
 Fonts and Layout - some formats (eg. PDF and AWT) rely on different
-font information. THe fonts for these outputs have different sizes
+font information. The fonts for these outputs have different sizes
 for the same point size. This means that the layout can be quite
 different for the same fo document.
     </p>
@@ -68,7 +70,50 @@ compatible.
 <s2 title="PCL">
     <p>
 This format is for the Hewlett-Packard PCL printers.
-    </p>
+It should produce output as close to identical as possible to the
+printed output of the PDFRenderer within the limitations of the
+renderer, and output device.
+    </p>
+    <p>
+The output created by the PCLRenderer is generic PCL 5 as documented
+in the "HP PCL 5 Printer Language Technical Reference Manual" (copyright 1990).
+This should allow any device fully supporting PCL 5 to be able to
+print the output generated by the PCLRenderer.
+    </p>
+    <s3 title="Limitations">
+      <ul>
+        <li>Text or graphics outside the left or top of the printable area are not rendered properly. In general things that should print to the left of the printable area are shifted to the right so that they start at the left edge of the printable area and an error message is generated.</li>
+        <li>The Helvetica and Times fonts are not well supported among PCL printers so Helvetica is mapped to Arial and Times is mapped to Times New. This is done in the PCLRenderer, no changes are required in the FO's. The metrics and appearance for Helvetica/Arial and Times/Times New are nearly identical, so this has not been a problem so far.</li>
+        <li>Only the original fonts built into FOP are supported.</li>
+        <li>For the non-symbol fonts, the ISO 8859/1 symbol set is used (PCL set "0N").</li>
+        <li>Multibyte characters are not supported.</li>
+        <li>SVG support is limited. Currently only lines, rectangles (may be rounded), circles, ellipses, text, simple paths, and images are supported. Colors are supported (dithered black and white) but not gradients.</li>
+        <li>Images print black and white only (not dithered). When the renderer prints a color image it uses a threshold value, colors above the threshold are printed as white and below are black. If you need to print a non-monochrome image you should dither it first.</li>
+        <li>Image scaling is accomplished by modifying the effective resolution of the image data. The available resolutions are 75, 100, 150, 300, and 600 DPI.</li>
+        <li>Color printing is not supported. Colors are rendered by mapping the color intensity to one of the PCL fill shades (from white to black in 9 steps).</li>
+        <li>SVG clipping is not supported.</li>
+      </ul>
+    </s3>
+
+    <s3 title="Additional Features">
+      <p>There are some special features that are controlled by some public variables on the PCLRenderer class.</p>
+
+      <dl>
+        <dt>orientation</dt>
+        <dd><p>The logical page orientation is controlled by the public orientation variable. Legal values are:</p>
+          <ul>
+            <li>0 Portrait</li>
+            <li>1 Landscape</li>
+            <li>2 Reverse Portrait</li>
+            <li>3 Reverse Landscape</li>
+          </ul>
+        </dd>
+        <dt>curdiv, paperheight</dt>
+        <dd>The curdiv and paperheight variables allow multiple virtual pages to be printed on a piece of paper. This allows a standard laser printer to use perforated paper where every perforation will represent an individual page. The paperheight sets the height of a piece of paper in decipoints. This will be divided by the page.getHeight() to determine the number of equal sized divisions (pages) that will fit on the paper. The curdiv variable may be read/written to get/set the current division on the page (to set the starting division and read the ending division for multiple invocations).</dd>
+        <dt>topmargin, leftmargin</dt>
+        <dd>The topmargin and leftmargin may be used to increase the top and left margins for printing.</dd>
+      </dl>
+    </s3>
 </s2>
 <s2 title="PS">
     <p>
@@ -93,6 +138,9 @@ This is primarily for slides and creating svg images of pages.
 Large documents will create SVG files that are far too large for
 and SVG viewer to handle. Since fo documents usually have text the
 SVG document will have a large number of text elements.
+The font information for the text is obtained from the jvm in the
+same way as the AWT viewer, if the svg is view where the fonts are
+different, such as another platform, then the page will appear wrong.
     </p>
 </s2>
 <s2 title="XML">
@@ -128,6 +176,23 @@ Text as you could imagine does not work very well. It is an output format
 that you should expect bad results. The main purpose of this is to get
 a quick and dirty view of the document and the text inside it.
     </p>
+    <p>
+The TXTRenderer is a FOP renderer that produces plain ASCII text output
+that attempts to match the output of the PDFRenderer as closely as
+possible. This was originally developed to accommodate an archive system
+that could only accept plain text files. Of course when limited to plain
+fixed pitch text the output does not always look very good.
+    </p>
+    <p>
+The TXTRenderer works with a fixed size page buffer. The size of this
+buffer is controlled with the textCPI and textLPI public variables.
+The textCPI is the effective horizontal characters per inch to use.
+The textLPI is the vertical lines per inch to use. From these values
+and the page width and height the size of the buffer is calculated.
+The formatting objects to be rendered are then mapped to this grid.
+Graphic elements (lines, borders, etc) are assigned a lower priority
+than text, so text will overwrite any graphic element representations.
+    </p>
 </s2>
 
 </s1>
diff --git a/docs/xml-docs/fop/todo.xml b/docs/xml-docs/fop/todo.xml
index e45b130f7..98d551f87 100644
--- a/docs/xml-docs/fop/todo.xml
+++ b/docs/xml-docs/fop/todo.xml
@@ -29,19 +29,9 @@ comment is made about the suitability of these suggestions.
   <s2 title="Core Features">
 <s3 title="Layout">
     <p>
-This is the crucial part to getting FOP to make it to the next step.
-    </p>
-</s3>
-<s3 title="Webstart Demo">
-    <p>
-a demo using Java Webstart that runs the awt viewer and supports
-linking from an index
-    </p>
-</s3>
-<s3 title="Website">
-    <p>
-Need to improve the website to better demonstrate what fop is and
-can do. Examples, screenshots, pdf documents.
+The design for the layout is being developed under the
+<jump href="design/index.html">Design</jump> section.
+The details should be discussed on the dev mailing list.
     </p>
 </s3>
 <s3 title="Property Support">
@@ -65,23 +55,24 @@ Better support for resolution including support for "inherit" and values
 with lists.
     </p>
 </s3>
-<s3 title="Validity Checking">
+<s3 title="Examples">
     <p>
-Check the validity of children for a particular element to ensure
-there are no invalid children. Should help process the layout better.
+Better and more available examples for users and new people to get a
+feel for what FOP does.
     </p>
 </s3>
 </s2>
   <s2 title="Processing Improvements">
 <s3 title="Image Handling">
     <p>
-Needs to be a bit more solid.
+Needs to be a bit more solid. Images are not cached properly
+and image formats are not well documented.
 Allow for direct insertion of jpeg images in svg into the pdf.
     </p>
 </s3>
 <s3 title="Configuration">
     <p>
-Support for avalon. Better multithread handling.
+A better configuration setup that users can easily integrate.
     </p>
 </s3>
 <s3 title="More PDF Outputs">
@@ -95,12 +86,6 @@ deployement of pdf documents.
 Use proper i18n handling for awt viewer.
     </p>
 </s3>
-<s3 title="better abstraction of rendering classes">
-    <p>
-put all common rendering processes into an abstract class that has
-no dependancies on any specific renderers.
-    </p>
-</s3>
 </s2>
   <s2 title="Enhancements">
 <s3 title="font handling">
author	Keiron Liddle <keiron@apache.org>	2001-12-17 10:19:34 +0000
committer	Keiron Liddle <keiron@apache.org>	2001-12-17 10:19:34 +0000
commit	010d64304dd62265ebcd076fba92720daf2e0950 (patch)
tree	e984bae7141334cedafcbac7934f9e603a70ab99 /docs/xml-docs
parent	2117e3c29113281c400889d61a2bd6926039a6c3 (diff)
download	xmlgraphics-fop-010d64304dd62265ebcd076fba92720daf2e0950.tar.gz xmlgraphics-fop-010d64304dd62265ebcd076fba92720daf2e0950.zip