legacy-tests/build/test/4/preface.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
  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.
-->
<preface conformance="docgen" xml:id="preface"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:ns5="http://www.w3.org/2000/svg"
         xmlns:ns4="http://www.w3.org/1998/Math/MathML"
         xmlns:ns3="http://www.w3.org/1999/xhtml"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Preface</title>

  <section>
    <title>What is FreeMarker?</title>

    <para>FreeMarker is a <emphasis>template engine</emphasis>: a generic
    tool to generate text output (anything from HTML to autogenerated source
    code) based on templates. It's a Java package, a class library for Java
    programmers. It's not an application for end-users in itself, but
    something that programmers can embed into their products.</para>

    <para>FreeMarker is designed to be practical for the generation of
    <emphasis>HTML Web pages</emphasis>, particularly by servlet-based
    applications following the <link linkend="gloss.MVC">MVC (Model View
    Controller) pattern</link>. The idea behind using the MVC pattern for
    dynamic Web pages is that you separate the designers (HTML authors) from
    the programmers. Everybody works on what they are good at. Designers can
    change the appearance of a page without programmers having to change or
    recompile code, because the application logic (Java programs) and page
    design (FreeMarker templates) are separated. Templates do not become
    polluted with complex program fragments. This separation is useful even
    for projects where the programmer and the HTML page author is the same
    person, since it helps to keep the application clear and easily
    maintainable.</para>

    <para>Although FreeMarker has some programming capabilities, it is
    <emphasis>not</emphasis> a full-blown programming language like PHP.
    Instead, Java programs prepare the data to be displayed (like issue SQL
    queries), and FreeMarker just generates textual pages that display the
    prepared data using templates.</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="figures/overview.png"></imagedata>
      </imageobject>
    </mediaobject>

    <para>FreeMarker is <emphasis>not</emphasis> a Web application
    framework. It is suitable as a component in a Web application framework,
    but the FreeMarker engine itself knows nothing about HTTP or servlets.
    It simply generates text. As such, it is perfectly usable in non-web
    application environments as well. Note, however, that we provide
    out-of-the-box solutions for using FreeMarker as the view component of
    Model 2 frameworks such as Struts.</para>

    <para>FreeMarker is <link
    xlink:href="http://www.fsf.org/philosophy/free-sw.html">Free</link>,
    released under a BSD-style license. It is <link
    xlink:href="http://www.opensource.org/">OSI Certified Open Source
    Software</link>. OSI Certified is a certification mark of the Open
    Source Initiative.</para>
  </section>

  <section>
    <title>What should I read?</title>

    <para>If you are a ...</para>

    <itemizedlist>
      <listitem>
        <para>designer, then you should read the <xref linkend="dgui" /> and
        then you can look into the <xref linkend="ref" /> on an as-needed
        basis for more specific details.</para>
      </listitem>

      <listitem>
        <para>programmer, then you should read the <xref linkend="dgui" />
        guide first, then the <xref linkend="pgui" /> and then you can look
        into the <xref linkend="ref" /> on an as-needed basis for more
        specific details.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Document conventions</title>

    <para>Variable names, template fragments, Java class names, etc. are
    written like this: <literal>foo</literal>.</para>

    <para>If something should be replaced with a concrete value then it is
    written in italics, as follows: <literal>Hello
    <replaceable>yourName</replaceable>!</literal>.</para>

    <para>Template examples are written like this:</para>

    <programlisting role="template">something</programlisting>

    <para>Data-model examples are written like this:</para>

    <programlisting role="dataModel">something</programlisting>

    <para>Output examples are written like this:</para>

    <programlisting role="output">something</programlisting>

    <para>Program examples are written like this:</para>

    <programlisting role="unspecified">something</programlisting>

    <remark>This paragraph is for the editors, and not visible for the
    public</remark>

    <para>In chapters <remark>this section is for the editors
    too</remark>written for both designers and programmers fragments
    addressed to programmers are written like this: <phrase
    role="forProgrammers">This is for programmers only.</phrase></para>

    <para>New terms are emphasized like this: <emphasis role="term">some new
    term</emphasis></para>
  </section>

  <section>
    <title>Contact</title>

    <indexterm>
      <primary>help</primary>
    </indexterm>

    <indexterm>
      <primary>homepage</primary>
    </indexterm>

    <indexterm>
      <primary>download</primary>
    </indexterm>

    <indexterm>
      <primary>contact</primary>
    </indexterm>

    <para>For the latest version of FreeMarker and to subscribe to the
    <emphasis>mailing lists</emphasis> visit the FreeMarker homepage: <olink
    targetdoc="homepage"><phrase role="homepage"></phrase></olink></para>

    <mediaobject xml:id="test_target">
      <imageobject>
        <imagedata fileref="bat.jpg"></imagedata>
      </imageobject>
    </mediaobject>
    
    <para>If you <emphasis>need help</emphasis> or you have
    <emphasis>suggestions</emphasis>, use the mailing lists (mail archives
    can be searched without subscription) or the Web based forums. If you
    want to <emphasis>report a bug</emphasis>, use the Web based bug
    tracker, or the mailing lists. To find all of these visit <olink
    targetdoc="homepage"><phrase role="homepage"></phrase></olink>. Also,
    note that we have a <link linkend="app_faq">FAQ</link> and <link
    linkend="alphaidx">index</link>; use them.</para>
  </section>

  <section>
    <title>About this document</title>

    <para>If you find <emphasis>any mistakes</emphasis> (including
    <emphasis>grammatical mistakes</emphasis>, <emphasis>typos</emphasis>,
    typographical mistakes) or you find something <emphasis>misleading or
    confusing</emphasis> in the documentation, or you have other
    suggestions, please let me know! Email: ddekany at
    users.sourceforge.net</para>
  </section>
</preface>