<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation or its licensors,
  as applicable.

  Licensed 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.
-->
<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.2//EN"
"http://forrest.apache.org/dtd/howto-v12.dtd">
<howto>
  <header>
    <title>Generate an ASF mirrors page using interactive web form</title>

    <abstract>Use ihtml (interpreted html) to include html form elements
    into a forrest-generated html page. For example, this enables building
    automated download mirror pages for ASF project websites.
    </abstract>

    <last-modified-content-date date="2004-07-19" />
  </header>

  <audience title="Intended Audience">
    <ul>
      <li>Any Apache project that uses Forrest to generate their website
        will need to have a mirrors page.</li>
      <li>Also anyone interested in the use of ihtml to embed html form
        elements into a generated Forrest page.</li>
    </ul>
  </audience>

  <purpose title="Purpose">
    <p>All Apache projects use dynamically generated download pages
    which determine the closest mirror and provide an interactive list of
    the current alternative mirrors.
    This HowTo describes the procedure to generate the template page
    that is utilised by the mirrors.cgi script. The processed page
    includes html "form" elements that are not included in the xdocs DTDs.
    </p>
    <p>This process has many exciting applications, beyond the scope of
     this document.
    </p>
  </purpose>

  <prerequisites title="Prerequisites">
    <ul>
      <li>Followed the documentation about
      <link href="http://www.apache.org/~bodewig/mirror.html">Making your
      downloads mirrorable</link> and
      <link href="http://www.apache.org/dev/mirrors.html">Apache Mirroring Information</link>
      .
      </li>
      <li>Established your ASF distribution space as described.</li>
      <li>Already building your project website with Forrest.</li>
    </ul>
  </prerequisites>

  <steps title="Steps">
    <section id="cgi">
      <title>Add the mirrors.cgi as a raw file</title>
      <p>As explained in the mirrors document, there will be a two-line CGI
      wrapper script at the top-level of your website called
      <code>mirrors.cgi</code></p>
      <p>Utilising the Forrest concept of raw un-processed content,
       add the file as <code>src/documentation/mirrors.cgi</code>
       (copy the Forrest project's
        <link href="http://svn.apache.org/repos/asf/forrest/trunk/src/documentation/content/mirrors.cgi">mirrors.cgi</link>)
      </p>
    </section>

    <section id="ihtml">
      <title>Add the mirrors.ihtml to xdocs directory</title>
      <p>This file contains the html content of your mirror page, including
        the html form elements which drive the mirror selection. It also
        contains the specific tokens that are interpreted by the mirrors.cgi
        script to add the list of mirrors and select the closest.
      </p>
      <p>
        Add the file as <code>src/documentation/xdocs/mirrors.html</code>
        (Use the Forrest project's
        <link href="http://svn.apache.org/repos/asf/forrest/trunk/src/documentation/content/xdocs/mirrors.ihtml">mirrors.html</link>
        as a template and edit it to suit.)
      </p>
    </section>

    <section id="menu">
      <title>Add a menu entry for Download</title>
      <p>Add an entry to your site.xml navigation. For example ...
      </p>
      <source><![CDATA[
 <about label="About">
  <index label="Index" href="index.html"/>
  <license label="License" href="license.html"/>
  <download label="Download" href="http://forrest.apache.org/mirrors.cgi"/>
  <download_html href="mirrors.html"/><!-- so the page is part of a tab -->
  ...]]></source>
    </section>

    <section id="link">
      <title>Cause the mirrors.ithml to be processed as an extra file</title>
      <p>Forrest gathers the links that are to be crawled, by reading site.xml
        and by finding any other internal links in the actual documents.
        There is no link to mirrors.html because it is an extra file that needs
        to be generated and skinned, but not linked in any way.
      </p>
      <p>The Cocoon command-line interface
        (<link href="http://cocoon.apache.org/2.1/userdocs/offline/">CLI</link>)
        to the rescue. Add an entry to your project's cli.xconf by copying the
        default one from
        <code>$FORREST_HOME/context/WEB-INF/cli.xconf</code> to your
        <code>src/documentation/conf/</code> directory (or wherever
        ${forrest.conf-dir} points). Add the following entry ...
      </p>
      <source><![CDATA[
<uris name="mirrors" follow-links="false">
  <uri type="append" src="mirrors.html"/>
</uris>]]></source>
    </section>

    <section id="forrest">
      <title>Run 'forrest' to build your site</title>
      <p>
        That is all that you need to do, Forrest will take care of it from
        there. Run the '<code>forrest</code>' command. The mirrors.html page
        will be generated with the skin applied.
      </p>
    </section>

    <section id="explain">
      <title>Explanation of the process</title>
      <p>Forrest automatically reads ihtml files and transforms the html source
      to the forrest xdocs intermediate format. It mainly detects heading
      elements (h1, h2, etc.) and converts them to "sections". The remainder
      of the html elements are copied over as-is. With this technique the
      html form elements are copied over to the output.
      </p>
    </section>
  </steps>
</howto>
