You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-commits@xmlgraphics.apache.org by kl...@apache.org on 2002/03/17 18:43:55 UTC

cvs commit: xml-fop/docs/xml-docs/fop download.xml embedding.xml implemented.xml output.xml readme.xml relnotes.xml resources.xml running.xml

klease      02/03/17 09:43:55

  Modified:    docs/xml-docs fop.xml
               docs/xml-docs/fop download.xml embedding.xml implemented.xml
                        output.xml readme.xml relnotes.xml resources.xml
                        running.xml
  Log:
  Submitted by: Jeremias M�rki
  Reviewed by:  Karen Lease
  - Added a page "How to get Help".
  - Added documentation for Michael's logging changes.
  - Corrected some minor typos.
  - Restructured the Resources page a bit.
  - Added some more information on the PostScript Renderer.
  - Added a comment on the FormattingResults class in "Embedding".
  - Added a comment on CVS branches.
  - A few other little additions.
  
  Revision  Changes    Path
  1.13      +30 -30    xml-fop/docs/xml-docs/fop.xml
  
  Index: fop.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop.xml,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- fop.xml	1 Mar 2002 00:02:42 -0000	1.12
  +++ fop.xml	17 Mar 2002 17:43:55 -0000	1.13
  @@ -1,32 +1,32 @@
   <?xml version="1.0"?>
  -
  -<book title="FOP XSL-FO documentation" copyright="1999-2001 The Apache Software Foundation">
  -  <external href="http://xml.apache.org/"  label="Home"/>
  -  <separator/>
  -  <page id="index"          label="About FOP"      source="fop/readme.xml"/>
  -  <page id="download"       label="Download"    source="fop/download.xml"    />
  -  <page id="running"        label="Running FOP"     source="fop/running.xml"    />
  -  <page id="embedding"      label="Embedding" source="fop/embedding.xml"    />
  -  <page id="output"      label="Ouput Formats" source="fop/output.xml"    />
  -  <page id="implemented"    label="Features" source="fop/implemented.xml"    />
  -  <page id="todo"           label="TODO"    source="fop/todo.xml"    />
  -  <page id="limitations"    label="Limitations" source="fop/limitations.xml"    />
  -  <page id="examples"       label="Examples" source="fop/examples.xml"    />
  -  <separator/>
  -  <page id="svg"            label="SVG" source="fop/svg.xml"    />
  -  <page id="extensions"     label="Extensions" source="fop/extensions.xml"    />  <page id="fonts"          label="Fonts" source="fop/fonts.xml"    />
  -  <page id="config"         label="Configuration" source="fop/configuration.xml"    />
  -  <separator/>
  -  <external href="design/index.html"      label="NEW DESIGN" />
  -  <page id="involved"       label="Getting involved" source="fop/involved.xml"    />
  -  <page id="compiling"      label="Compiling" source="fop/compiling.xml"    />
  -  <page id="testing"        label="Testing" source="fop/testing.xml"    />
  -  <separator/>
  -  <page id="relnotes"       label="Release Notes" source="fop/relnotes.xml"    />
  -  <separator/>
  -  <faqs id="faq"            label="FAQ" source="fop/faq.xml"/>
  -  <page id="bugs"           label="Bugs" source="fop/bugs.xml"    />
  -  <page id="resources"      label="Resources" source="fop/resources.xml"    />
  -  <page id="license"        label="License"     source="fop/license.xml"   />
  -
  +<book title="FOP XSL-FO documentation" copyright="1999-2002 The Apache Software Foundation">
  +	<external href="http://xml.apache.org/" label="Home"/>
  +	<separator/>
  +	<page id="index" label="About FOP" source="fop/readme.xml"/>
  +	<page id="download" label="Download" source="fop/download.xml"/>
  +	<page id="relnotes" label="Release Notes" source="fop/relnotes.xml"/>
  +	<page id="gethelp" label="How to get Help" source="fop/gethelp.xml"/>
  +	<separator/>
  +	<page id="running" label="Running FOP" source="fop/running.xml"/>
  +	<page id="embedding" label="Embedding" source="fop/embedding.xml"/>
  +	<page id="output" label="Ouput Formats" source="fop/output.xml"/>
  +	<page id="implemented" label="Features" source="fop/implemented.xml"/>
  +	<page id="todo" label="TODO" source="fop/todo.xml"/>
  +	<page id="limitations" label="Limitations" source="fop/limitations.xml"/>
  +	<page id="examples" label="Examples" source="fop/examples.xml"/>
  +	<separator/>
  +	<page id="svg" label="SVG" source="fop/svg.xml"/>
  +	<page id="extensions" label="Extensions" source="fop/extensions.xml"/>
  +	<page id="fonts" label="Fonts" source="fop/fonts.xml"/>
  +	<page id="config" label="Configuration" source="fop/configuration.xml"/>
  +	<separator/>
  +	<external href="design/index.html" label="NEW DESIGN"/>
  +	<page id="involved" label="Getting involved" source="fop/involved.xml"/>
  +	<page id="compiling" label="Compiling" source="fop/compiling.xml"/>
  +	<page id="testing" label="Testing" source="fop/testing.xml"/>
  +	<separator/>
  +	<faqs id="faq" label="FAQ" source="fop/faq.xml"/>
  +	<page id="bugs" label="Bugs" source="fop/bugs.xml"/>
  +	<page id="resources" label="Resources" source="fop/resources.xml"/>
  +	<page id="license" label="License" source="fop/license.xml"/>
   </book>
  
  
  
  1.5       +6 -2      xml-fop/docs/xml-docs/fop/download.xml
  
  Index: download.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/download.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- download.xml	17 Dec 2001 10:19:34 -0000	1.4
  +++ download.xml	17 Mar 2002 17:43:55 -0000	1.5
  @@ -21,8 +21,12 @@
          a snapshot from the cvs files <jump href="http://xml.apache.org/from-cvs/xml-fop/">here</jump>. 
          In both cases you have to build Fop yourself - see <jump href="compiling.html">Compiling Fop</jump> for details. 
       </p>
  -    <p>To run FOP from the command line, see <jump href="running.html">Running FOP</jump>. If you are 
  -       interested in embedding FOP in a Java application of your own, see 
  +    <note>
  +      <p>Important: Currently, releases of FOP are coming out of the "fop-0_20_2-maintain" branch. The "MAIN" branch is
  +      used for the redesign. See <jump href="design/index.html">NEW DESIGN</jump> for more information.</p>
  +    </note>
  +    <p>To run FOP from the command line, see <jump href="running.html">Running FOP</jump>.</p>
  +    <p>If you are interested in embedding FOP in a Java application of your own, see
          <jump href="embedding.html">Embedding FOP</jump>.
       </p>
   </s1>
  
  
  
  1.16      +38 -17    xml-fop/docs/xml-docs/fop/embedding.xml
  
  Index: embedding.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/embedding.xml,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- embedding.xml	8 Mar 2002 09:53:21 -0000	1.15
  +++ embedding.xml	17 Mar 2002 17:43:55 -0000	1.16
  @@ -37,23 +37,6 @@
      driver.setRenderer(RENDER_PDF);
      driver.run();]]></source>
   
  -  <p>You also need to set the Logger for logging messages, see
  -     <jump href="http://jakarta.apache.org/avalon/logkit/index.html">Jakarta Logkit</jump>
  -     for more information.
  -  </p>
  -    <source><![CDATA[
  -    Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
  -    PatternFormatter formatter = new PatternFormatter(
  -       "[%{priority}]: %{message}\n%{throwable}" );
  -
  -    LogTarget target = null;
  -    target = new StreamTarget(System.out, formatter);
  -
  -    hierarchy.setDefaultLogTarget(target);
  -    log = hierarchy.getLoggerFor("fop");
  -    log.setPriority(Priority.INFO);
  -    driver.setLogger(log);]]></source>
  -
     <p>To setup the user config file you can do the following
     </p>
       <source><![CDATA[
  @@ -105,7 +88,37 @@
   issues should be fixed in the upcoming JDK1.4</note>
   </p>
     </s2>
  +  <s2 title="Controlling logging">
  +  	<p>FOP uses Jakarta Avalon's 
  +  		<jump href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/logger/Logger.html">Logger</jump>
  +  		 interface to do logging. See the <jump href="http://jakarta.apache.org/avalon/">Jakarta Avalon project</jump> for more information.</p>
  +  	<p>Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a 
  +  	logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a
  +  	different Logger implementation on the Driver object. Here's an example how you would use LogKit:</p>
  +    <source><![CDATA[
  +    Hierarchy hierarchy = Hierarchy.getDefaultHierarchy();
  +    PatternFormatter formatter = new PatternFormatter(
  +       "[%{priority}]: %{message}\n%{throwable}" );
  +
  +    LogTarget target = null;
  +    target = new StreamTarget(System.out, formatter);
  +
  +    hierarchy.setDefaultLogTarget(target);
  +    log = hierarchy.getLoggerFor("fop");
  +    log.setPriority(Priority.INFO);
  +    
  +    driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]></source>
  +  <p>The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit. 
  +  More information on Jakarta LogKit can be found <jump href="http://jakarta.apache.org/avalon/logkit/index.html">here</jump>.</p>
  +  <p>Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and 
  +  JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).</p>
  +  <p>If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.</p>
  +  <p>If you want to use yet another logging facility you simply have to create a class that implements org.apache.avalon.framework.logging.Logger 
  +  and set it on the Driver object. See the existing implementations in Avalon Framework for examples.</p>
  +
  +  </s2>
     <s2 title="Hints">
  +  	<s3 title="Object reuse">
        <p>
   If FOP is going to be used multiple times within your application
   it may be useful to reuse certain objects to save time.
  @@ -117,6 +130,14 @@
   You will need to setup the driver again with a new OutputStream,
   IntputStream and renderer.
        </p>
  +  	</s3>
  +  	<s3 title="Getting information on the rendering process">
  +  		To get the number of pages that were rendered by FOP you can call Driver.getResults(). This returns a 
  +  		FormattingResults object where you can lookup the number of pages produced. It also gives you the
  +  		page-sequences that were produced along with their id attribute and their number of pages. This is particularly useful if you
  +  		render multiple documents (each enclosed by a page-sequence) and have to know the number of pages
  +  		of each document.
  +  	</s3>
     </s2>
     <s2 title="Using Fop in a servlet">  
        <p>
  
  
  
  1.18      +11 -11    xml-fop/docs/xml-docs/fop/implemented.xml
  
  Index: implemented.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/implemented.xml,v
  retrieving revision 1.17
  retrieving revision 1.18
  diff -u -r1.17 -r1.18
  --- implemented.xml	5 Feb 2002 19:14:58 -0000	1.17
  +++ implemented.xml	17 Mar 2002 17:43:55 -0000	1.18
  @@ -6,8 +6,8 @@
   <s1 title="Features">
     <s2 title="What's Implemented?">
         <p>The following formatting objects and properties of the XSL-FO 1.0
  -         W3C Recommandation are implemented.Please have also a look at the 
  -         section on <jump href="limitations.html">limitations</jump>
  +         W3C Recommandation are implemented. Please have also a look at the 
  +         section on <jump href="limitations.html">limitations</jump>.
         </p>
     </s2>
     <s2 title="1) Formatting Objects">
  @@ -17,28 +17,28 @@
       <s3 title="B.1 Declaration and Pagination and Layout Formatting Objects">
         <ul>
           <li>root</li>
  -        <li>page-sequence </li>
  +        <li>page-sequence</li>
           <li>page-sequence-master</li>
           <li>single-page-master-reference</li>
           <li>repeatable-page-master-reference</li>
           <li>repeatable-page-master-alternatives</li>
           <li>conditional-page-master-reference</li>
  -        <li>layout-master-set </li>
  -        <li>simple-page-master </li>
  -        <li>region-body </li>
  -        <li>region-before </li>
  -        <li>region-after </li>
  +        <li>layout-master-set</li>
  +        <li>simple-page-master</li>
  +        <li>region-body</li>
  +        <li>region-before</li>
  +        <li>region-after</li>
           <li>region-start</li>
           <li>region-end</li>
           <li>flow</li>
  -        <li>static-content </li>
  +        <li>static-content</li>
         </ul>
         <p>Not implemented: declarations, color-profile, title</p>
       </s3>
   
       <s3 title="B.2 Block Formatting Objects">
         <ul>
  -        <li>block </li>
  +        <li>block</li>
           <li>block-container (limited)</li>
         </ul>
       </s3>
  @@ -58,7 +58,7 @@
   
       <s3 title="B.4 Table Formatting Objects">
         <ul>
  -        <li>table </li>
  +        <li>table</li>
           <li>table-body</li>
           <li>table-cell</li>
           <li>table-column</li>
  
  
  
  1.4       +16 -5     xml-fop/docs/xml-docs/fop/output.xml
  
  Index: output.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/output.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- output.xml	5 Feb 2002 19:14:58 -0000	1.3
  +++ output.xml	17 Mar 2002 17:43:55 -0000	1.4
  @@ -115,13 +115,24 @@
         </dl>
       </s3>
   </s2>
  -<s2 title="PS">
  +<s2 title="PostScript">
       <p>
  -The postscript format can be used to send to a printer or any other
  -purpose you may have. It has good support for most text and
  -layout. images and SVG are not fully supported due to some ps
  -issues.
  +The PostScript renderer is still in its early stages and therefore still
  +missing some features. It provides good support for most text and layout. 
  +Images and SVG are not fully supported, yet. Currently, the PostScript
  +renderer generates PostScript Level 3 with most DSC comments. Actually, 
  +the only Level 3 feature used is FlateDecode, everthing else is Level 2.
       </p>
  +    <s3 title="Limitations">
  +      <ul>
  +        <li>Images and SVG may not be display correctly. SVG support is far from being complete. No image transparency is available.</li>
  +        <li>Character spacing may be wrong.</li>
  +        <li>No font embedding is supported.</li>
  +        <li>Multibyte characters are not supported.</li>
  +        <li>PPD support is still missing.</li>
  +        <li>The renderer is not yet configurable.</li>
  +      </ul>
  +    </s3>
   </s2>
   <s2 title="RTF">
       <p>
  
  
  
  1.19      +1 -1      xml-fop/docs/xml-docs/fop/readme.xml
  
  Index: readme.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/readme.xml,v
  retrieving revision 1.18
  retrieving revision 1.19
  diff -u -r1.18 -r1.19
  --- readme.xml	1 Mar 2002 00:02:42 -0000	1.18
  +++ readme.xml	17 Mar 2002 17:43:55 -0000	1.19
  @@ -15,7 +15,7 @@
   <p>
           <figure width="300" height="100" src="title.jpg" alt="FOP Title" />
   </p>
  -    <p>FOP is the world's first print formatter driven by XSL formatting
  +    <p>FOP (Formatting Objects Processor) is the world's first print formatter driven by XSL formatting
          objects and the world's first output independent formatter. It is a
          Java application that reads a formatting object tree and then
          renders the resulting pages to a specified output. <jump href="output.html">Output formats</jump>
  
  
  
  1.2       +4 -1      xml-fop/docs/xml-docs/fop/relnotes.xml
  
  Index: relnotes.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/relnotes.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- relnotes.xml	1 Mar 2002 00:02:42 -0000	1.1
  +++ relnotes.xml	17 Mar 2002 17:43:55 -0000	1.2
  @@ -22,7 +22,7 @@
            on <code>fo:page-sequence</code>, <code>fo:single-page-master-reference</code>,
            <code>fo:repeatable-page-master-reference</code> and
            <code>fo:conditional-page-master-reference</code>.</p></li>
  -       <li>JDK 1.2 (or better) is required</li>
  +       <li>JDK 1.2 (or later) is required</li>
          <li>Jimi has been removed for licensing reasons
            <p>If you need PNG support you have to download 
              <jump href="http://java.sun.com/products/jimi/">Jimi</jump>,
  @@ -32,6 +32,9 @@
            <code>src/org/apache/fop/svg/PDFGraphics2D.java</code>
            (search for jdk1.4 and remove the comments)
           </p> 
  +       </li>
  +       <li>
  +       	<p>For a more detailed list of changes, see the CHANGES file in the root of the FOP distribution.</p>
          </li>
         </ul>
       </p>
  
  
  
  1.11      +33 -7     xml-fop/docs/xml-docs/fop/resources.xml
  
  Index: resources.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/resources.xml,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- resources.xml	8 Mar 2002 09:53:21 -0000	1.10
  +++ resources.xml	17 Mar 2002 17:43:55 -0000	1.11
  @@ -13,6 +13,38 @@
       <body>
   
   <s1 title="FOP Relevant Specifications and Links">
  +  <s2 title="Mailing Lists (and archives)">
  +  	<s3 title="FOP User Mailing List">
  +  		<ul>
  +  			<li>Send a mail to <jump href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</jump>
  +  			 to subscribe. This is where user specific topics are discussed. For detailed instructions on the subscription, see 
  +  			 <jump href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</jump>.</li>
  +  			 <li>The Mailing list ARChives (MARC) at the AIMS group: 
  +		      		<jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">fop-user</jump>
  +		      	</li>(searchable)
  +		      	<li><jump href="http://xml.apache.org/mail/fop-user/">Apache archive of fop-user@apache.org</jump></li>
  +  		</ul>
  +  	</s3>
  +  	<s3 title="FOP Developer Mailing List">
  +  		<ul>
  +  			<li>Send a mail to <jump href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</jump>
  +  			 to subscribe. For detailed instructions on the subscription, see 
  +  			 <jump href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</jump>.</li>
  +  			 <li>The Mailing list ARChives (MARC) at the AIMS group: 
  +		      		<jump href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">fop-dev</jump>
  +		      	</li>(searchable)
  +		      	<li><jump href="http://xml.apache.org/mail/fop-dev/">Apache archive of fop-dev@apache.org</jump></li>
  +  		</ul>
  +  	</s3>
  +  	<s3 title="XSL:FO Mailing List (at W3C)">
  +  		<ul>
  +		      <li>There is an XSL:FO mailing list: www-xsl-fo@w3.org. Subscription info can be found here: <jump href="http://www.w3.org/Mail/Request">
  +		          http://www.w3.org/Mail/Request</jump>.</li>
  +		          <li>The archive can be found here: 
  +		          <jump href="http://lists.w3.org/Archives/Public/www-xsl-fo/">http://lists.w3.org/Archives/Public/www-xsl-fo/</jump></li>
  +  		</ul>
  +  	</s3>
  +  </s2>
     <s2 title="Specifications">
     <ul>
       <li><jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Recommendation (15 October 2001)</jump></li>
  @@ -36,14 +68,8 @@
         <li><jump href="http://www.dpawson.co.uk/xsl/sect3/bk/index.html">Dave Pawson: An introduction to XSL Formatting Objects</jump></li>
       </ul>
     </s2>
  -  <s2 title="Other resources">
  +  <s2 title="Related/Useful Products">
       <ul>
  -      <li><jump href="http://xml.apache.org/mail/fop-dev/">Apache archive of fop-dev@apache.org</jump></li>
  -      <li>The Mailing list ARChives (MARC) at the AIMS group: <jump href="http://marc.theaimsgroup.com/?l=fop-dev&amp;r=1&amp;w=2">fop-dev</jump>,
  -      <jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">fop-user</jump></li>(searchable)
  -      <li>There is an xsl:fo mailing list: www-xsl-fo@w3.org. Subscription info can be found here: <jump href="http://www.w3.org/Mail/Request">
  -          http://www.w3.org/Mail/Request</jump>. And the archive can be found here: 
  -          <jump href="http://lists.w3.org/Archives/Public/www-xsl-fo/">http://lists.w3.org/Archives/Public/www-xsl-fo/</jump></li>
         <li>
   PJ is an open source product that can be used to modify PDF documents:
   <jump href="http://www.etymon.com/pj/index.html">http://www.etymon.com/pj/index.html</jump>
  
  
  
  1.19      +1 -7      xml-fop/docs/xml-docs/fop/running.xml
  
  Index: running.xml
  ===================================================================
  RCS file: /home/cvs/xml-fop/docs/xml-docs/fop/running.xml,v
  retrieving revision 1.18
  retrieving revision 1.19
  diff -u -r1.18 -r1.19
  --- running.xml	1 Mar 2002 00:02:42 -0000	1.18
  +++ running.xml	17 Mar 2002 17:43:55 -0000	1.19
  @@ -67,13 +67,7 @@
     </s2>
   
     <s2 title="Problems">
  -    <p>If you have problems running FOP, please have a look at the 
  -       <jump href="http://www.owal.co.uk:8090/asf/servlet/asf/screen/DisplayTopics/action/SetAll/project_id/18/faq_id/276">FOP FAQ</jump>. If you don't find a solution there,
  -       you can ask for help on 
  -       <jump href="http://marc.theaimsgroup.com/?l=fop-user&amp;r=1&amp;w=2">fop-user@xml.apache.org</jump>
  -      (see  <jump href="http://xml.apache.org/mail.html">here</jump> for
  -       howto subscribe). Maybe it is a bug and maybe somebody is already working on it. 
  -    </p>
  +    <p>If you have problems running FOP, please have a look at the <jump href="gethelp.html">"How to get Help" page</jump>.</p>
     </s2>
   </s1>
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: fop-cvs-help@xml.apache.org