Fixed more style problems.

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

10 files changed, 282 insertions, 235 deletions

diff --git a/src/org/apache/fop/apps/AWTStarter.java b/src/org/apache/fop/apps/AWTStarter.java
index 961822e26..4394c3c9e 100644
--- a/src/org/apache/fop/apps/AWTStarter.java
+++ b/src/org/apache/fop/apps/AWTStarter.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -13,8 +13,8 @@ import org.apache.fop.viewer.PreviewDialog;
 import org.apache.fop.viewer.Translator;
 
 //Java
-import javax.swing.UIManager;
-import java.awt.*;
+import java.awt.Dimension;
+import java.awt.Toolkit;
 import java.awt.event.WindowAdapter;
 import java.awt.event.WindowEvent;
 import java.util.Locale;
@@ -36,7 +36,13 @@ public class AWTStarter extends CommandLineStarter {
     private Driver driver;
     private XMLReader parser;
 
-    public AWTStarter(CommandLineOptions commandLineOptions) throws FOPException {
+    /**
+     * Construct an AWTStarter
+     * @param commandLineOptions the parsed command line options
+     * @throws FOPException if anything goes wrong during initialization.
+     */
+    public AWTStarter(CommandLineOptions commandLineOptions)
+        throws FOPException {
         super(commandLineOptions);
         init();
     }
@@ -44,10 +50,11 @@ public class AWTStarter extends CommandLineStarter {
     private void init() throws FOPException {
         //Creates Translator according to the language
         String language = commandLineOptions.getLanguage();
-        if (language == null)
+        if (language == null) {
             translator = new Translator(Locale.getDefault());
-        else
+        } else {
             translator = new Translator(new Locale(language, ""));
+        }
         AWTRenderer renderer = new AWTRenderer(translator);
         frame = createPreviewDialog(renderer, translator);
         renderer.setComponent(frame);
@@ -61,6 +68,7 @@ public class AWTStarter extends CommandLineStarter {
 
     /**
      * Runs formatting.
+     * @throws FOPException FIXME should not happen.
      */
     public void run() throws FOPException {
         driver.reset();
diff --git a/src/org/apache/fop/apps/CommandLineOptions.java b/src/org/apache/fop/apps/CommandLineOptions.java
index 4297d2e56..33549034f 100644
--- a/src/org/apache/fop/apps/CommandLineOptions.java
+++ b/src/org/apache/fop/apps/CommandLineOptions.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -8,19 +8,13 @@
 package org.apache.fop.apps;
 
 // java
-import java.util.Vector;
 import java.io.File;
 import java.io.FileNotFoundException;
 
-// FOP
-import org.apache.fop.apps.FOPException;
-
 // Avalon
 import org.apache.avalon.framework.logger.ConsoleLogger;
 import org.apache.avalon.framework.logger.Logger;
 
-import java.io.*;
-
 /**
  * Options parses the commandline arguments
  */
@@ -54,32 +48,38 @@ public class CommandLineOptions {
     private static final int RTF_OUTPUT = 10;
 
     /* show configuration information */
-    Boolean dumpConfiguration = Boolean.FALSE;
+    private Boolean dumpConfiguration = Boolean.FALSE;
     /* suppress any progress information */
-    Boolean quiet = Boolean.FALSE;
+    private Boolean quiet = Boolean.FALSE;
     /* for area tree XML output, only down to block area level */
-    Boolean suppressLowLevelAreas = Boolean.FALSE;
+    private Boolean suppressLowLevelAreas = Boolean.FALSE;
     /* user configuration file */
-    File userConfigFile = null;
+    private File userConfigFile = null;
     /* input fo file */
-    File fofile = null;
+    private File fofile = null;
     /* xsltfile (xslt transformation as input) */
-    File xsltfile = null;
+    private File xsltfile = null;
     /* xml file (xslt transformation as input) */
-    File xmlfile = null;
+    private File xmlfile = null;
     /* output file */
-    File outfile = null;
+    private File outfile = null;
     /* input mode */
-    int inputmode = NOT_SET;
+    private int inputmode = NOT_SET;
     /* output mode */
-    int outputmode = NOT_SET;
+    private int outputmode = NOT_SET;
     /* language for user information */
-    String language = null;
+    private String language = null;
 
     private java.util.HashMap rendererOptions;
 
     private Logger log;
 
+    /**
+     * Construct a command line option object from command line arguments
+     * @param args command line parameters
+     * @throws FOPException for general errors
+     * @throws FileNotFoundException if an input file wasn't found.
+     */
     public CommandLineOptions(String[] args)
             throws FOPException, FileNotFoundException {
 
@@ -99,16 +99,19 @@ public class CommandLineOptions {
             printUsage();
             throw e;
         }
-
     }
 
+    /**
+     * Get the logger.
+     * @return the logger
+     */
     public Logger getLogger() {
         return log;
     }
 
     /**
      * parses the commandline arguments
-     * @return true if parse was successful and procesing can continue, false if processing should stop
+     * @return true if parse was successful and processing can continue, false if processing should stop
      * @exception FOPException if there was an error in the format of the options
      */
     private boolean parseOptions(String args[]) throws FOPException {
@@ -333,7 +336,8 @@ public class CommandLineOptions {
     }    // end checkSettings
 
     /**
-     * returns the chosen renderer, throws FOPException
+     * @return the type chosen renderer
+     * @throws FOPException for invalid output modes
      */
     public int getRenderer() throws FOPException {
         switch (outputmode) {
@@ -366,7 +370,8 @@ public class CommandLineOptions {
     }
 
     /**
-     *
+     * Get the input handler.
+     * @return the input handler
      */
     public InputHandler getInputHandler() {
         switch (inputmode) {
@@ -379,42 +384,39 @@ public class CommandLineOptions {
         }
     }
 
+    /**
+     * Get the renderer specific options.
+     * @return hash map with option/value pairs.
+     */
     public java.util.HashMap getRendererOptions() {
         return rendererOptions;
     }
 
+    /**
+     * Get the starter for the process.
+     * @return the starter.
+     */
     public Starter getStarter() throws FOPException {
         Starter starter = null;
         switch (outputmode) {
         case AWT_OUTPUT:
             try {
-                starter = ((Starter)Class.forName("org.apache.fop.apps.AWTStarter").getConstructor(new Class[] {
-                    CommandLineOptions.class
-                }).newInstance(new Object[] {
-                    this
-                }));
+                starter = new AWTStarter(this);
+            } catch (FOPException e) {
+                throw e;
             } catch (Exception e) {
-                if (e instanceof FOPException) {
-                    throw (FOPException)e;
-                }
                 throw new FOPException("AWTStarter could not be loaded.", e);
             }
-        break;
+            break;
         case PRINT_OUTPUT:
             try {
-                starter = ((Starter)Class.forName("org.apache.fop.apps.PrintStarter").getConstructor(new Class[] {
-                    CommandLineOptions.class
-                }).newInstance(new Object[] {
-                    this
-                }));
+                starter = new PrintStarter(this);
+            } catch (FOPException e) {
+                throw e;
             } catch (Exception e) {
-                if (e instanceof FOPException) {
-                    throw (FOPException)e;
-                }
-                throw new FOPException("PrintStarter could not be loaded.",
-                                       e);
+                throw new FOPException("PrintStarter could not be loaded.", e);
             }
-        break;
+            break;
         default:
             starter = new CommandLineStarter(this);
         }
@@ -467,7 +469,7 @@ public class CommandLineOptions {
     }
 
     /**
-     * return either the fofile or the xmlfile
+     * @return either the fofile or the xmlfile
      */
     public File getInputFile() {
         switch (inputmode) {
@@ -485,48 +487,48 @@ public class CommandLineOptions {
      */
     public static void printUsage() {
         System.err.println("\nUSAGE\nFop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-pcl|-ps|-txt|-at|-print] <outfile>\n"
-                               + " [OPTIONS]  \n"
-                               + "  -d          debug mode   \n"
-                               + "  -x          dump configuration settings  \n"
-                               + "  -q          quiet mode  \n"
-                               + "  -c cfg.xml  use additional configuration file cfg.xml\n"
-                               + "  -l lang     the language to use for user information \n"
-                               + "  -s          for area tree XML, down to block areas only\n\n"
-                               + " [INPUT]  \n"
-                               + "  infile            xsl:fo input file (the same as the next) \n"
-                               + "  -fo  infile       xsl:fo input file  \n"
-                               + "  -xml infile       xml input file, must be used together with -xsl \n"
-                               + "  -xsl stylesheet   xslt stylesheet \n \n"
-                               + " [OUTPUT] \n"
-                               + "  outfile           input will be rendered as pdf file into outfile \n"
-                               + "  -pdf outfile      input will be rendered as pdf file (outfile req'd) \n"
-                               + "  -awt              input will be displayed on screen \n"
-                               + "  -mif outfile      input will be rendered as mif file (outfile req'd)\n"
-                               + "  -rtf outfile      input will be rendered as rtf file (outfile req'd)\n"
-                               + "  -pcl outfile      input will be rendered as pcl file (outfile req'd) \n"
-                               + "  -ps outfile       input will be rendered as PostScript file (outfile req'd) \n"
-                               + "  -txt outfile      input will be rendered as text file (outfile req'd) \n"
-                               + "  -svg outfile      input will be rendered as an svg slides file (outfile req'd) \n"
-                               + "  -at outfile       representation of area tree as XML (outfile req'd) \n"
-                               + "  -print            input file will be rendered and sent to the printer \n"
-                               + "                    see options with \"-print help\" \n\n"
-                               + " [Examples]\n" + "  Fop foo.fo foo.pdf \n"
-                               + "  Fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)\n"
-                               + "  Fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf\n"
-                               + "  Fop foo.fo -mif foo.mif\n"
-                               + "  Fop foo.fo -rtf foo.rtf\n"
-                               + "  Fop foo.fo -print or Fop -print foo.fo \n"
-                               + "  Fop foo.fo -awt \n");
+                           + " [OPTIONS]  \n"
+                           + "  -d          debug mode   \n"
+                           + "  -x          dump configuration settings  \n"
+                           + "  -q          quiet mode  \n"
+                           + "  -c cfg.xml  use additional configuration file cfg.xml\n"
+                           + "  -l lang     the language to use for user information \n"
+                           + "  -s          for area tree XML, down to block areas only\n\n"
+                           + " [INPUT]  \n"
+                           + "  infile            xsl:fo input file (the same as the next) \n"
+                           + "  -fo  infile       xsl:fo input file  \n"
+                           + "  -xml infile       xml input file, must be used together with -xsl \n"
+                           + "  -xsl stylesheet   xslt stylesheet \n \n"
+                           + " [OUTPUT] \n"
+                           + "  outfile           input will be rendered as pdf file into outfile \n"
+                           + "  -pdf outfile      input will be rendered as pdf file (outfile req'd) \n"
+                           + "  -awt              input will be displayed on screen \n"
+                           + "  -mif outfile      input will be rendered as mif file (outfile req'd)\n"
+                           + "  -rtf outfile      input will be rendered as rtf file (outfile req'd)\n"
+                           + "  -pcl outfile      input will be rendered as pcl file (outfile req'd) \n"
+                           + "  -ps outfile       input will be rendered as PostScript file (outfile req'd) \n"
+                           + "  -txt outfile      input will be rendered as text file (outfile req'd) \n"
+                           + "  -svg outfile      input will be rendered as an svg slides file (outfile req'd) \n"
+                           + "  -at outfile       representation of area tree as XML (outfile req'd) \n"
+                           + "  -print            input file will be rendered and sent to the printer \n"
+                           + "                    see options with \"-print help\" \n\n"
+                           + " [Examples]\n" + "  Fop foo.fo foo.pdf \n"
+                           + "  Fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)\n"
+                           + "  Fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf\n"
+                           + "  Fop foo.fo -mif foo.mif\n"
+                           + "  Fop foo.fo -rtf foo.rtf\n"
+                           + "  Fop foo.fo -print or Fop -print foo.fo \n"
+                           + "  Fop foo.fo -awt \n");
     }
-
+    
     /**
      * shows the options for print output
      */
     public void printUsagePrintOutput() {
         System.err.println("USAGE: -print [-Dstart=i] [-Dend=i] [-Dcopies=i] [-Deven=true|false] "
-                               + " org.apache.fop.apps.Fop (..) -print \n"
-                               + "Example:\n"
-                               + "java -Dstart=1 -Dend=2 org.apache.Fop.apps.Fop infile.fo -print ");
+                           + " org.apache.fop.apps.Fop (..) -print \n"
+                           + "Example:\n"
+                           + "java -Dstart=1 -Dend=2 org.apache.Fop.apps.Fop infile.fo -print ");
     }
 
 
@@ -623,21 +625,5 @@ public class CommandLineOptions {
 
     }
 
-    // debug: create class and output all settings
-    public static void main(String args[]) {
-        /*
-         * for (int i = 0; i < args.length; i++) {
-         * log.debug(">"+args[i]+"<");
-         * }
-         */
-        try {
-            CommandLineOptions options = new CommandLineOptions(args);
-        } catch (Exception e) {
-            e.printStackTrace();
-        }
-
-        // options.debug();
-    }
-
 }
 
diff --git a/src/org/apache/fop/apps/CommandLineStarter.java b/src/org/apache/fop/apps/CommandLineStarter.java
index 46cd0cf36..744d54005 100644
--- a/src/org/apache/fop/apps/CommandLineStarter.java
+++ b/src/org/apache/fop/apps/CommandLineStarter.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -9,13 +9,10 @@ package org.apache.fop.apps;
 
 // SAX
 import org.xml.sax.XMLReader;
-import org.xml.sax.InputSource;
-import org.xml.sax.SAXException;
-import org.xml.sax.SAXParseException;
 
 // Java
-import java.io.*;
-import java.net.URL;
+import java.io.BufferedOutputStream;
+import java.io.FileOutputStream;
 
 
 /**
@@ -25,7 +22,7 @@ import java.net.URL;
  */
 public class CommandLineStarter extends Starter {
 
-    CommandLineOptions commandLineOptions;
+    protected CommandLineOptions commandLineOptions;
 
     public CommandLineStarter(CommandLineOptions commandLineOptions)
     throws FOPException {
@@ -54,7 +51,7 @@ public class CommandLineStarter extends Starter {
             BufferedOutputStream bos = new BufferedOutputStream(new FileOutputStream(
                                       commandLineOptions.getOutputFile()));
             driver.setOutputStream(bos);
-            if(driver.getRenderer() != null) {
+            if (driver.getRenderer() != null) {
                 driver.getRenderer().setOptions(
               commandLineOptions.getRendererOptions());
             }
diff --git a/src/org/apache/fop/apps/Driver.java b/src/org/apache/fop/apps/Driver.java
index ad50a33d4..fd980ed8a 100644
--- a/src/org/apache/fop/apps/Driver.java
+++ b/src/org/apache/fop/apps/Driver.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -8,37 +8,39 @@
 package org.apache.fop.apps;
 
 // FOP
-import org.apache.fop.fo.FOUserAgent;
-import org.apache.fop.fo.FOTreeBuilder;
 import org.apache.fop.fo.ElementMapping;
+import org.apache.fop.fo.FOTreeBuilder;
+import org.apache.fop.fo.FOUserAgent;
 import org.apache.fop.render.Renderer;
 import org.apache.fop.tools.DocumentInputSource;
 import org.apache.fop.tools.DocumentReader;
 
-import org.apache.fop.render.pdf.PDFRenderer;
 
 // Avalon
 import org.apache.avalon.framework.logger.ConsoleLogger;
-import org.apache.avalon.framework.logger.Logger;
 import org.apache.avalon.framework.logger.LogEnabled;
-import org.apache.avalon.framework.logger.AbstractLogEnabled;
+import org.apache.avalon.framework.logger.Logger;
 
 // DOM
 import org.w3c.dom.Document;
-import org.w3c.dom.Node;
-import org.w3c.dom.NamedNodeMap;
-import org.w3c.dom.Attr;
 
 // SAX
 import org.xml.sax.ContentHandler;
 import org.xml.sax.InputSource;
-import org.xml.sax.XMLReader;
 import org.xml.sax.SAXException;
-import org.xml.sax.helpers.AttributesImpl;
+import org.xml.sax.XMLReader;
+import javax.xml.parsers.ParserConfigurationException;
 
 // Java
-import java.io.*;
-import java.util.*;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
+import java.io.Reader;
+import java.util.Enumeration;
+import java.util.Hashtable;
+import java.util.Vector;
 
 /**
  * Primary class that drives overall FOP process.
@@ -142,17 +144,17 @@ public class Driver implements LogEnabled {
     /**
      * the FO tree builder
      */
-    private FOTreeBuilder _treeBuilder;
+    private FOTreeBuilder treeBuilder;
 
     /**
      * the renderer type code given by setRenderer
      */
-    private int _rendererType;
+    private int rendererType;
 
     /**
      * the renderer to use to output the area tree
      */
-    private Renderer _renderer;
+    private Renderer renderer;
 
     /**
      * the structure handler
@@ -162,17 +164,17 @@ public class Driver implements LogEnabled {
     /**
      * the source of the FO file
      */
-    private InputSource _source;
+    private InputSource source;
 
     /**
      * the stream to use to output the results of the renderer
      */
-    private OutputStream _stream;
+    private OutputStream stream;
 
     /**
      * The XML parser to use when building the FO tree
      */
-    private XMLReader _reader;
+    private XMLReader reader;
 
     /**
      * the system resources that FOP will use
@@ -182,7 +184,8 @@ public class Driver implements LogEnabled {
 
     public static final String getParserClassName() {
         try {
-            return javax.xml.parsers.SAXParserFactory.newInstance().newSAXParser().getXMLReader().getClass().getName();
+            return javax.xml.parsers.SAXParserFactory.newInstance()
+                .newSAXParser().getXMLReader().getClass().getName();
         } catch (javax.xml.parsers.ParserConfigurationException e) {
             return null;
         } catch (org.xml.sax.SAXException e) {
@@ -194,19 +197,19 @@ public class Driver implements LogEnabled {
      * create a new Driver
      */
     public Driver() {
-        _stream = null;
+        stream = null;
     }
 
     public Driver(InputSource source, OutputStream stream) {
         this();
-        _source = source;
-        _stream = stream;
+        this.source = source;
+        this.stream = stream;
     }
 
     public void initialize() {
-        _stream = null;
-        _treeBuilder = new FOTreeBuilder();
-        _treeBuilder.setUserAgent(getUserAgent());
+        stream = null;
+        treeBuilder = new FOTreeBuilder();
+        treeBuilder.setUserAgent(getUserAgent());
         setupDefaultMappings();
     }
 
@@ -218,7 +221,7 @@ public class Driver implements LogEnabled {
         if (userAgent == null) {
             userAgent = new FOUserAgent();
             userAgent.enableLogging(getLogger());
-            userAgent.setBaseURL("file:/.");
+            userAgent.setBaseURL("");
         }
         return userAgent;
     }
@@ -247,14 +250,14 @@ public class Driver implements LogEnabled {
      * The output stream is cleared. The renderer is cleared.
      */
     public synchronized void reset() {
-        _source = null;
-        _stream = null;
-        _reader = null;
-        _treeBuilder.reset();
+        source = null;
+        stream = null;
+        reader = null;
+        treeBuilder.reset();
     }
 
     public boolean hasData() {
-        return (_treeBuilder.hasData());
+        return (treeBuilder.hasData());
     }
 
     /**
@@ -264,7 +267,7 @@ public class Driver implements LogEnabled {
      *
      */
     public void setOutputStream(OutputStream stream) {
-        _stream = stream;
+        this.stream = stream;
     }
 
     /**
@@ -273,15 +276,16 @@ public class Driver implements LogEnabled {
      * @see DocumentInputSource
      */
     public void setInputSource(InputSource source) {
-        _source = source;
+        this.source = source;
     }
 
     /**
      * Sets the reader used when reading in the source. If not set,
      * this defaults to a basic SAX parser.
+     * @param reader the reader to use.
      */
     public void setXMLReader(XMLReader reader) {
-        _reader = reader;
+        this.reader = reader;
     }
 
     /**
@@ -301,29 +305,31 @@ public class Driver implements LogEnabled {
                 String str = (String)providers.nextElement();
                 try {
                     addElementMapping(str);
-                } catch (IllegalArgumentException e) {}
+                } catch (IllegalArgumentException e) {
+                }
 
             }
         }
     }
 
     /**
-     * Set the rendering type to use. Must be one of
+     * Shortcut to set the rendering type to use. Must be one of
      * <ul>
-     * <li>RENDER_PDF
-     * <li>RENDER_AWT
-     * <li>RENDER_MIF
-     * <li>RENDER_XML
-     * <li>RENDER_PCL
-     * <li>RENDER_PS
-     * <li>RENDER_TXT
-     * <li>RENDER_SVG
-     * <li>RENDER_RTF
+     * <li>RENDER_PDF</li>
+     * <li>RENDER_AWT</li>
+     * <li>RENDER_MIF</li>
+     * <li>RENDER_XML</li>
+     * <li>RENDER_PCL</li>
+     * <li>RENDER_PS</li>
+     * <li>RENDER_TXT</li>
+     * <li>RENDER_SVG</li>
+     * <li>RENDER_RTF</li>
      * </ul>
      * @param renderer the type of renderer to use
+     * @throws IllegalArgumentException if an unsupported renderer type was required.
      */
     public void setRenderer(int renderer) throws IllegalArgumentException {
-        _rendererType = renderer;
+        rendererType = renderer;
         switch (renderer) {
         case RENDER_PDF:
             setRenderer("org.apache.fop.render.pdf.PDFRenderer");
@@ -364,15 +370,15 @@ public class Driver implements LogEnabled {
      */
     public void setRenderer(Renderer renderer) {
         renderer.setUserAgent(getUserAgent());
-        _renderer = renderer;
+        this.renderer = renderer;
     }
 
     public Renderer getRenderer() {
-        return _renderer;
+        return renderer;
     }
 
     /**
-     * @deprecated use renderer.setProducer(version) + setRenderer(renderer) or just setRenderer(renderer_type) which will use the default producer string.
+     * @deprecated use renderer.setProducer(version) + setRenderer(renderer) or just setRenderer(rendererType) which will use the default producer string.
      * @see #setRenderer(int)
      * @see #setRenderer(Renderer)
      */
@@ -391,26 +397,23 @@ public class Driver implements LogEnabled {
     public void setRenderer(String rendererClassName)
     throws IllegalArgumentException {
         try {
-            _renderer =
+            renderer =
                 (Renderer)Class.forName(rendererClassName).newInstance();
-            if (_renderer instanceof LogEnabled) {
-                ((LogEnabled)_renderer).enableLogging(getLogger());
+            if (renderer instanceof LogEnabled) {
+                ((LogEnabled)renderer).enableLogging(getLogger());
             }
-            _renderer.setProducer(Version.getVersion());
-            _renderer.setUserAgent(getUserAgent());
+            renderer.setProducer(Version.getVersion());
+            renderer.setUserAgent(getUserAgent());
         } catch (ClassNotFoundException e) {
             throw new IllegalArgumentException("Could not find "
                                                + rendererClassName);
-        }
-        catch (InstantiationException e) {
+        } catch (InstantiationException e) {
             throw new IllegalArgumentException("Could not instantiate "
                                                + rendererClassName);
-        }
-        catch (IllegalAccessException e) {
+        } catch (IllegalAccessException e) {
             throw new IllegalArgumentException("Could not access "
                                                + rendererClassName);
-        }
-        catch (ClassCastException e) {
+        } catch (ClassCastException e) {
             throw new IllegalArgumentException(rendererClassName
                                                + " is not a renderer");
         }
@@ -423,14 +426,16 @@ public class Driver implements LogEnabled {
      * @param mapping the element mappingto add
      */
     public void addElementMapping(ElementMapping mapping) {
-        mapping.addToBuilder(_treeBuilder);
+        mapping.addToBuilder(treeBuilder);
     }
 
     /**
-     * add the element mapping with the given class name
+     * Add the element mapping with the given class name.
+     * @param the class name representing the element mapping.
+     * @throws IllegalArgumentException if there was not such element mapping.
      */
     public void addElementMapping(String mappingClassName)
-    throws IllegalArgumentException {
+        throws IllegalArgumentException {
         try {
             ElementMapping mapping =
                 (ElementMapping)Class.forName(mappingClassName).newInstance();
@@ -438,16 +443,13 @@ public class Driver implements LogEnabled {
         } catch (ClassNotFoundException e) {
             throw new IllegalArgumentException("Could not find "
                                                + mappingClassName);
-        }
-        catch (InstantiationException e) {
+        } catch (InstantiationException e) {
             throw new IllegalArgumentException("Could not instantiate "
                                                + mappingClassName);
-        }
-        catch (IllegalAccessException e) {
+        } catch (IllegalAccessException e) {
             throw new IllegalArgumentException("Could not access "
                                                + mappingClassName);
-        }
-        catch (ClassCastException e) {
+        } catch (ClassCastException e) {
             throw new IllegalArgumentException(mappingClassName
                                                + " is not an ElementMapping");
         }
@@ -459,62 +461,73 @@ public class Driver implements LogEnabled {
      * Used in situations where SAX is used but not via a FOP-invoked
      * SAX parser. A good example is an XSLT engine that fires SAX
      * events but isn't a SAX Parser itself.
+     * @return a content handler for handling the SAX events.
      */
     public ContentHandler getContentHandler() {
         // TODO - do this stuff in a better way
-        if(_rendererType == RENDER_MIF) {
-            structHandler = new org.apache.fop.mif.MIFHandler(_stream);
-        } else if(_rendererType == RENDER_RTF) {
-            structHandler = new org.apache.fop.rtf.renderer.RTFHandler(_stream);
+        // PIJ: I guess the structure handler should be created by the renderer.
+        if (rendererType == RENDER_MIF) {
+            structHandler = new org.apache.fop.mif.MIFHandler(stream);
+        } else if (rendererType == RENDER_RTF) {
+            structHandler = new org.apache.fop.rtf.renderer.RTFHandler(stream);
         } else {
-            if (_renderer == null) throw new Error("_renderer not set when using standard structHandler");
-            structHandler = new LayoutHandler(_stream, _renderer, true);
+            if (renderer == null) {
+                throw new Error("Renderer not set when using standard structHandler");
+            }
+            structHandler = new LayoutHandler(stream, renderer, true);
         }
 
         structHandler.enableLogging(getLogger());
 
-        _treeBuilder.setUserAgent(getUserAgent());
-        _treeBuilder.setStructHandler(structHandler);
+        treeBuilder.setUserAgent(getUserAgent());
+        treeBuilder.setStructHandler(structHandler);
 
-        return _treeBuilder;
+        return treeBuilder;
     }
 
     /**
-     * Build the formatting object tree using the given SAX Parser and
-     * SAX InputSource
+     * Render the FO document read by a SAX Parser from an InputSource.
+     * @param parser the SAX parser.
+     * @param source the input source the parser reads from.
+     * @throws FOPException if anything goes wrong.
      */
     public synchronized void render(XMLReader parser, InputSource source)
-    throws FOPException {
+        throws FOPException {
         parser.setContentHandler(getContentHandler());
         try {
             parser.parse(source);
         } catch (SAXException e) {
             if (e.getException() instanceof FOPException) {
+                // Undo exception tunneling.
                 throw (FOPException)e.getException();
             } else {
                 throw new FOPException(e);
             }
-        }
-        catch (IOException e) {
+        } catch (IOException e) {
             throw new FOPException(e);
         }
     }
 
     /**
-     * Build the formatting object tree using the given DOM Document
+     * Render the FO ducument represented by a DOM Document.
+     * @param document the DOM document to read from
+     * @throws FOPException if anything goes wrong.
      */
     public synchronized void render(Document document)
-    throws FOPException {
-
+        throws FOPException {
         try {
             DocumentInputSource source = new DocumentInputSource(document);
             DocumentReader reader = new DocumentReader();
             reader.setContentHandler(getContentHandler());
             reader.parse(source);
         } catch (SAXException e) {
-            throw new FOPException(e);
-        }
-        catch (IOException e) {
+            if (e.getException() instanceof FOPException) {
+                // Undo exception tunneling.
+                throw (FOPException)e.getException();
+            } else {
+                throw new FOPException(e);
+            }
+        } catch (IOException e) {
             throw new FOPException(e);
         }
 
@@ -522,31 +535,40 @@ public class Driver implements LogEnabled {
 
     /**
      * Runs the formatting and renderering process using the previously set
-     * inputsource and outputstream
-     */
-    public synchronized void run() throws IOException, FOPException {
-        if (_renderer == null) {
+     * parser, input source, renderer and output stream.
+     * If the renderer was not set, default to PDF.
+     * If no parser was set, and the input source is not a dom document,
+     * get a default SAX parser.
+     * @throws IOException in case of IO errors.
+     * @throws FOPException if anything else goes wrong.
+     */
+    public synchronized void run()
+        throws IOException, FOPException {
+        if (renderer == null) {
             setRenderer(RENDER_PDF);
         }
 
-        if (_source == null) {
+        if (source == null) {
             throw new FOPException("InputSource is not set.");
         }
 
-        if (_reader == null) {
-            if (!(_source instanceof DocumentInputSource)) {
+        if (reader == null) {
+            if (!(source instanceof DocumentInputSource)) {
                 try {
-                _reader = javax.xml.parsers.SAXParserFactory.newInstance().newSAXParser().getXMLReader();
-                } catch(Exception e) {
+                    reader = javax.xml.parsers.SAXParserFactory.newInstance()
+                        .newSAXParser().getXMLReader();
+                } catch (SAXException e) {
+                    throw new FOPException(e);
+                } catch (ParserConfigurationException e) {
                     throw new FOPException(e);
                 }
             }
         }
 
-        if (_source instanceof DocumentInputSource) {
-            render(((DocumentInputSource)_source).getDocument());
+        if (source instanceof DocumentInputSource) {
+            render(((DocumentInputSource)source).getDocument());
         } else {
-            render(_reader, _source);
+            render(reader, source);
         }
     }
 
@@ -561,7 +583,7 @@ public class Driver implements LogEnabled {
  */
 class Service {
 
-    static Hashtable providerMap = new Hashtable();
+    static private Hashtable providerMap = new Hashtable();
 
     public static synchronized Enumeration providers(Class cls) {
         ClassLoader cl = cls.getClassLoader();
diff --git a/src/org/apache/fop/apps/ErrorHandler.java b/src/org/apache/fop/apps/ErrorHandler.java
index d559c9357..b9428744a 100644
--- a/src/org/apache/fop/apps/ErrorHandler.java
+++ b/src/org/apache/fop/apps/ErrorHandler.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -10,4 +10,5 @@ package org.apache.fop.apps;
 /**
  * not implemented yet
  */
-public interface ErrorHandler {}
+public interface ErrorHandler {
+}
diff --git a/src/org/apache/fop/apps/FOInputHandler.java b/src/org/apache/fop/apps/FOInputHandler.java
index 7a98b23a0..4af404ef8 100644
--- a/src/org/apache/fop/apps/FOInputHandler.java
+++ b/src/org/apache/fop/apps/FOInputHandler.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001-2002 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
@@ -19,17 +19,29 @@ import java.net.URL;
  * Manages input if it is an xsl:fo file
  */
 public class FOInputHandler extends InputHandler {
-    File fofile = null;
-    URL foURL = null;
+    private File fofile = null;
+    private URL foURL = null;
 
+    /*
+     * Create a FOInputHandler for a file.
+     * @param file the file to read the FO document.
+     */
     public FOInputHandler (File fofile) {
         this.fofile = fofile;
     }
 
+    /*
+     * Create a FOInputHandler for an URL.
+     * @param file the URL to read the FO document.
+     */
     public FOInputHandler (URL url) {
         this.foURL = url;
     }
 
+    
+    /*
+     * Get the input source associated with this input handler.
+     */
     public InputSource getInputSource () {
         if (fofile != null) {
             return super.fileInputSource(fofile);
@@ -37,6 +49,9 @@ public class FOInputHandler extends InputHandler {
         return super.urlInputSource(foURL);
     }
 
+    /*
+     * Get the SAX parser associated with this input handler.
+     */
     public XMLReader getParser() throws FOPException {
         return super.createParser();
     }
diff --git a/src/org/apache/fop/apps/FOPException.java b/src/org/apache/fop/apps/FOPException.java
index 1e1e9e8a4..0a377d652 100644
--- a/src/org/apache/fop/apps/FOPException.java
+++ b/src/org/apache/fop/apps/FOPException.java
@@ -1,6 +1,6 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources."
  */
@@ -17,7 +17,7 @@ public class FOPException extends Exception {
 
     private static final String EXCEPTION_SEPARATOR = "\n---------\n";
 
-    private Throwable _exception;
+    private Throwable exception;
 
     /**
      * create a new FOP Exception
@@ -39,15 +39,15 @@ public class FOPException extends Exception {
     }
 
     protected void setException(Throwable t) {
-        _exception = t;
+        exception = t;
     }
 
     public Throwable getException() {
-        return _exception;
+        return exception;
     }
 
     protected Throwable getRootException() {
-        Throwable result = _exception;
+        Throwable result = exception;
 
         if (result instanceof SAXException) {
             result = ((SAXException)result).getException();
@@ -56,7 +56,7 @@ public class FOPException extends Exception {
             result =
                 ((java.lang.reflect.InvocationTargetException)result).getTargetException();
         }
-        if (result != _exception) {
+        if (result != exception) {
             return result;
         }
         return null;
@@ -66,9 +66,9 @@ public class FOPException extends Exception {
     public void printStackTrace() {
         synchronized (System.err) {
             super.printStackTrace();
-            if (_exception != null) {
+            if (exception != null) {
                 System.err.println(EXCEPTION_SEPARATOR);
-                _exception.printStackTrace();
+                exception.printStackTrace();
             }
             if (getRootException() != null) {
                 System.err.println(EXCEPTION_SEPARATOR);
@@ -80,9 +80,9 @@ public class FOPException extends Exception {
     public void printStackTrace(java.io.PrintStream stream) {
         synchronized (stream) {
             super.printStackTrace(stream);
-            if (_exception != null) {
+            if (exception != null) {
                 stream.println(EXCEPTION_SEPARATOR);
-                _exception.printStackTrace(stream);
+                exception.printStackTrace(stream);
             }
             if (getRootException() != null) {
                 stream.println(EXCEPTION_SEPARATOR);
@@ -94,9 +94,9 @@ public class FOPException extends Exception {
     public void printStackTrace(java.io.PrintWriter writer) {
         synchronized (writer) {
             super.printStackTrace(writer);
-            if (_exception != null) {
+            if (exception != null) {
                 writer.println(EXCEPTION_SEPARATOR);
-                _exception.printStackTrace(writer);
+                exception.printStackTrace(writer);
             }
             if (getRootException() != null) {
                 writer.println(EXCEPTION_SEPARATOR);
diff --git a/src/org/apache/fop/apps/Fop.java b/src/org/apache/fop/apps/Fop.java
index 91399e53a..2342555f7 100644
--- a/src/org/apache/fop/apps/Fop.java
+++ b/src/org/apache/fop/apps/Fop.java
@@ -1,13 +1,21 @@
 /*
  * $Id$
- * Copyright (C) 2001 The Apache Software Foundation. All rights reserved.
+ * Copyright (C) 2001-2003 The Apache Software Foundation. All rights reserved.
  * For details on use and redistribution please refer to the
  * LICENSE file included with these sources.
  */
 
 package org.apache.fop.apps;
 
+/*
+ * The main application class for the FOP command line interface (CLI).
+ */
 public class Fop {
+
+    /*
+     * The main routine for the command line interface
+     * @param args the command line parameters
+     */
     public static void main(String[] args) {
         CommandLineOptions options = null;
 
@@ -16,7 +24,7 @@ public class Fop {
             Starter starter = options.getStarter();
             starter.run();
         } catch (FOPException e) {
-            if("null".equals("" + e.getMessage())) {
+            if (e.getMessage()==null) {
                 System.err.println("Exception occured with a null error message");
             } else {
                 System.err.println("" + e.getMessage());
diff --git a/src/org/apache/fop/apps/InputHandler.java b/src/org/apache/fop/apps/InputHandler.java
index 8c0bed8b2..ff82b781a 100644
--- a/src/org/apache/fop/apps/InputHandler.java
+++ b/src/org/apache/fop/apps/InputHandler.java
@@ -18,6 +18,11 @@ import javax.xml.parsers.ParserConfigurationException;
 import java.net.URL;
 import java.io.File;
 
+/*
+ * Abstract super class for input handlers.
+ * Should be used to abstract the various possibilities on how input
+ * can be provided to FOP (but actually isn't).
+ */
 public abstract class InputHandler {
 
     public abstract InputSource getInputSource();
@@ -53,6 +58,7 @@ public abstract class InputHandler {
      * Creates <code>XMLReader</code> object using default
      * <code>SAXParserFactory</code>
      * @return the created <code>XMLReader</code>
+     * @throws FOPException if the parser couldn't be created or configured for proper operation.
      */
     protected static XMLReader createParser() throws FOPException {
         try {
diff --git a/src/org/apache/fop/apps/LayoutHandler.java b/src/org/apache/fop/apps/LayoutHandler.java
index 523fef946..3e5e67b00 100644
--- a/src/org/apache/fop/apps/LayoutHandler.java
+++ b/src/org/apache/fop/apps/LayoutHandler.java
@@ -8,19 +8,23 @@
 package org.apache.fop.apps;
 
 // Java
-import java.io.OutputStream;
 import java.io.IOException;
+import java.io.OutputStream;
 import java.util.List;
 
 // SAX
 import org.xml.sax.SAXException;
 
 // FOP
+import org.apache.fop.area.AreaTree;
+import org.apache.fop.area.AreaTreeModel;
+import org.apache.fop.area.StorePagesModel;
+import org.apache.fop.area.Title;
+import org.apache.fop.area.TreeExt;
+import org.apache.fop.fo.pagination.LayoutMasterSet;
+import org.apache.fop.fo.pagination.PageSequence;
 import org.apache.fop.layout.FontInfo;
-import org.apache.fop.area.*;
 import org.apache.fop.render.Renderer;
-import org.apache.fop.fo.pagination.PageSequence;
-import org.apache.fop.fo.pagination.LayoutMasterSet;
 
 /**
  * Layout handler that receives the structure events.