some font faq clarifications

removed or fixed empty links
added wiki link


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

6 files changed, 97 insertions, 74 deletions

diff --git a/src/documentation/content/xdocs/dev/book.xml b/src/documentation/content/xdocs/dev/book.xml
index 74e016c4d..2bcb04277 100644
--- a/src/documentation/content/xdocs/dev/book.xml
+++ b/src/documentation/content/xdocs/dev/book.xml
@@ -24,6 +24,7 @@
       <menu-item label="Fonts" href="fonts.html"/>
     </menu>
     <menu label="Developers">
+      <external label="Tasks Wiki" href="http://codeconsult.ch/wiki/index.php/FopTasks"/>
       <menu-item label="Design" href="../design/index.html"/>
     </menu>
 </book>
diff --git a/src/documentation/content/xdocs/dev/faq.xml b/src/documentation/content/xdocs/dev/faq.xml
index 3a1c56f24..800174f74 100644
--- a/src/documentation/content/xdocs/dev/faq.xml
+++ b/src/documentation/content/xdocs/dev/faq.xml
@@ -274,12 +274,12 @@
           <code>path/file.ext</code> or <code>../file.ext</code>. The string
           <code>file:path/file.ext</code> is <em>not</em> a relative URL,
           in fact, it isn't a valid URL at all. A relative URL is subject to a
-          <link>resolving process</link>, which transforms it into an absolute
+          resolving process, which transforms it into an absolute
           URL.
         </p>
         <p>
-          See <link>Understanding URIs and URLs</link> and <link>Understanding
-          URL resolving</link>.
+          See Understanding URIs and URLs and Understanding
+          URL resolving.
         </p>
       </answer>
     </faq>
@@ -298,7 +298,7 @@
           whether you got them right.
         </p>
         <p>
-          You can use the <link>FOP DTD</link> or <link>FOP Schema</link> to
+          You can use the FOP DTD or FOP Schema to
           validate your soure. This will catch most, but still not all problems.
         </p>
         <p>
@@ -368,8 +368,8 @@
           the user agent.
         </p>
         <p>
-          See <link>Understanding URIs and URLs</link> and <link>Understanding
-          URL resolving</link>.
+          See Understanding URIs and URLs and Understanding
+          URL resolving.
         </p>
       </answer>
     </faq>
@@ -506,7 +506,7 @@
           </li>
         </ul>
         <p>
-          See also <link>supported image formats</link>.
+          See also supported image formats.
         </p>
       </answer>
     </faq>
@@ -526,7 +526,7 @@
     <faq>
       <question>How do I use FOP in a servlet?</question>
       <answer>
-        <p>Look at the <link>servlet example</link>.</p>
+        <p>Look at the servlet example.</p>
         <p>
           A rather minimal code snippet to demonstrate the basics:
         </p>
@@ -541,7 +541,7 @@ driver.run();</source>
           with IEx and view it later. There are other problems with this code.
         </p>
         <p>
-          Please look into <link>Howto embed FOP in a servlet</link> for all
+          Please look into Howto embed FOP in a servlet for all
           kinds of details.
         </p>
       </answer>
@@ -802,26 +802,30 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</so
       <question>How do I embed fonts in PDF?</question>
       <answer>
         <p>
-          Provide$$$
+          See the <link href="fonts.html">Fonts</link> page for information
+          about embedding fonts.
         </p>
       </answer>
     </faq>
     <faq>
-      <question>Characters not displayed, or displayed incorrectly, or displayed
-  as "#"</question>
+      <question>Characters not displayed, or displayed incorrectly, or displayed  as "#"</question>
       <answer>
-        <p>  Answers are that fonts must be available on the target platform, and
+        <p>Answers are that fonts must be available for the output format, and
   the selected font must contain glyphs for the desired character.
+PDF has a set of <link href="output.html#pdf-fonts">defined fonts</link>, other fonts can be embedded following the
+<link href="fonts.html">instructions</link>.
+To find out if the characters you need are in the core fonts then
+(todo - find a glyph font table for the fonts).
 </p>
         <p>  For example, for most symbols, the symbol font has to be selected
-  explicitely (actually: is this a feature or a bug?):
+  explicitely (in future it should be possible to specify a list of fonts
+where it will select the font for the specified character):
 </p>
 <p>   &lt;fo:inline font-family="Symbol">&amp;#x2205;&lt;/fo:inline></p>
 <p>  gives EMPTY SET while the same characters in the default font results
   in AE LIGATURE (which happens to occupy the same place in the default
   font as the EMPTY SET in the Symbol font). The "#" shows up if the
   selected font does not define a glyph for the translated index.</p>
-        <p>(Still applicable in 0.20.3?)</p>
       </answer>
     </faq>
     <faq>
diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index 91e39f505..ef25c3646 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -113,8 +113,8 @@
       <question>How can I contribute?</question>
       <answer>
         <p>
-          There is always plenty of things to do. See <link>limitations</link>
-          and <link>bugzilla</link>.
+          There is always plenty of things to do. See
+          <link href="involved.html">getting involved</link>.
         </p>
       </answer>
     </faq>
@@ -139,7 +139,7 @@
           master definitions.
         </p>
         <p>
-          See also <link>release notes</link>.
+          See also <link href="relnotes.html">release notes</link>.
         </p>
       </answer>
     </faq>
@@ -150,14 +150,14 @@
           The Jimi image library, which is used for processing images in PNG and
           other formats, was removed from the distribution for licensing
           reasons. You have to <fork href="http://java.sun.com">download</fork>
-          and <link>install</link> it by yourself.
+          and install it by yourself.
         </p>
       </answer>
     </faq>
     <faq>
       <question>I get a NoClassDefFound exception.</question>
       <answer>
-        <p>This is typically a problem with your <link>classpath</link>.</p>
+        <p>This is typically a problem with your classpath.</p>
         <p>If you are running FOP from the command line:</p>
         <ul>
           <li>
@@ -207,11 +207,11 @@
         </p>
         <ul>
           <li>
-            Avoid forward <link>references</link>. Forward references cause all
+            Avoid forward references. Forward references cause all
             pages from the page with the reference on to be held in memory until
             the page with the referenced element is encountered. Common forward
             references are table of contents at the beginning of the document
-            and the <link>"page N of TOTAL"</link> in footers. Forward
+            and the <link href="#pagenum">"page N of TOTAL"</link> in footers. Forward
             references may be required by the task, however, if you are getting
             a memory overflow you should at least check whether this is really
             as necessary as claimed. A TOC, for example, could often be placed
@@ -233,7 +233,7 @@
             possibly be freed after the page sequence has been rendered.
           </li>
           <li>
-            Increase <link>memory settings of the JVM</link>. Be aware that it
+            Increase memory settings of the JVM. Be aware that it
             is usually unwise to increase the memory allocated to the JVM beyond
             the amount of physical RAM, it will significantly slow down. YMMV.
           </li>
@@ -248,13 +248,14 @@
         </p>
         <p>
           Reducing memory consumption in general and squishing bugs is an
-          ongoing effort, partially addressed in the <link>redesign</link>.
+          ongoing effort, partially addressed in the <link href="dev/index.html">redesign</link>.
         </p>
       </answer>
     </faq>
     <faq>
       <question>I get a MalformedURLException.</question>
       <answer>
+        <anchor id="MalformedURL"/>
         <p>
           What you probably think of as "file names" are usually URLs, in
           particular the src attribute of fo:external-graphic.
@@ -277,12 +278,12 @@
           <code>path/file.ext</code> or <code>../file.ext</code>. The string
           <code>file:path/file.ext</code> is <em>not</em> a relative URL,
           in fact, it isn't a valid URL at all. A relative URL is subject to a
-          <link>resolving process</link>, which transforms it into an absolute
+          resolving process, which transforms it into an absolute
           URL.
         </p>
         <p>
-          See <link>Understanding URIs and URLs</link> and <link>Understanding
-          URL resolving</link>.
+          See Understanding URIs and URLs and Understanding
+          URL resolving.
         </p>
       </answer>
     </faq>
@@ -367,13 +368,13 @@ FO document. This will catch most problems, but should not be relied upon to cat
           Relative URLs are resolved against the baseDir property of FOP. For
           the command line FOP application, the baseDir is the directory of the
           input file, either the FO file or the XML source. If FOP is used
-          embedded in a servlet, <link>baseDir can be set explicitely</link>. If
+          embedded in a servlet, <link href="embedding.html">baseDir can be set explicitely</link>. If
           it's not set, it is usually the current working directory of the
           process which runs FOP.
         </p>
         <p>
-          See <link>Understanding URIs and URLs</link> and <link>Understanding
-          URL resolving</link>.
+          See Understanding URIs and URLs and Understanding
+          URL resolving.
         </p>
       </answer>
     </faq>
@@ -510,7 +511,7 @@ FO document. This will catch most problems, but should not be relied upon to cat
           </li>
         </ul>
         <p>
-          See also <link>supported image formats</link>.
+          See also supported image formats.
         </p>
       </answer>
     </faq>
@@ -530,7 +531,7 @@ FO document. This will catch most problems, but should not be relied upon to cat
     <faq>
       <question>How do I use FOP in a servlet?</question>
       <answer>
-        <p>Look at the <link>servlet example</link>.</p>
+        <p>Look at the servlet example.</p>
         <p>
           A rather minimal code snippet to demonstrate the basics:
         </p>
@@ -545,7 +546,7 @@ driver.run();</source>
           with IEx and view it later. There are other problems with this code.
         </p>
         <p>
-          Please look into <link>Howto embed FOP in a servlet</link> for all
+          Please look into Howto embed FOP in a servlet for all
           kinds of details.
         </p>
       </answer>
@@ -822,12 +823,6 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</so
           <li>
             Make sure that the reference is valid in the current SVG document.
           </li>
-          <li>
-            **DOES THIS WORK**
-            Let the URL refer to some location where the gradient could be
-            retrieved, for example if the SVG code is embedded in your XSL,
-            try <code>fill="url(my.xsl#PurpleToWhite)"</code>.
-          </li>
         </ul>
         <p>
           In any case, the referenced stuff has to be pointed to by an URL. It
@@ -841,7 +836,7 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</so
           but also some effort by a standard committee in order to make the
           semantics of this kind of references in embedded SVG clearer.
         </p>
-        <p>See also <link>MalformedURLException</link></p>
+        <p>See also <link href="#MalformedURL">MalformedURLException</link></p>
       </answer>
     </faq>
   </part>
@@ -851,7 +846,8 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</so
       <question>How do I embed fonts in PDF?</question>
       <answer>
         <p>
-          Provide$$$
+          See the <link href="fonts.html">Fonts</link> page for information
+          about embedding fonts.
         </p>
       </answer>
     </faq>
@@ -859,18 +855,22 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</so
       <question>Characters not displayed, or displayed incorrectly, or displayed
   as "#"</question>
       <answer>
-        <p>  Answers are that fonts must be available on the target platform, and
+        <p>Answers are that fonts must be available for the output format, and
   the selected font must contain glyphs for the desired character.
+PDF has a set of <link href="output.html#pdf-fonts">defined fonts</link>, other fonts can be embedded following the
+<link href="fonts.html">instructions</link>.
+To find out if the characters you need are in the core fonts then
+(todo - find a glyph font table for the fonts).
 </p>
         <p>  For example, for most symbols, the symbol font has to be selected
-  explicitely (actually: is this a feature or a bug?):
+  explicitely (in future it should be possible to specify a list of fonts
+where it will select the font for the specified character):
 </p>
 <p>   &lt;fo:inline font-family="Symbol">&amp;#x2205;&lt;/fo:inline></p>
 <p>  gives EMPTY SET while the same characters in the default font results
   in AE LIGATURE (which happens to occupy the same place in the default
   font as the EMPTY SET in the Symbol font). The "#" shows up if the
   selected font does not define a glyph for the translated index.</p>
-        <p>(Still applicable in 0.20.3?)</p>
       </answer>
     </faq>
     <faq id="PDF-postprocess">
@@ -1236,6 +1236,7 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler()));</so
       <question>(FO) How do I print the total number of pages, like in "page 1
       of 12"</question>
       <answer>
+        <anchor id="pagenum"/>
         <p>
           (XSL FAQ)
         </p>
@@ -1396,7 +1397,7 @@ class rendtest {
           offending characters.
         </p>
         <p>
-          Refer to the <link>XML specification</link> or to a good tutorial for
+          Refer to the <link href="http://www.w3.org/XML/">XML specification</link> or to a good tutorial for
           details of the XML file format.
         </p>
       </answer>
diff --git a/src/documentation/content/xdocs/fo/size.fo b/src/documentation/content/xdocs/fo/size.fo
index 0279c69ef..2076276df 100644
--- a/src/documentation/content/xdocs/fo/size.fo
+++ b/src/documentation/content/xdocs/fo/size.fo
@@ -105,6 +105,11 @@ The image
 (<fo:external-graphic content-width="75pt" content-height="100pt" scaling="uniform" src="images/fop.jpg"/>)
 has uniform scaling.
   </fo:block>
+  <fo:block>
+The image
+(<fo:external-graphic width="75pt" height="100pt" content-width="scale-to-fit" content-height="scale-to-fit" src="images/fop.jpg"/>)
+is scaled to fit the viewport.
+  </fo:block>
 </fo:block>
 
 <fo:block>
diff --git a/src/documentation/content/xdocs/fonts.xml b/src/documentation/content/xdocs/fonts.xml
index d76e05aa3..478b08a69 100644
--- a/src/documentation/content/xdocs/fonts.xml
+++ b/src/documentation/content/xdocs/fonts.xml
@@ -18,6 +18,10 @@
     </p>
     <p>Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe
     Type 1 fonts and TrueType fonts. No other font types (Type 3, etc.) are supported at this time.
+    More information about font types can be found at
+    the <link href="http://partners.adobe.com/asn/developer/type/ftypes.html">
+    Adobe font types</link>. There is also lots more font information
+    on this <link href="http://partners.adobe.com/asn/developer/technotes/fonts.html">Adobe Font Technote</link>.
     </p>
     <note>
         The font is simply embedded into the PDF file, it is not converted.
@@ -34,15 +38,15 @@
       </p>
       <p>Windows:</p>
 <source>
-
-  java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.PFMReader pfm-file xml-file
-
+java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
+         lib\xercesImpl.jar;lib\xalan.jar
+           org.apache.fop.fonts.apps.PFMReader pfm-file xml-file
 </source>
       <p>Unix:</p>
 <source>
-
-  java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:lib/xercesImpl.jar:lib/xalan.jar org.apache.fop.fonts.apps.PFMReader pfm-file xml-file
-
+java -cp build/fop.jar:lib/avalon-framework.jar:lib/xml-apis.jar:
+         lib/xercesImpl.jar:lib/xalan.jar
+           org.apache.fop.fonts.apps.PFMReader pfm-file xml-file
 </source>
       <note>
         The classpath in the above example has been simplified for readibity. 
@@ -60,17 +64,14 @@
     <section>
       <title>Register the fonts within FOP</title>
       <p>
-                Edit conf/userconfig.xml and add entries for the font
-                if the fonts section,
-                ie:
+        Edit conf/userconfig.xml and add entries for the font
+        if the fonts section,
+        ie:
       </p>
-<source>
-<![CDATA[
-  <font metrics-file="FTL_____.xml" kerning="yes" embed-file="C:\myfonts\FTL_____.pfb">
-    <font-triplet name="FrutigerLight" style="normal" weight="normal">
-  </font>]]>
-
-</source>
+<source><![CDATA[<font metrics-file="FTL_____.xml" kerning="yes"
+      embed-file="C:\myfonts\FTL_____.pfb">
+  <font-triplet name="FrutigerLight" style="normal" weight="normal">
+</font>]]></source>
       <note>
         Starting from FOP version 0.20.5 you can use URLs for the paths to the font files. Relative URLs are resolved 
         relative to the fontBaseDir property (or baseDir) if available.
@@ -109,9 +110,10 @@
             the name cmr10.ttf and exists in c:\myfonts\):
       </p>
 <source>
-
-  java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.TTFReader C:\myfonts\cmr10.ttf C:\myfonts\cmr10.ttf ttfcm.xml
-
+java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
+         lib\xercesImpl.jar;lib\xalan.jar
+           org.apache.fop.fonts.apps.TTFReader
+             C:\myfonts\cmr10.ttf C:\myfonts\cmr10.ttf ttfcm.xml
 </source>
     </section>
     <section>
@@ -132,9 +134,10 @@
       Example on generating metrics for a .ttc file:
       </p>
 <source>
-      
-  java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;lib\xercesImpl.jar;lib\xalan.jar org.apache.fop.fonts.apps.TTFReader -ttcname "MS Mincho" msmincho.ttc msminch.xml
-
+java -cp build\fop.jar;lib\avalon-framework.jar;lib\xml-apis.jar;
+         lib\xercesImpl.jar;lib\xalan.jar
+           org.apache.fop.fonts.apps.TTFReader -ttcname "MS Mincho"
+             msmincho.ttc msminch.xml
 </source>
     </section>
 
@@ -143,13 +146,10 @@
         <p>
           Similiar to Type 1 fonts.
         </p>
-<source>
-<![CDATA[
-  <font metrics-file="cyberbit.xml" kerning="yes" embed-file="C:\WINNT\Fonts\Cyberbit.ttf">
-    <font-triplet name="Cyberbit" style="normal" weight="normal">
-  </font>]]>
-
-</source>
+<source><![CDATA[<font metrics-file="cyberbit.xml" kerning="yes"
+      embed-file="C:\WINNT\Fonts\Cyberbit.ttf">
+  <font-triplet name="Cyberbit" style="normal" weight="normal">
+</font>]]></source>
       </section>
 
   </section>
diff --git a/src/documentation/content/xdocs/output.xml b/src/documentation/content/xdocs/output.xml
index fee304c53..4af6ac7c6 100644
--- a/src/documentation/content/xdocs/output.xml
+++ b/src/documentation/content/xdocs/output.xml
@@ -81,6 +81,18 @@ The PDF version supported is 1.3 which is currently the most popular
 version for Acrobat Reader (4.0), PDF versions are forwards/backwards
 compatible.
     </p>
+    <anchor id="pdf-fonts"/>
+    <p>
+      PDF has a set of fonts that are always available to all PDF viewers,
+      to quote from the PDF Specification:
+
+<em>"PDF prescribes a set of 14 standard fonts that can be used without prior
+definition.
+These include four faces each of three Latin text typefaces (Courier,
+Helvetica, and Times), as well as two symbolic fonts (Symbol and ITC Zapf
+Dingbats). These fonts, or suitable substitute fonts with the same metrics, are
+guaranteed to be available in all PDF viewer applications."</em>
+    </p>
 </section>
 <section>
   <title>PCL</title>