git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@1241041 13f79535-47bb-0310-9956-ffa450edef68

il y a 12 ans · 098ac1879e
--- a/src/documentation/content/xdocs/dev/api-doc.xml
+++ b/src/documentation/content/xdocs/dev/api-doc.xml
@@ -1,42 +0,0 @@
 <?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.
 -->
 <!-- $Id$ -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
 <document>
  <header>
    <title>FOP Development: API Documentation (javadocs)</title>
    <version>$Revision$</version>
  </header>
  <body>
    <section id="gump">
      <title>On-line Access (through Gump)</title>
      <p>FOP (and many other Apache projects) use <link href="http://gump.apache.org/">Apache Gump</link> to do a test build several times each day. One of the useful byproducts of this process is that javadocs can be created and made available.</p>
      <p>First, determine which line of development code you wish to see. If you don't know, you probably want the "Maintenance Branch", which is the line that currently produces FOP releases. See <link href="index.html#lines">Development Lines</link> for more details.</p>
      <warning>Javadocs for both development lines are made from current SVN code, and are not tied to any particular release. Both the documentation and the API may be different, even if you are working with the correct branch. Currently, the only way to obtain API documentation for a specific release is to <link href="#self-built">build it yourself</link>.</warning>
      <ul>
        <li><link href="http://gump.apache.org/javadoc/xml-fop-maintenance/build/javadocs/index.html">Javadocs for Maintenance Branch</link></li>
        <li><link href="http://gump.apache.org/javadoc/xml-fop/build/javadocs/index.html">Javadocs for Trunk (Redesign)</link></li>
      </ul>
      <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../maillist.html#fop-user">FOP User Mailing List</link> so that any problems can be fixed before the next build.</note>
    </section>
    <section id="self-built">
      <title>Building them Yourself</title>
      <p>See <link href="../download.html#source">Source Download</link> for instructions on obtaining the source code. Then see <link href="../trunk/compiling.html">Building FOP</link> for instructions on running the build process. The Ant build target that you will use to generate the API documentation is "javadocs", and the results will be stored in xml-fop/build/javadocs.</p>
    </section>
  </body>
 </document>
--- a/src/documentation/content/xdocs/site.xml
+++ b/src/documentation/content/xdocs/site.xml
@@ -211,7 +211,6 @@
  </design>

  <develop label="Develop" href="dev/" tab="development">
    <api-doc label="API Doc" href="api-doc.html"/>
    <walkthru label="Walk-Thru" href="implement.html" tab="development"/>
    <patch label="Patch Queue" href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Fop&amp;short_desc=%5BPATCH%5D&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;namedcmd=Fop+all&amp;newqueryname=fop+patch+queue&amp;tofooter=1&amp;order=Reuse+same+sort+as+last+time" tab="development"/>
    <conventions label="Conventions" href="conventions.html" tab="development"/>
--- a/src/documentation/content/xdocs/trunk/embedding.xml
+++ b/src/documentation/content/xdocs/trunk/embedding.xml
@@ -37,19 +37,39 @@
      org.apache.fop.apps.FopFactory instance. This object can be used to launch multiple
      rendering runs. For each run, create a new org.apache.fop.apps.Fop instance through
      one of the factory methods of FopFactory. In the method call you specify which output
      format (i.e. Renderer) to use and, if the selected renderer requires an OutputStream,
      which OutputStream to use for the results of the rendering. You can customize FOP's
      behaviour in a rendering run by supplying your own FOUserAgent instance. The
      FOUserAgent can, for example, be used to set your own Renderer instance (details
      below). Finally, you retrieve a SAX DefaultHandler instance from the Fop object and
      use that as the SAXResult of your transformation.
      format (i.e. MIME type) to use and, if the selected output format requires an
      OutputStream, which OutputStream to use for the results of the rendering. You can
      customize FOP's behaviour in a rendering run by supplying your own FOUserAgent
      instance. The FOUserAgent can, for example, be used to set your own document handler
      instance (details below). Finally, you retrieve a SAX DefaultHandler instance from
      the Fop object and use that as the SAXResult of your transformation.
    </p>
  </section>
  <section id="API">
    <title>The API</title>
    <p>
      FOP has many classes which express the "public" access modifier, however, this is not
      indicative of their inclusion into the public API. Every attempt will be made to keep the
      public API static, to minimize regressions for existing users, however, since the API is not
      clearly defined, the list of classes below are the generally agreed public API:
      <source><![CDATA[
 org.apache.fop.apps.*
 org.apache.fop.fo.FOEventHandler
 org.apache.fop.fo.ElementMappingRegistry
 org.apache.fop.fonts.FontManager
 org.apache.fop.events.EventListener
 org.apache.fop.events.Event
 org.apache.fop.events.model.EventSeverity
 org.apache.fop.render.ImageHandlerRegistry
 org.apache.fop.render.RendererFactory
 org.apache.fop.render.intermediate.IFContext
 org.apache.fop.render.intermediate.IFDocumentHandler
 org.apache.fop.render.intermediate.IFException
 org.apache.fop.render.intermediate.IFParser
 org.apache.fop.render.intermediate.IFSerializer
 org.apache.fop.render.intermediate.IFUtil
 org.apache.fop.render.intermediate.util.IFConcatenator]]></source>
    </p>
    <note>
      We recently changed FOP's outer API to what we consider the final API. This might require
      some changes in your application. The main reasons for these changes were performance
      improvements due to better reuse of reusable objects and reduced use of static variables
      for added flexibility in complex environments.
    </note>
  </section>
  <section id="basics">
    <title>Basic Usage Pattern</title>
@@ -425,11 +445,11 @@ try {
        </li>
        <li>
          <p>
            Set <strong>your own Renderer instance</strong>. If you want to supply your own renderer or
            configure a Renderer in a special way you can give the instance to the FOUserAgent. Normally,
            the Renderer instance is created by FOP. Example:
            Set <strong>your own Document Handler</strong>. This feature can be used for several purposes, the most likey usage of which would probably be
            binding a MIME type when the output is Intermediate Format (see <a href="#documenthandlers">Document Handlers</a>). This also allows advanced
            users to create their own implementation of the document handler.
          </p>
          <source>userAgent.setRendererOverride(myRenderer); // myRenderer is an org.apache.fop.render.Renderer</source>
          <source>userAgent.setDocumentHandlerOverride(documentHandler) // documentHandler is an instance of org.apache.fop.render.intermediate.IFDocumentHandler</source>
        </li>
        <li>
          <p>
@@ -482,6 +502,28 @@ fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));]]></source>
      The layout of the configuration file is described on the <a href="configuration.html">Configuration page</a>.
    </p>
  </section>
  <section id="documenthandlers">
    <title>Document Handlers</title>
    <p>
      The document handlers are classes that inherit from <code>org.apache.fop.render.intermediate.IFDocumentHandler</code>. This
      is an interface for which a MIME type specific implementation can be created. This same handler is used either when XSL-FO
      is used as the input or when Intermediate Format is used. Since IF is output format agnostic, if custom fonts or other
      configuration information that affect layout (specific to a particular MIME type) are given then FOP needs that contextual
      information. The document handler provides that context so that when the IF is rendered, it is more visually consistent with
      FO rendering. The code below shows an example of how a document handler can be used to provide PDF configuration data to the
      IFSerializer.
      <source><![CDATA[
 IFDocumentHandler targetHandler = userAgent.getRendererFactory().createDocumentHandler(userAgent, MimeConstants.MIME_PDF);

 IFSerializer ifSerializer = new IFSerializer();  //Create the IFSerializer to write the intermediate format
 ifSerializer.setContext(new IFContext(userAgent));
 ifSerializer.mimicDocumentHandler(targetHandler);   //Tell the IFSerializer to mimic the target format

 userAgent.setDocumentHandlerOverride(ifSerializer);  //Make sure the prepared document handler is used
      ]]></source>
      The rest of the code is the same as in <a href="#basics">Basic Usage Patterns</a>. 
    </p>
  </section>
  <section id="hints">
    <title>Hints</title>
    <section id="object-reuse">
@@ -686,6 +728,15 @@ shows the usage of the PDF Transcoder, a sub-application within FOP.
 It is used to generate a PDF document from an SVG file.
    </p>
  </section>
  <section id="ExampleConcat">
    <title>ExampleConcat.java (IF Concatenation example)</title>
    <p>
 This can be found in the <code>embedding.intermediate</code> package within the
 examples and describes how IF can be concatenated to produce a document. Because
 IF has been through FOPs layout engine, it should be visually consistent with FO
 rendered documents while allowing the user to merge numerous documents together.
    </p>
  </section>
  <section id="example-notes">
    <title>Final notes</title>
    <p>