Merged revisions 654111,654121,654190,654314,654322-654323,654338,654347,654437,654461,654528,654557 via svnmerge from

https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk

........
  r654111 | adelmelle | 2008-05-07 15:04:17 +0100 (Wed, 07 May 2008) | 6 lines
  
  Bugzilla 41500:
  Fixed a ClassCastException when fo:wrapper was used as a child of an fo:block-container.
  Bugzilla 42423:
  Added support for the "id" attribute on fo:wrappers that are children of the fo:flow.
........
  r654121 | adelmelle | 2008-05-07 15:19:13 +0100 (Wed, 07 May 2008) | 1 line
  
  Small correction: use appropriate value for 'context'
........
  r654190 | adelmelle | 2008-05-07 18:41:07 +0100 (Wed, 07 May 2008) | 1 line
  
  Added comment
........
  r654314 | adelmelle | 2008-05-07 23:45:46 +0100 (Wed, 07 May 2008) | 1 line
  
  Corrected errors in ColumnNumberPropertyMaker.java; temporarily disabled two testcases for a non-standard feature
........
  r654322 | acumiskey | 2008-05-08 00:27:45 +0100 (Thu, 08 May 2008) | 1 line
  
  Looks like the serialVersionUID got bumped but the log statement wasn't being completely honest about what it was doing.  FontCache now attempts to delete its cache file so subsequent runs should repopulate it.
........
  r654323 | acumiskey | 2008-05-08 00:29:04 +0100 (Thu, 08 May 2008) | 1 line
  
  Whoops.. small checkstyle nit :)
........
  r654338 | adelmelle | 2008-05-08 01:18:14 +0100 (Thu, 08 May 2008) | 1 line
  
  Removed inadvertently added override [Avoid late night commits...]
........
  r654347 | acumiskey | 2008-05-08 01:33:21 +0100 (Thu, 08 May 2008) | 1 line
  
  Removed tabs.  Checkstyle now configured.  Late nights..  and a new machine build.. :S
........
  r654437 | jeremias | 2008-05-08 08:32:02 +0100 (Thu, 08 May 2008) | 1 line
  
  Checkstyle fix.
........
  r654461 | jeremias | 2008-05-08 10:55:55 +0100 (Thu, 08 May 2008) | 5 lines
  
  Added support for font referencing for auto-detected fonts.
  Referenced TrueType fonts can now use glyphs outside the WinAnsi charset (Same approach as for extended glyph support with Type 1 fonts).
  
  Removed FopFactory reference from FontManager to make the class more useful outside this context (ex. transcoders).
  Updated fonts documentation with information that TTCs are now supported through auto-detection.
........
  r654528 | adelmelle | 2008-05-08 14:56:14 +0100 (Thu, 08 May 2008) | 5 lines
  
  Tweak:
  -> add 'runtimeType' member and toString() to PropertyCache to facilitate debugging
  -> modify the initial assignment in the related Property types accordingly
........
  r654557 | pietsch | 2008-05-08 16:36:02 +0100 (Thu, 08 May 2008) | 1 line
  
  Quick fix for XML validation error
........


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

1 files changed, 52 insertions, 18 deletions

diff --git a/src/documentation/content/xdocs/trunk/fonts.xml b/src/documentation/content/xdocs/trunk/fonts.xml
index eb466ec73..30b72ffac 100644
--- a/src/documentation/content/xdocs/trunk/fonts.xml
+++ b/src/documentation/content/xdocs/trunk/fonts.xml
@@ -177,10 +177,8 @@
         if you wanted to add a custom font. This unconvenient step has been removed and in
         addition to that, FOP supports auto-registration of fonts, i.e. FOP can find fonts
         installed in your operating system or can scan user-specified directories for fonts.
-        Font registration via XML font metrics file is still supported and is still necessary
-        if you want to use a TrueType Collection (*.ttc). Direct support for TrueType
-        collections may be added later. Furthermore, the XML font metrics files are still
-        required if you don't want to embed, but only reference a font.
+        Font registration via XML font metrics file is still supported and may still be necessary
+        for some very special cases as fallback variant while we stabilize font auto-detection.
       </p>
       <p>
         Basic information about fonts can be found at:
@@ -375,20 +373,56 @@
       </section>
       <section id="embedding">
         <title>Embedding</title>
-        <note>The PostScript renderer does not yet support TrueType fonts, but can embed Type 1 fonts.</note>
-        <note>The font is simply embedded into the PDF file, it is not converted.</note>
-        <p>Font embedding is enabled in the userconfig.xml file and controlled by the embed-url attribute.
-          If you don't specify the embed-url attribute the font will not be embedded, but will only be referenced.</p>
-        <warning>
-          Omitting the embed-url attribute for CID-encoded TrueType fonts will currently produce invalid 
-          PDF files! If you create the XML font metric file using the "-enc ansi" option, you can omit 
-          the embed-url attribute for TrueType fonts but you're restricted to the WinAnsi character set.
-        </warning>
-        <p>When FOP embeds a font, it adds a prefix to the fontname to ensure that the name will not match the fontname of an installed font.
-          This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.</p>
-        <p>When embedding PostScript fonts, the entire font is always embedded.</p>
-        <p>When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a subset of the
-          original font, containing only the glyphs used, is embedded in the output document.</p>
+        <p>
+          By default, all fonts are embedded if an output format supports font embedding. In some
+          cases, however, it is preferred that some fonts are only referenced. When working
+          with referenced fonts it is important to be in control of the target environment where
+          the produced document is consumed, i.e. the necessary fonts have to be installed there.
+        </p>
+        <p>
+          There are two different ways how you can specify that a font should be referenced:
+        </p>
+        <ol>
+          <li>
+            When using the old-style "font" element to configure a single font, font referencing
+            is controlled by the embed-url attribute. If you don't specify the embed-url attribute
+            the font will not be embedded, but will only be referenced.
+          </li>
+          <li>
+            For automatically configured fonts there's a different mechanism to specify which
+            fonts should be referenced rather than embedded. This is done in the "referenced-fonts"
+            element in the configuration. Here's an example:
+          </li>
+        </ol>
+        <source><![CDATA[
+<fop version="1.0">
+   <fonts>
+      <referenced-fonts>
+        <match font-family="Helvetica"/>
+        <match font-family="DejaVu.*"/>
+      </referenced-fonts>
+   </fonts>
+</fop>]]></source>
+        <p>
+          At the moment, you can only match fonts against their font-family. It is possible to use
+          regular expressions as is shown in the second example above ("DejaVu.*"). The syntax for
+          the regular expressions used here are the one used by the
+          <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/regex/package-summary.html"><code>java.util.regex</code> package</a>.
+          So, in the above snippet "Helvetica" and all variants of the "DejaVu" font family are
+          referenced. If you want to reference all fonts, just specify <code>font-family=".*"</code>.
+        </p>
+        <p>
+          Various notes related to embedded fonts:
+        </p>
+        <ul>
+          <li>The PostScript renderer does not yet support TrueType fonts, but can embed Type 1 fonts.</li>
+          <li>The font is simply embedded into the PDF file, it is not converted.</li>
+          <li>When FOP embeds a font, it adds a prefix to the fontname to ensure that the name will not match the fontname of an installed font.
+            This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.</li>
+          <li>When embedding PostScript fonts, the entire font is always embedded.</li>
+          <li>When embedding TrueType fonts (ttf) or TrueType Collections (ttc), a subset of the
+          original font, containing only the glyphs used, is embedded in the output document.</li>
+        </ul>
       </section>
       <section id="substitution">
          <title>Substitution</title>