| <?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$ --> |
| <!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$</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.1rc1/compiling.html">Build FOP</link> (you can skip this step if you download the binary distribution!)</li> |
| <li><link href="1.1rc1/configuration.html">Configure FOP</link></li> |
| <li><link href="1.1rc1/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.1rc1/embedding.html">Calling FOP from a Java Application</link></li> |
| <li><link href="1.1rc1/servlets.html">Using FOP in Servlets</link></li> |
| <li><link href="1.1rc1/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.1rc1/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 <fop-home>. |
| </li> |
| <li> |
| Get a command prompt in the <fop-home> 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> |
