From 075dda8aec77eb4edfddb24ec19a3f93f5f5d4af Mon Sep 17 00:00:00 2001
From: Joerg Pietschmann <pietsch@apache.org>
Date: Thu, 12 Sep 2002 20:38:31 +0000
Subject: [PATCH] A few more JavaDoc related patches. Submitted by:	Victor
 Mote

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_20_2-maintain@195175 13f79535-47bb-0310-9956-ffa450edef68
---
 build.sh                                      |   4 +
 build.xml                                     | 103 ++++++++++++------
 src/codegen/elements.xsl                      |   2 +-
 src/codegen/enumgen.xsl                       |   2 +-
 src/codegen/properties.xsl                    |   2 +-
 .../configuration/ConfigurationReader.java    |  17 +--
 src/org/apache/fop/datatypes/package.html     |   3 +-
 src/org/apache/fop/extensions/Label.java      |   5 +
 src/org/apache/fop/extensions/Outline.java    |   5 +-
 .../ConditionalPageMasterReference.java       |   7 ++
 .../fop/fo/pagination/LayoutMasterSet.java    |   7 ++
 .../fo/pagination/PageMasterReference.java    |   5 +-
 .../fop/fo/pagination/PageSequence.java       |   8 +-
 .../fop/fo/pagination/PageSequenceMaster.java |   7 ++
 src/org/apache/fop/fo/pagination/Region.java  |   2 +-
 .../apache/fop/fo/pagination/RegionAfter.java |   7 ++
 .../fop/fo/pagination/RegionBefore.java       |   7 ++
 .../apache/fop/fo/pagination/RegionBody.java  |   7 ++
 .../apache/fop/fo/pagination/RegionEnd.java   |   7 ++
 .../apache/fop/fo/pagination/RegionStart.java |   7 ++
 .../RepeatablePageMasterAlternatives.java     |   7 ++
 .../RepeatablePageMasterReference.java        |   7 ++
 src/org/apache/fop/fo/pagination/Root.java    |   5 +-
 .../fop/fo/pagination/SimplePageMaster.java   |   7 ++
 .../pagination/SinglePageMasterReference.java |   7 ++
 .../apache/fop/image/AbstractFopImage.java    |   4 +-
 src/org/apache/fop/pdf/package.html           |   2 +-
 .../apache/fop/render/awt/AWTRenderer.java    |  23 ++--
 .../apache/fop/render/mif/MIFRenderer.java    |  12 +-
 .../apache/fop/render/pcl/PCLRenderer.java    |  11 +-
 src/org/apache/fop/render/pdf/package.html    |   2 +-
 .../apache/fop/render/txt/TXTRenderer.java    |   7 +-
 src/org/apache/fop/render/xml/package.html    |   2 +-
 src/overview.html                             |  45 +++++++-
 34 files changed, 269 insertions(+), 86 deletions(-)

diff --git a/build.sh b/build.sh
index 58b8c3203..c53d45bb6 100755
--- a/build.sh
+++ b/build.sh
@@ -30,6 +30,10 @@ LIBDIR=lib
 LOCALCLASSPATH=$JAVA_HOME/lib/tools.jar:$JAVA_HOME/lib/classes.zip:$LIBDIR/ant-1.4.1.jar:$LIBDIR/batik.jar:$LIBDIR/buildtools.jar:$LIBDIR/xercesImpl-2.0.1.jar:$LIBDIR/xalan-2.3.1.jar:$LIBDIR/xml-apis.jar:$LIBDIR/bsf.jar
 LOCALCLASSPATH=$LOCALCLASSPATH:$LIBDIR/jimi-1.0.jar:$LIBDIR/avalon-framework-cvs-20020806.jar
 
+# antRun must be executable (can't do this in build.xml because Ant uses antRun
+# to do the chmod)
+chmod +rx $LIBDIR/bin/antRun
+
 ANT_HOME=$LIBDIR
 
 # For Cygwin, switch paths to Windows format before running java
diff --git a/build.xml b/build.xml
index 15cc911ea..5e7d94822 100644
--- a/build.xml
+++ b/build.xml
@@ -276,6 +276,11 @@ Sometimes ant gives out this warnings, but the build is finished without any pro
 
     <property name="tools.pkg" value="org/apache/fop/tools"/>
 
+    <property name="xslfo.std"
+              value="http://www.w3.org/TR/2001/REC-xsl-20011015/xslspec.html"/>
+    <property name="xslfo.std.id"
+              value="XSL-FO 1.0"/>
+
 
     <!-- insert custom font information here (step 1 of 2) -->
     <!-- use this as a template 
@@ -403,7 +408,11 @@ Sometimes ant gives out this warnings, but the build is finished without any pro
     <!-- copy src files -->
     <copy todir="${build.src}" filtering="yes">
       <fileset dir="${src.dir}" 
-         excludes="**/package.html, **/${jimi},**/${jai},**/${xsltransform},**/${trax},**/apps/TraxInputHandler.java"/>
+        excludes="**/${jimi},**/${jai},**/${xsltransform},**/${trax},**/apps/TraxInputHandler.java"/>
+      <filterset>
+        <filter token="XSLFO-STD" value="${xslfo.std}"/>
+        <filter token="XSLFO-STDID" value="${xslfo.std.id}"/>
+      </filterset>
     </copy>
   </target>
 
@@ -448,96 +457,93 @@ Sometimes ant gives out this warnings, but the build is finished without any pro
     </dependset>
 
     <style in="${allprops.xml}" style="${genconst.xsl}"
-        out="${build.src}/org/apache/fop/fo/properties/Constants.java"/>
-
+           out="${build.src}/${properties.dir}/Constants.java"/>
     <style in="${foproperties.xml}" style="${properties.xsl}"
-        out="${build.src}/org/apache/fop/fo/properties/fo_${ignore_this}"/>
+           out="${build.src}/${properties.dir}/fo_${ignore_this}"/>
     <style in="${foproperties.xml}" style="${propmap.xsl}"
-        out="${build.src}/org/apache/fop/fo/properties/FOPropertyMapping.java"/>
+           out="${build.src}/${properties.dir}/FOPropertyMapping.java"/>
     <style in="${foproperties.xml}" style="${enumgen.xsl}"
-        out="${build.src}/org/apache/fop/fo/properties/foenums_${ignore_this}"/>
-
+           out="${build.src}/${properties.dir}/foenums_${ignore_this}"/>
     <style in="${extproperties.xml}" style="${propmap.xsl}"
-        out="${build.src}/org/apache/fop/fo/properties/ExtensionPropertyMapping.java"/>
+           out="${build.src}/${properties.dir}/ExtensionPropertyMapping.java"/>
+    <style in="${encodings.xml}" style="${charlist.xsl}"
+           out="${build.src}/org/apache/fop/render/pdf/CodePointMapping.java"/>
 
     <style
-       in="${encodings.xml}" style="${charlist.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/CodePointMapping.java"/>
-    <style
-       in="${Courier.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/Courier.java">
+      in="${Courier.xml}" style="${fontfile.xsl}"
+      out="${build.src}/${fonts.dir}/Courier.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
-       in="${Courier-Oblique.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/CourierOblique.java">
+      in="${Courier-Oblique.xml}" style="${fontfile.xsl}"
+      out="${build.src}/${fonts.dir}/CourierOblique.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Courier-Bold.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/CourierBold.java">
+       out="${build.src}/${fonts.dir}/CourierBold.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Courier-BoldOblique.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/CourierBoldOblique.java">
+       out="${build.src}/${fonts.dir}/CourierBoldOblique.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Helvetica.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/Helvetica.java">
+       out="${build.src}/${fonts.dir}/Helvetica.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Helvetica-Bold.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/HelveticaBold.java">
+       out="${build.src}/${fonts.dir}/HelveticaBold.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Helvetica-Oblique.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/HelveticaOblique.java">
+       out="${build.src}/${fonts.dir}/HelveticaOblique.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Helvetica-BoldOblique.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/HelveticaBoldOblique.java">
+       out="${build.src}/${fonts.dir}/HelveticaBoldOblique.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Times-Roman.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/TimesRoman.java">
+       out="${build.src}/${fonts.dir}/TimesRoman.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Times-Italic.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/TimesItalic.java">
+       out="${build.src}/${fonts.dir}/TimesItalic.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Times-Bold.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/TimesBold.java">
+       out="${build.src}/${fonts.dir}/TimesBold.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Times-BoldItalic.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/TimesBoldItalic.java">
+       out="${build.src}/${fonts.dir}/TimesBoldItalic.java">
       <param name="encoding" expression="${textfontencoding}"/>
     </style>
     <style
        in="${Symbol.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/Symbol.java"/>
+       out="${build.src}/${fonts.dir}/Symbol.java"/>
     <style
        in="${ZapfDingbats.xml}" style="${fontfile.xsl}"
-       out="${build.src}/org/apache/fop/render/pdf/fonts/ZapfDingbats.java"/>
+       out="${build.src}/${fonts.dir}/ZapfDingbats.java"/>
 
     <!-- custom fonts (Use t1fontfile.xsl instead of fontfile.xsl for Type 1 fonts!) step 2/2 -->
     <!-- use this as a template for type 1 fonts: 
     <xslt infile="${myfont.xml}" xsltfile="${t1fontfile.xsl}"
-        outfile="${build.src}/org/apache/fop/render/pdf/fonts/myfont.java" smart="yes"/>
+        outfile="${build.src}/${fonts.dir}/myfont.java" smart="yes"/>
     -->
     <!-- use this as a template for truetype fonts 
     <xslt infile="${myfont.xml}" xsltfile="${ttffontfile.xsl}" 
-        outfile="${build.src}/org/apache/fop/render/pdf/fonts/myfont.java" smart="yes"/>
+        outfile="${build.src}/${fonts.dir}/myfont.java" smart="yes"/>
     -->
 
 
@@ -619,15 +625,13 @@ Sometimes ant gives out this warnings, but the build is finished without any pro
   <!-- =================================================================== -->
   <target name="prepare-docs" depends="init">
     <mkdir dir="${build.docs}"/>
-    <!-- sets exec permission for antRun on Unix systems. necessary for javadoc-->
-    <chmod file="${lib.dir}/bin/antRun" perm="ugo+rx" />
   </target>
 
 
   <!-- =================================================================== -->
   <!-- Creates the API documentation                                       -->
   <!-- =================================================================== -->
-  <target name="javadocs" depends="prepare-src">
+  <target name="javadocs" depends="codegen,prepare-src">
     <echo message="Producing the javadoc files "/>
     <mkdir dir="${build.javadocs}"/>
     <javadoc packagenames="${packages}"
@@ -638,7 +642,40 @@ Sometimes ant gives out this warnings, but the build is finished without any pro
              windowtitle="${Name} API"
              doctitle="${Name}"
              bottom="Copyright &#169; ${year} Apache Software Foundation. All Rights Reserved."
-    />
+             overview="${build.src}/overview.html"
+             use="true"
+             failonerror="true">
+      <group title="Control and Startup">
+        <package name="org.apache.fop.apps"/>
+        <package name="org.apache.fop.configuration"/>
+        <package name="org.apache.fop.messaging"/>
+      </group>
+      <group title="XSL-FO Document (Input)">
+        <package name="org.apache.fop.fo"/>
+        <package name="org.apache.fop.fo.*"/>
+        <package name="org.apache.fop.datatypes"/>
+      </group>
+      <group title="Area Tree Document (Intermediate)">
+        <package name="org.apache.fop.layout"/>
+        <package name="org.apache.fop.layout.*"/>
+      </group>
+      <group title="Rendered Document (Output)">
+        <package name="org.apache.fop.render"/>
+        <package name="org.apache.fop.render.*"/>
+        <package name="org.apache.fop.viewer"/>
+      </group>
+      <group title="Utility">
+        <package name="org.apache.fop.pdf"/>
+        <package name="org.apache.fop.mif"/>
+        <package name="org.apache.fop.tools"/>
+        <package name="org.apache.fop.tools.*"/>
+        <package name="org.apache.fop.svg"/>
+        <package name="org.apache.fop.image"/>
+        <package name="org.apache.fop.image.*"/>
+        <package name="org.apache.fop.fonts"/>
+        <package name="org.apache.fop.fonts.*"/>
+      </group>
+    </javadoc>
   </target>
 
   <target name="htmldoc" depends="prepare-src">
diff --git a/src/codegen/elements.xsl b/src/codegen/elements.xsl
index 3fcca188d..7896f6cab 100644
--- a/src/codegen/elements.xsl
+++ b/src/codegen/elements.xsl
@@ -89,7 +89,7 @@
   </xsl:choose>
 </xsl:variable>
 
-<redirect:write select="concat('@org/apache/fop@/{$prefixVal}/', $classname, '.java')">
+<redirect:write select="concat('./{$prefixVal}/', $classname, '.java')">
 package org.apache.fop.<xsl:value-of select="$prefixVal"/>;
 
 import org.apache.fop.fo.*;
diff --git a/src/codegen/enumgen.xsl b/src/codegen/enumgen.xsl
index 80c8db4fd..4c3e6db5a 100644
--- a/src/codegen/enumgen.xsl
+++ b/src/codegen/enumgen.xsl
@@ -32,7 +32,7 @@
    </xsl:variable>
 
    <xsl:if test="$bEnum='true' or contains($bSubpropEnum, 'true')">
-<redirect:write select="concat('@org/apache/fop@/fo/properties/', $classname, '.java')">
+      <redirect:write select="concat('./', $classname, '.java')">
 package org.apache.fop.fo.properties;
 
 <!-- Handle enumeration values -->
diff --git a/src/codegen/properties.xsl b/src/codegen/properties.xsl
index f00be7833..79decfea3 100644
--- a/src/codegen/properties.xsl
+++ b/src/codegen/properties.xsl
@@ -204,7 +204,7 @@
   <xsl:text> implements </xsl:text><xsl:value-of select="$eclassname"/></xsl:if>
 </xsl:variable>
 
-<redirect:write select="concat('@org/apache/fop@/fo/properties/', $classname, '.java')">
+<redirect:write select="concat('./', $classname, '.java')">
 package org.apache.fop.fo.properties;
 
 import java.util.Hashtable;
diff --git a/src/org/apache/fop/configuration/ConfigurationReader.java b/src/org/apache/fop/configuration/ConfigurationReader.java
index a6771ef7a..00ccc5409 100644
--- a/src/org/apache/fop/configuration/ConfigurationReader.java
+++ b/src/org/apache/fop/configuration/ConfigurationReader.java
@@ -24,18 +24,21 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.configuration.Configuration;
 
 /**
- * entry class for reading configuration from file and creating a configuration
- * class. typical use looks like that: <br>
+ * Entry class for reading configuration from file and creating a configuration
+ * class. Example of typical use:
  *
- * <code>ConfigurationReader reader = new ConfigurationReader ("config.xml","standard");
+ * <pre>ConfigurationReader reader = new ConfigurationReader ("config.xml","standard");
  * try {
- * reader.start();
- * } catch (org.apache.fop.apps.FOPException error) {
- * reader.dumpError(error);
+ *   reader.start();
  * }
- * </code>
+ * catch (org.apache.fop.apps.FOPException error) {
+ *   reader.dumpError(error);
+ * }</pre>
+ *
  * Once the configuration has been setup, the information can be accessed with
  * the methods of StandardConfiguration.
+ *
+ * @version $Revision$
  */
 public class ConfigurationReader {
 
diff --git a/src/org/apache/fop/datatypes/package.html b/src/org/apache/fop/datatypes/package.html
index 05d202085..47676c4c3 100644
--- a/src/org/apache/fop/datatypes/package.html
+++ b/src/org/apache/fop/datatypes/package.html
@@ -1,6 +1,7 @@
 <HTML>
 <TITLE>org.apache.fop.datatypes Package</TITLE>
 <BODY>
-<P>XSL Datatypes</P>
+<P>Classes representing XSL-FO Datatypes (See &para;5.11 of the XSL 1.0 Standard).
+</P>
 </BODY>
 </HTML>
\ No newline at end of file
diff --git a/src/org/apache/fop/extensions/Label.java b/src/org/apache/fop/extensions/Label.java
index 7f0b73aaa..791724e94 100644
--- a/src/org/apache/fop/extensions/Label.java
+++ b/src/org/apache/fop/extensions/Label.java
@@ -10,6 +10,11 @@ package org.apache.fop.extensions;
 import org.apache.fop.fo.*;
 
 
+/**
+ * Class representing destinations or targets within a document (/Dest
+ * objects in PDF, called "Destinations" in Adobe Acrobat). Used for the
+ * bookmark/outline extension.
+ */
 public class Label extends ExtensionObj {
     private StringBuffer textBuffer;
 
diff --git a/src/org/apache/fop/extensions/Outline.java b/src/org/apache/fop/extensions/Outline.java
index db1dd2084..072c10d95 100644
--- a/src/org/apache/fop/extensions/Outline.java
+++ b/src/org/apache/fop/extensions/Outline.java
@@ -14,7 +14,10 @@ import org.apache.fop.datatypes.IDReferences;
 
 import java.util.*;
 
-
+/**
+ * Class representing an outline entry (an /OUT object in a PDF file, but
+ * referred to as a "Bookmark" from within Adobe Acrobat).
+ */
 public class Outline extends ExtensionObj {
     private Label _label;
     private ArrayList _outlines = new ArrayList();
diff --git a/src/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java b/src/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java
index d84fc1327..6b3714e4b 100644
--- a/src/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java
+++ b/src/org/apache/fop/fo/pagination/ConditionalPageMasterReference.java
@@ -11,6 +11,13 @@ import org.apache.fop.fo.*;
 import org.apache.fop.fo.properties.*;
 import org.apache.fop.apps.FOPException;
 
+/**
+ * Class modeling the fo:conditional-page-master-reference object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_conditional-page-master-reference"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.11</a>
+ */
 public class ConditionalPageMasterReference extends FObj {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/LayoutMasterSet.java b/src/org/apache/fop/fo/pagination/LayoutMasterSet.java
index 6c5dcc5cb..5f9688f37 100644
--- a/src/org/apache/fop/fo/pagination/LayoutMasterSet.java
+++ b/src/org/apache/fop/fo/pagination/LayoutMasterSet.java
@@ -17,6 +17,13 @@ import org.apache.fop.layout.PageMaster;
 import java.util.HashMap;
 import java.util.Iterator;
 
+/**
+ * Class modeling the fo:layout-master-set object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_layout-master-set"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.6</a>
+ */
 public class LayoutMasterSet extends FObj {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/PageMasterReference.java b/src/org/apache/fop/fo/pagination/PageMasterReference.java
index 244919855..0fa6908a0 100644
--- a/src/org/apache/fop/fo/pagination/PageMasterReference.java
+++ b/src/org/apache/fop/fo/pagination/PageMasterReference.java
@@ -12,8 +12,9 @@ import org.apache.fop.fo.properties.*;
 import org.apache.fop.apps.FOPException;
 
 /**
- * Base PageMasterReference class. Provides implementation for handling the
- * master-reference attribute and containment within a PageSequenceMaster
+ * Abstract base class for PageMasterReference classes. Provides
+ * implementation for handling the master-reference attribute and
+ * containment within a PageSequenceMaster
  */
 public abstract class PageMasterReference extends FObj
     implements SubSequenceSpecifier {
diff --git a/src/org/apache/fop/fo/pagination/PageSequence.java b/src/org/apache/fop/fo/pagination/PageSequence.java
index 2a40108b1..017bdae86 100644
--- a/src/org/apache/fop/fo/pagination/PageSequence.java
+++ b/src/org/apache/fop/fo/pagination/PageSequence.java
@@ -25,8 +25,12 @@ import java.util.HashMap;
 import java.util.ArrayList;
 
 /**
- * This provides pagination of flows onto pages. Much of the logic for paginating
- * flows is contained in this class. The main entry point is the format method.
+ * Class modeling the fo:page-sequence object. Provides pagination of flows.
+ * Much of the logic for paginating flows is contained in this class. The main
+ * entry point is the format method.
+ *
+ * @see <a href="@XSLFO-STD@#fo_page-sequence" target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.5</a>
  */
 public class PageSequence extends FObj {
     //
diff --git a/src/org/apache/fop/fo/pagination/PageSequenceMaster.java b/src/org/apache/fop/fo/pagination/PageSequenceMaster.java
index 864129752..b57719b25 100644
--- a/src/org/apache/fop/fo/pagination/PageSequenceMaster.java
+++ b/src/org/apache/fop/fo/pagination/PageSequenceMaster.java
@@ -16,6 +16,13 @@ import org.apache.fop.apps.FOPException;
 // Java
 import java.util.ArrayList;
 
+/**
+ * Class modeling the fo:page-sequence-master object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_page-sequence-master"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.7</a>
+ */
 public class PageSequenceMaster extends FObj {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/Region.java b/src/org/apache/fop/fo/pagination/Region.java
index e5925a900..412f8e0e8 100644
--- a/src/org/apache/fop/fo/pagination/Region.java
+++ b/src/org/apache/fop/fo/pagination/Region.java
@@ -14,7 +14,7 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.layout.RegionArea;
 
 /**
- * This is an abstract base class for pagination regions
+ * Abstract base class for pagination regions.
  */
 public abstract class Region extends FObj {
     public static final String PROP_REGION_NAME = "region-name";
diff --git a/src/org/apache/fop/fo/pagination/RegionAfter.java b/src/org/apache/fop/fo/pagination/RegionAfter.java
index 251cbd822..34458af3b 100644
--- a/src/org/apache/fop/fo/pagination/RegionAfter.java
+++ b/src/org/apache/fop/fo/pagination/RegionAfter.java
@@ -15,6 +15,13 @@ import org.apache.fop.layout.RegionArea;
 import org.apache.fop.layout.BorderAndPadding;
 import org.apache.fop.layout.BackgroundProps;
 
+/**
+ * Class modeling the fo:region-after object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_region-after"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.15</a>
+ */
 public class RegionAfter extends Region {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/RegionBefore.java b/src/org/apache/fop/fo/pagination/RegionBefore.java
index a62303e45..4a60880bd 100644
--- a/src/org/apache/fop/fo/pagination/RegionBefore.java
+++ b/src/org/apache/fop/fo/pagination/RegionBefore.java
@@ -15,6 +15,13 @@ import org.apache.fop.layout.BorderAndPadding;
 import org.apache.fop.layout.BackgroundProps;
 import org.apache.fop.apps.FOPException;
 
+/**
+ * Class modeling the fo:region-before object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_region-before"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.14</a>
+ */
 public class RegionBefore extends Region {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/RegionBody.java b/src/org/apache/fop/fo/pagination/RegionBody.java
index 782aca9c3..1271e3ae3 100644
--- a/src/org/apache/fop/fo/pagination/RegionBody.java
+++ b/src/org/apache/fop/fo/pagination/RegionBody.java
@@ -18,6 +18,13 @@ import org.apache.fop.layout.BorderAndPadding;
 import org.apache.fop.layout.BackgroundProps;
 import org.apache.fop.layout.MarginProps;
 
+/**
+ * Class modeling the fo:region-body object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_region-body"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.13</a>
+ */
 public class RegionBody extends Region {
 
 
diff --git a/src/org/apache/fop/fo/pagination/RegionEnd.java b/src/org/apache/fop/fo/pagination/RegionEnd.java
index d32237182..e3cb8e0f5 100644
--- a/src/org/apache/fop/fo/pagination/RegionEnd.java
+++ b/src/org/apache/fop/fo/pagination/RegionEnd.java
@@ -15,6 +15,13 @@ import org.apache.fop.layout.BorderAndPadding;
 import org.apache.fop.layout.BackgroundProps;
 import org.apache.fop.apps.FOPException;
 
+/**
+ * Class modeling the fo:region-end object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_region-end"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.17</a>
+ */
 public class RegionEnd extends Region {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/RegionStart.java b/src/org/apache/fop/fo/pagination/RegionStart.java
index be7c36a1c..d9c2d7620 100644
--- a/src/org/apache/fop/fo/pagination/RegionStart.java
+++ b/src/org/apache/fop/fo/pagination/RegionStart.java
@@ -15,6 +15,13 @@ import org.apache.fop.layout.BorderAndPadding;
 import org.apache.fop.layout.BackgroundProps;
 import org.apache.fop.apps.FOPException;
 
+/**
+ * Class modeling the fo:region-start object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_region-start"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.16</a>
+ */
 public class RegionStart extends Region {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java b/src/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java
index cd6d39399..a30502b98 100644
--- a/src/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java
+++ b/src/org/apache/fop/fo/pagination/RepeatablePageMasterAlternatives.java
@@ -13,6 +13,13 @@ import org.apache.fop.apps.FOPException;
 // Java
 import java.util.ArrayList;
 
+/**
+ * Class modeling the fo:repeatable-page-master-alternatives object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_repeatable-page-master-alternatives"
+ *      target="_xslfostd">@XSLFO-STDID@
+ *      &para;6.4.10</a>
+ */
 public class RepeatablePageMasterAlternatives extends FObj
     implements SubSequenceSpecifier {
 
diff --git a/src/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java b/src/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java
index 7f95587a3..e9b8b1927 100644
--- a/src/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java
+++ b/src/org/apache/fop/fo/pagination/RepeatablePageMasterReference.java
@@ -10,6 +10,13 @@ package org.apache.fop.fo.pagination;
 import org.apache.fop.fo.*;
 import org.apache.fop.apps.FOPException;
 
+/**
+ * Class modeling the fo:repeatable-page-master-reference object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_repeatable-page-master-reference"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.9</a>
+ */
 public class RepeatablePageMasterReference extends PageMasterReference
     implements SubSequenceSpecifier {
 
diff --git a/src/org/apache/fop/fo/pagination/Root.java b/src/org/apache/fop/fo/pagination/Root.java
index bf8e1b7b0..d7b0b848a 100644
--- a/src/org/apache/fop/fo/pagination/Root.java
+++ b/src/org/apache/fop/fo/pagination/Root.java
@@ -16,8 +16,11 @@ import org.apache.fop.apps.FOPException;
 import org.apache.fop.extensions.ExtensionObj;
 
 /**
- * The fo:root formatting object. Contains page masters, root extensions,
+ * Class modeling the fo:root object. Contains page masters, root extensions,
  * page-sequences.
+ *
+ * @see <a href="@XSLFO-STD@#fo_root" target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.2</a>
  */
 public class Root extends FObj {
 
diff --git a/src/org/apache/fop/fo/pagination/SimplePageMaster.java b/src/org/apache/fop/fo/pagination/SimplePageMaster.java
index b5f34440a..e792df673 100644
--- a/src/org/apache/fop/fo/pagination/SimplePageMaster.java
+++ b/src/org/apache/fop/fo/pagination/SimplePageMaster.java
@@ -19,6 +19,13 @@ import org.apache.fop.apps.FOPException;
 import java.util.HashMap;
 import java.util.Iterator;
 
+/**
+ * Class modeling the fo:simple-page-master object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_simple-page-master"
+ *     target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.12</a>
+ */
 public class SimplePageMaster extends FObj {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/fo/pagination/SinglePageMasterReference.java b/src/org/apache/fop/fo/pagination/SinglePageMasterReference.java
index 7e60f54fe..f65fd5a6a 100644
--- a/src/org/apache/fop/fo/pagination/SinglePageMasterReference.java
+++ b/src/org/apache/fop/fo/pagination/SinglePageMasterReference.java
@@ -9,6 +9,13 @@ package org.apache.fop.fo.pagination;
 import org.apache.fop.fo.*;
 import org.apache.fop.apps.FOPException;
 
+/**
+ * Class modeling the fo:single-page-master-reference object.
+ *
+ * @see <a href="@XSLFO-STD@#fo_single-page-master-reference"
+       target="_xslfostd">@XSLFO-STDID@
+ *     &para;6.4.8</a>
+ */
 public class SinglePageMasterReference extends PageMasterReference {
 
     public static class Maker extends FObj.Maker {
diff --git a/src/org/apache/fop/image/AbstractFopImage.java b/src/org/apache/fop/image/AbstractFopImage.java
index fbabe05dc..234343428 100644
--- a/src/org/apache/fop/image/AbstractFopImage.java
+++ b/src/org/apache/fop/image/AbstractFopImage.java
@@ -19,8 +19,8 @@ import java.net.URL;
 
 /**
  * Base class to implement the FopImage interface.
- * @author Eric SCHAEFFER
- * @author Modified by Eric Dalquist - 9/14/2001 - ebdalqui@mtu.edu
+ * @author Eric Schaeffer
+ * @author <a href="mailto:ebdalqui@mtu.edu">Eric Dalquist</a>
  * @see FopImage
  */
 public abstract class AbstractFopImage implements FopImage {
diff --git a/src/org/apache/fop/pdf/package.html b/src/org/apache/fop/pdf/package.html
index 1fd09411d..e86318adc 100644
--- a/src/org/apache/fop/pdf/package.html
+++ b/src/org/apache/fop/pdf/package.html
@@ -1,7 +1,7 @@
 <HTML>
 <TITLE>org.apache.fop.pdf Package</TITLE>
 <BODY>
-<P>Classes for handling the low-level creation of PDF documents</P>
+<P>Classes for handling the low-level creation of PDF documents.</P>
 <P>These classes were developed for FOP, but could be used by other
 applications wishing to produce PDF.</P>
 </BODY>
diff --git a/src/org/apache/fop/render/awt/AWTRenderer.java b/src/org/apache/fop/render/awt/AWTRenderer.java
index 42c893ef7..9fb088c63 100644
--- a/src/org/apache/fop/render/awt/AWTRenderer.java
+++ b/src/org/apache/fop/render/awt/AWTRenderer.java
@@ -7,13 +7,6 @@
 
 package org.apache.fop.render.awt;
 
-/*
- * originally contributed by
- * Juergen Verwohlt: Juergen.Verwohlt@jCatalog.com,
- * Rainer Steinkuhle: Rainer.Steinkuhle@jCatalog.com,
- * Stanislav Gorkhover: Stanislav.Gorkhover@jCatalog.com
- */
-
 import org.apache.fop.apps.*;
 import org.apache.fop.datatypes.*;
 import org.apache.fop.image.*;
@@ -52,10 +45,18 @@ import java.util.*;
 import javax.swing.*;
 
 /**
-  Modified by Mark Lillywhite mark-fop@inomial.com. Did lots of
-  cleaning up and made the class implement the new Renderer
-  interface. This class could also do with a general audit,
-  and I suspect it's not swing-thread-safe either.
+ * @author <a href="mailto:Juergen.Verwohlt@jCatalog.com">Juergen Verwohlt</a>
+ * @author <a href="mailto:Rainer.Steinkuhle@jCatalog.com">Rainer Steinkuhle</a>
+ * @author <a href="mailto:Stanislav.Gorkhover@jCatalog.com">Stanislav
+ *   Gorkhover</a>
+ * @author <a href="mailto:mark-fop@inomial.com">Mark Lillywhite</a>
+ */
+
+/*
+ * Mark Lillywhite(?) made the following comment: Did lots of
+ * cleaning up and made the class implement the new Renderer
+ * interface. This class could also do with a general audit,
+ * and I suspect it's not swing-thread-safe either.
 */
 public class AWTRenderer extends AbstractRenderer implements Printable, Pageable {
 
diff --git a/src/org/apache/fop/render/mif/MIFRenderer.java b/src/org/apache/fop/render/mif/MIFRenderer.java
index 073c7542d..989490510 100644
--- a/src/org/apache/fop/render/mif/MIFRenderer.java
+++ b/src/org/apache/fop/render/mif/MIFRenderer.java
@@ -5,8 +5,6 @@
  * LICENSE file included with these sources.
  */
 
-// Author : Seshadri G
-
 package org.apache.fop.render.mif;
 
 // FOP
@@ -34,13 +32,11 @@ import java.io.OutputStream;
 import java.awt.Rectangle;
 
 /**
- * Renderer that renders areas to MIF
+ * Renders areas to MIF. Collects all the Pages and print them out at the end.
+ * This means that the MIF renderer does not stream.
  *
- * Modified by Mark Lillywhite mark-fop@inomial.com. Updated to
- * collect all the Pages and print them out at the end. This means
- * that the MIF renderer does not stream, but on the other hand
- * it should still work. I don't have an MIF view to test it with,
- * you see.
+ * @author Seshadri G
+ * @author <a href="mailto:mark-fop@inomial.com">Mark Lillywhite</a>
  */
 public class MIFRenderer extends AbstractRenderer {
 
diff --git a/src/org/apache/fop/render/pcl/PCLRenderer.java b/src/org/apache/fop/render/pcl/PCLRenderer.java
index a0fe2bd67..0a8e33cea 100755
--- a/src/org/apache/fop/render/pcl/PCLRenderer.java
+++ b/src/org/apache/fop/render/pcl/PCLRenderer.java
@@ -28,11 +28,12 @@ import java.io.IOException;
 import java.io.OutputStream;
 
 /**
- * Renderer that renders areas to PCL
- * Created by Arthur E Welch III while at M&I EastPoint Technology
- * Donated by EastPoint to the Apache FOP project March 2, 2001.
- * Modified by Mark Lillywhite mark-fop@inomial.com to use the
- * new Renderer interface.
+ * Renders areas to PCL.
+ *
+ * @author Arthur E Welch III (while at M&I EastPoint Technology --
+ *     donated by EastPoint to the Apache FOP project March 2, 2001)
+ * @author <a href="mailto:mark-fop@inomial.com">Mark Lillywhite</a> (to use
+ *     the new Renderer interface)
  */
 public class PCLRenderer extends PrintRenderer {
 
diff --git a/src/org/apache/fop/render/pdf/package.html b/src/org/apache/fop/render/pdf/package.html
index 1bcf2644f..dc1e3fc1c 100644
--- a/src/org/apache/fop/render/pdf/package.html
+++ b/src/org/apache/fop/render/pdf/package.html
@@ -1,6 +1,6 @@
 <HTML>
 <TITLE>org.apache.fop.render.pdf Package</TITLE>
 <BODY>
-<P>classes for rendering to PDF</P>
+<P>Classes for rendering the Area Tree to PDF.</P>
 </BODY>
 </HTML>
\ No newline at end of file
diff --git a/src/org/apache/fop/render/txt/TXTRenderer.java b/src/org/apache/fop/render/txt/TXTRenderer.java
index 6cec9c672..135ace970 100755
--- a/src/org/apache/fop/render/txt/TXTRenderer.java
+++ b/src/org/apache/fop/render/txt/TXTRenderer.java
@@ -33,10 +33,11 @@ import java.io.OutputStream;
 import java.util.ArrayList;
 
 /**
- * Renderer that renders areas to plain text
+ * Renderer that renders areas to plain text.
  *
- * Modified by Mark Lillywhite mark-fop@inomial.com to use the new
- * Renderer interface.
+ * @author unascribed
+ * @author <a href="mailto:mark-fop@inomial.com">Mark Lillywhite</a> (to use
+ *     the new Renderer interface)
  */
 public class TXTRenderer extends PrintRenderer {
 
diff --git a/src/org/apache/fop/render/xml/package.html b/src/org/apache/fop/render/xml/package.html
index ecabe3547..f82e08109 100644
--- a/src/org/apache/fop/render/xml/package.html
+++ b/src/org/apache/fop/render/xml/package.html
@@ -1,6 +1,6 @@
 <HTML>
 <TITLE>org.apache.fop.render.xml Package</TITLE>
 <BODY>
-<P>classes for rendering to XML for debugging</P>
+<P>Classes for rendering the Area Tree to XML (for debugging).</P>
 </BODY>
 </HTML>
\ No newline at end of file
diff --git a/src/overview.html b/src/overview.html
index af1f3c055..a83809de0 100644
--- a/src/overview.html
+++ b/src/overview.html
@@ -1,9 +1,48 @@
 <HTML>
 <TITLE>FOP Overview</TITLE>
 <BODY>
-<P>FOP is an XSL formatter and renderer that works with an XSLT transformer to
-produce PDF (and eventually other output formats) from XML documents.</P>
+<P>The main purpose of FOP is to render XSL-FO documents into a variety of
+output formats, including PDF, text, MIF, Postscript, and others. This process
+requires two conversions as the data moves through the following three
+stages:
+<OL>
+  <LI>XSL-FO document (input). This document should conform to the XSL
+    standard (currently version 1.0). It is a description of the general
+    formatting requirements of the document.</LI>
+  <LI>Area Tree document (intermediate). This document is a model of the
+    specific, paginated layout that fulfills the general requirements of the
+    input XSL-FO document, and conforms to the constraints of the XSL
+    standard. It is transitory.</LI>
+  <LI>Rendered document (output). This document implements a specific file
+    format to serialize the Area Tree document.</LI>
+</OL>
+
+<P>As a convenience to users, FOP can also manage the following ancillary
+processes:</P>
+
+<UL>
+  <LI> (upstream, external) conversion of a semantic XML document into an
+    XSL-FO document by invoking an XSLT transformation.</LI>
+  <LI> (downstream, internal) display of the modeled paginated document in
+    a viewer.</LI>
+</UL>
+
+<P>To get an overview of the FOP process, begin with the class
+<A HREF="org/apache/fop/apps/Driver.html">org.apache.fop.apps.Driver</A>.</P>
+
+<H3>Developer Information</H3>
+<UL>
+  <LI>The current development platform is Java 1.3. There are minor
+    source code changes required to compile with Java 1.4. See the <A
+    HREF="http://xml.apache.org/fop/relnotes.html" TARGET="_blank">Release
+    Notes</A> for details.</LI>
+  <LI>For javadoc documentation that references external standards (such as
+    the W3C XSL standard), such standards will be opened in a different
+    browser instance. Following additional references to the same standard
+    will update the same browser, but you will not see that update unless that
+    browser window is open on your desktop -- in other words, if that browser
+    is minimized, it will look like nothing happened.</LI>
+</UL>
 
-<P>To get an overview of the FOP process, begin with the class <A HREF="org/apache/fop/apps/Driver.html">org.apache.fop.apps.Driver</A>.</P>
 </BODY>
 </HTML>
\ No newline at end of file
-- 
2.39.5