<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!-- $Id: quickstartguide.xml 1394416 2012-10-05 08:56:54Z gadams $ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
<document>
  <header>
    <title>Apache™ FOP: Quick Start Guide</title>
    <subtitle>Everything you need to start using and appreciating Apache™ FOP quickly.</subtitle>
    <version>$Revision: 1394416 $</version>
  </header>
  <body>
    <section id="essentials">
      <title>Apache™ FOP Essentials</title>
      <p>The goal of this <strong>Quick Start Guide</strong> is to help novice users get Apache FOP up and running quickly. Typically, you'll need to:</p>
      <ol>
        <li><link href="download.html">Download FOP</link></li>
        <li><link href="1.1/compiling.html">Build FOP</link> (you can skip this step if you download the binary distribution!)</li>
        <li><link href="1.1/configuration.html">Configure FOP</link></li>
        <li><link href="1.1/running.html">Run FOP</link></li>
      </ol>
      <p>Here are some links to help you find out what FOP can do, as well as how and where to get help:</p>
      <ul>
        <li><link href="1.1/embedding.html">Calling FOP from a Java Application</link></li>
        <li><link href="1.1/servlets.html">Using FOP in Servlets</link></li>
        <li><link href="1.1/anttask.html">Using FOP in an 'Ant' Build Script</link></li>
        <li><link href="compliance.html" title="FOP Compliance">XSL-FO Compliance</link> (what FOP supports and what it doesn't)</li>
        <li><link href="faq.html">FAQs</link></li>
        <li><link href="gethelp.html">Getting Help</link></li>
        <li><link href="maillist.html">Mailing Lists</link></li>
      </ul>
      <p>
        Once you've familiarized yourself with the basics, you can get more detailed information,
        in the detailed FOP <link href="1.1/index.html">product documentation</link>.
      </p>
    </section>
    
    <section id="hello-world">
      <title>Hello World with FOP</title>
      <p>
        This section walks you through a "Hello World!" page with Apache FOP. We're assuming you
        download the binary distribution and that you have a Java Runtime Environment (version 1.4
        or later) installed.
      </p>
      <ol>
        <li>
          Unpack the downloaded binary distribution to a directory of your choice (for example,
          <code>C:\FOP</code> if you're on Windows). Let's call that
          directory &lt;fop-home&gt;.
        </li>
        <li>
          Get a command prompt in the &lt;fop-home&gt; directory and write:<br/>
          Windows: <code>fop -fo examples/fo/basic/readme.fo -awt</code><br/>
          Unix: <code>./fop -fo examples/fo/basic/readme.fo -awt</code><br/>
        </li>
        <li>
          If all went well, this should open a window showing you a "readme"-style document.
          This is just to verify that FOP runs correctly.
        </li>
        <li>
          Now, take your favorite XML editor and create a small XML file like the following. Replace
          "Frank" with your own first name to make it a bit more personal and save it as
          <code>name.xml</code>:<br/>
          <source><![CDATA[<name>Frank</name>]]></source>
        </li>
        <li>
          To produce a PDF file from this XML file, we need an XSLT stylesheet that converts the
          XML to XSL-FO. This is the first step in the processing chain. The second step will be
          done by FOP when it reads the generated XSL-FO document and formats it to a PDF document.
          You can copy the following minimal XSLT stylesheet, which takes your first name and
          produces a "Hello World!"-style document (save it as <code>name2fo.xsl</code>):<br/>
          <source><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:fo="http://www.w3.org/1999/XSL/Format">
  <xsl:output method="xml" indent="yes"/>
  <xsl:template match="/">
    <fo:root>
      <fo:layout-master-set>
        <fo:simple-page-master master-name="A4-portrait"
              page-height="29.7cm" page-width="21.0cm" margin="2cm">
          <fo:region-body/>
        </fo:simple-page-master>
      </fo:layout-master-set>
      <fo:page-sequence master-reference="A4-portrait">
        <fo:flow flow-name="xsl-region-body">
          <fo:block>
            Hello, <xsl:value-of select="name"/>!
          </fo:block>
        </fo:flow>
      </fo:page-sequence>
    </fo:root>
  </xsl:template>
</xsl:stylesheet>]]></source>
          
        </li>
        <li>
          Finally, let's put the previous two steps together: Go back to the command prompt and
          enter the following command:<br/>
          Windows: <code>fop -xml name.xml -xsl name2fo.xsl -pdf name.pdf</code><br/>
          Unix: <code>./fop -xml name.xml -xsl name2fo.xsl -pdf name.pdf</code><br/>
        </li>
        <li>
          You've produced your first PDF with Apache FOP! Please open <code>name.pdf</code>
          in your favorite PDF viewer.
        </li>
      </ol>
    </section>
  </body>
</document>
