forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: rev 23055 - in forrest/trunk: . src/documentation/content/xdocs src/documentation/content/xdocs/howto
Date Mon, 19 Jul 2004 07:25:44 GMT
Author: crossley
Date: Mon Jul 19 00:25:43 2004
New Revision: 23055

   forrest/trunk/src/documentation/content/xdocs/howto/howto-asf-mirror.xml   (contents, props
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
@@ -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
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  See the License for the specific language governing permissions and
+  limitations under the License.
+<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.2//EN"
+  <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="">Making your
+      downloads mirrorable</link> and
+      <link href="">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="">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="">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=""/>
+  ...]]></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>

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><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
         - 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"/>

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 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.

View raw message