You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2004/07/19 09:25:44 UTC
svn commit: rev 23055 - in forrest/trunk: . src/documentation/content/xdocs src/documentation/content/xdocs/howto
Author: crossley
Date: Mon Jul 19 00:25:43 2004
New Revision: 23055
Added:
forrest/trunk/src/documentation/content/xdocs/howto/howto-asf-mirror.xml (contents, props changed)
Modified:
forrest/trunk/src/documentation/content/xdocs/howto/index.xml
forrest/trunk/src/documentation/content/xdocs/site.xml
forrest/trunk/status.xml
Log:
Add a new howto. Generate an ASF mirrors page using interactive web form with ihtml.
Added: forrest/trunk/src/documentation/content/xdocs/howto/howto-asf-mirror.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/documentation/content/xdocs/howto/howto-asf-mirror.xml Mon Jul 19 00:25:43 2004
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ 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>
+ </p>
+ <p>
+ 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"/>
+ ...]]></source>
+ </section>
+
+ <section id="link">
+ <title>Add a link to cause the mirrors.ithml to be processed</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>To enable this, use the trick of an invisible link in one of your
+ xdocs, e.g.
+ <code><![CDATA[<link href="site:mirrors"/>]]></code>
+ </p>
+ <fixme author="open">
+ There must be a better way to process extra documents, probably using
+ the Cocoon cli.xconf file. The invisible link trick is a fine
+ workaround because the link is not rendered into the final output.
+ </fixme>
+ </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>
Modified: forrest/trunk/src/documentation/content/xdocs/howto/index.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/howto/index.xml (original)
+++ forrest/trunk/src/documentation/content/xdocs/howto/index.xml Mon Jul 19 00:25:43 2004
@@ -28,6 +28,11 @@
- Provides instructions about writing documents. Please copy this
file to serve as a template for your own document.
</li>
+ <li><link href="site:howto/asf-mirror">Generate an ASF mirrors page using interactive web form</link>
+ - 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.
+ </li>
<li><link href="site:howto/pdf-tab">How to create a PDF document for each tab</link>
- Describes the generation of a PDF document for each
group of documents that is defined by a tab.
Modified: forrest/trunk/src/documentation/content/xdocs/site.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/site.xml (original)
+++ forrest/trunk/src/documentation/content/xdocs/site.xml Mon Jul 19 00:25:43 2004
@@ -100,6 +100,7 @@
<howto label="How-To" href="howto/" tab="howto">
<overview label="Overview" href="index.html"/>
<write-howto label="Write a How-to" href="howto-howto.html"/>
+ <asf-mirror label="Download mirror" href="howto-asf-mirror.html"/>
<pdf-tab label="Create tab PDF" href="howto-pdf-tab.html"/>
</howto>
Modified: forrest/trunk/status.xml
==============================================================================
--- forrest/trunk/status.xml (original)
+++ forrest/trunk/status.xml Mon Jul 19 00:25:43 2004
@@ -50,6 +50,12 @@
Added new document to facilitate
<link href="site:upgrading_06">upgrading to v0.6</link>
</action>
+ <action dev="DC" type="add" context="docs">
+ Added a How-To:
+ <link href="site:asf-mirror">Generate an ASF mirrors page using
+ interactive web form</link> and ihtml to include additional html
+ form elements.
+ </action>
<action dev="DB" type="add" context="forrestbot" fixes-bug="FOR-219">
Added forrestbot deploy.svn implmentation.
</action>