**********************
* JFREEREPORT 0.8.3c *
**********************

19 Jun 2003

1. INTRODUCTION
---------------
JFreeReport is a free Java report library, distributed under the terms
of the GNU Lesser General Public License (see license-LGPL.txt for
details).  JFreeReport is developed by Thomas Morgner, David Gilbert
and others.

For the latest news and information about JFreeReport, please refer to:

    http://www.jfree.org/jfreereport/index.html


2. INSTALLATION
---------------
Detailed instructions for installing JFreeReport are provided in the
jfreechart-install.pdf file.  You can download this file from the
JFreeReport home page. 


3. OTHER LIBRARIES
------------------
JFreeReport uses several other open source libraries:

JCommon - http://www.jfree.org/jcommon/index.html
BeanShell - http://www.beanshell.org
GnuJAXP - http://www.gnu.org/software/classpathx/jaxp
iText - http://www.lowagie.com/iText
POI - http://jakarta.apache.org/poi


4. JAVADOC HTML PAGES
---------------------
The Javadoc HTML pages for JFreeReport are available on-line at the
JFreeReport home page.  You can also regenerate the Javadocs directly
from the source code.  There is a task in the Ant script (see below)
that makes this relatively simple.


5. EXTENDED XML DEFINITION REFERENCE DOCUMENTS
----------------------------------------------
The reference documents for the extended report definition format can
be found in the resources directory or can be generated by starting the
java class

  com.jrefinery.report.io.ext.ReferenceDocGenerator

The reference manual documents all currently defined StyleKeys and
the object definitions used in the stylekeys and when defining
templates or datasources.


6. SUPPORT
----------
Free support is available via the JFreeReport forum, follow the link
from the JFreeReport home page.  Please note that questions are
answered by volunteers, so there is no guaranteed response time or
level of service.

Please avoid e-mailing the developers directly for support questions.
If you post a message in the forum, then everyone can see the
question, and everyone can see the answer.


7. REPORTING BUGS
-----------------
If you find bugs in JFreeReport, we'd like to hear about it so that we
can improve future releases of JFreeReport.  Please post a bug report
at the JFreeReport project page on SourceForge:

    http://sourceforge.net/projects/jfreereport

Please be sure to provide as much information as you can.  We need to
know the version of JFreeReport that you are using, the JDK version,
and the steps required to replicate the bug.  Include any other
information that you think is relevant.


8. ANT
------
We use an open source build tool called Ant to build JFreeReport.  An
Ant script (tested using Ant 1.5.1) is included in the distribution:

    <jfreereport-directory>/ant/build.xml

You can find out more about Ant at:

    http://jakarta.apache.org/ant

Ant is licensed under the terms of the Apache Software License (a
popular open source software license).


9. CHECKSTYLE
-------------
We use a free utility called Checkstyle to apply a consistent coding
style to the JFreeReport source code.  You will find the Checkstyle
property settings in the following file:

    <jfreereport-directory>/checkstyle/properties.txt

You can find out more about Checkstyle at:

    http://checkstyle.sourceforge.net/

Checkstyle is licensed under the terms of the GNU LGPL.


10. TABLE-BASED OUTPUTTARGETS AND PLAINTEXT-OUTPUT
-------------------------------------------------

All table based output targets (HTML, Execl, Layouted CSV) have some
layout restrictions. These layout restrictions also apply to the
PlainText output target:

* The elements must be aligned properly, they must not overlap. When
  overlapping, the left element gets preferred over the right element,
  and top elements have a higher preferrence level as bottom elements.

* The elements must be large enough to contain the element. This is
  important when specifying the cell/line height, the elements height
  must be greater than the minimum height.

  For Excel/Html cells the minimum height is equal to the font height,
  so you'll just have to make sure that the cell is able to print at
  least one line of text.

  For PlainText, the line height is defined by the LPI setting, if LPI
  (lines per inch) is set to 10, then the minimum height of a line
  should be 72/10 points, so specifying a element height of 8 is safe.
  If LPI is set to 6, then the line height should be at least 72/6, so
  a element height of 12 should be ok.

* When specifying colors for the Excel target, then these colors are
  translated into one of the predefined excel color constants. This
  translation tries to find the nearest color, if that fails, the colors
  could look weird. Using one of the predefined AWT colors is always safe,
  everything else should work, but there are no guarantees.


11. DEFINING THE SELECTABLE ENCODINGS IN THE EXPORT DIALOGS
-----------------------------------------------------------
By default, the export dialogs make all defined string encodings available
in the encodings comboboxes. As the availability of all encodings is not
necessary for most deployment scenarios, we implemeted a way to customize
the available encodings.

The general availabilty can be defined by specifying the report configuration
key "com.jrefinery.report.encodings.available". If the key is set to "all", then
all supported encodings of the JDK are enabled and selectable. Setting the key
to "none" will disable the encodings completly, and only the report's defined
target encoding is visible and selectable.

If the configuration key is set to "file", then a encodings property file can
be specified with the configuration key "com.jrefinery.report.encodings.file".
The key should point to a properties file, which contains all selectable
encodings. A sample for such an property file can be found as resource
"/com/jrefinery/report/jfreereport-encodings.properties" in the library and the
sources.


12. "BUGGY FONTRENDERER CONTEXT" MESSAGE APPEARS IN THE LOGS
------------------------------------------------------------
A message like this one appears in the logs:

  DEBUG: This is a buggy version of the font-renderer context: false
  DEBUG: The buggy-value is defined in the configuration : false
  DEBUG: The G2OutputTarget uses Antialiasing.
  The FontRendererBugs should not be visible in TextAntiAliasing-Mode.
  If there are problems with the string-placement, please report your
  Operating System version and your JDK Version to www.object-refinery.com/jfreereport.

This is a debug message, so (as with every debug message) it may have
no meaning at all. But this one has .. :)

  DEBUG: This is a buggy version of the font-renderer context: true
  DEBUG: The G2OutputTarget uses Antialiasing.

means, that your AWT implementation behaves different when
fonts are rendered with aliasing enabled than it would do
without aliasing. Most Sun JDKs have this bug, which got
finally fixed in JDK >1.4.

The FontMetrics implementation is not correct, when Aliasing
is disabled (the computed font size is not the same as the
used space when printing the string). In that case, we just
use our own FontMetrics calculation methods, and it seems to
work...

But our method is not foolprof, as it is no standard
function, and it is possible, that our fix may not work on
other JDKs or may cause the layout be get even more weird.
So if your layout looks weird and text elements behave
strangely, then you should report your JDK version and
OperatingSystem to us. If everything looks fine, then ignore
the message ...

If this bug strikes you, you will see that non-left aligned texts
are printed on wrong positions, while left-aligned text does not
fully use the available space (or the oposite effect, that the field
does not obey to the defined limitations).


14. USING TRUETYPE FONTS
------------------------
Unix: If you want to use TrueType in Java, you will have to copy all
  needed TrueType fonts to the $JRE/lib/fonts directory. After copying
  the fonts, make sure that you update the font.dir file of that directory,
  so that the JRE can find these fonts.

  When JFreeReport is used to generate PDF files only, copying the files
  will not be necessary, iText uses the all fonts of the default font path
  without using AWT functionality.

  The PDF-Target will register all fonts found in the directory
  "/usr/X11R6/lib/X11/fonts" and all subdirectories. Additionally the directory
  "/usr/share/fonts" is searched for usable font files.

  See also: (This should also work for JDK 1.2.2)
  http://java.sun.com/j2se/1.3/docs/guide/intl/addingfonts.html#adding

MacOS: The iText library uses only TTF and Adobe font files to generate PDF
  files. If your system stores the fonts in the ResourceFork, Java may not be
  able to access them.

  You can use FONDU (http://fondu.sourceforge.net/) to convert the MacOS fonts
  into a usable format.

  Additionally the MacOS X font directories are searched in the following order:

  ~/Library/Fonts
  /Library/Fonts
  /Network/Library/Fonts
  /System/Library/Fonts

  Any TTF, AFM or PFB file found in these directories will be registered with
  iText and can be used to create PDF files.

Windows: The %WINDIR%/fonts directory is used to search and register the system
  fonts. The JDK uses all fonts that are available, no additional work is needed.


14. OTHER FEEDBACK
-----------------
For other feedback and comments, please post a message on the
JFreeReport forum.
