husted 02/01/16 14:29:38 Added: docs/site jakarta-site2b.html Log: Post proposed revised version, submitted by robert burrell donkin Revision Changes Path 1.1 jakarta-site2/docs/site/jakarta-site2b.html Index: jakarta-site2b.html =================================================================== <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> <!-- Content Stylesheet for Site --> <!-- start the processing --> <!-- ====================================================================== --> <!-- Main Page Section --> <!-- ====================================================================== --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> <meta name="author" value="Jon S. Stevens"> <meta name="email" value="[EMAIL PROTECTED]"> <meta name="author" value="robert burrell donkin"> <meta name="email" value="[EMAIL PROTECTED]"> <title>The Jakarta Site - Using the jakarta-site2 module as a dependency</title> </head> <body bgcolor="#ffffff" text="#000000" link="#525D76"> <table border="0" width="100%" cellspacing="0"> <!-- TOP IMAGE --> <tr> <td colspan="2"> <a href="http://jakarta.apache.org";><img src="http://jakarta.apache.org/images/jakarta-logo.gif"; align="left" border="0"/></a> </td> </tr> </table> <table border="0" width="100%" cellspacing="4"> <tr><td colspan="2"> <hr noshade="" size="1"/> </td></tr> <tr> <!-- LEFT SIDE NAVIGATION --> <td width="20%" valign="top" nowrap="true"> <p><strong>Essentials</strong></p> <ul> <li> <a href="../index.html">Front Page</a> </li> <li> <a href="http://jakarta.apache.org/site/news.html";>News & Status</a> </li> <li> <a href="http://jakarta.apache.org/site/mission.html";>Mission</a> </li> <li> <a href="http://jakarta.apache.org/site/guidelines.html";>Guidelines Notes</a> </li> <li> <a href="http://jakarta.apache.org/site/faqs.html";>FAQs</a> </li> <li> <a href="../gump">Gump</a> </li> <li> <a href="http://search.apache.org/";>Search Apache Sites</a> </li> </ul> <p><strong>Download</strong></p> <ul> <li> <a href="http://jakarta.apache.org/site/binindex.html";>Binaries</a> </li> <li> <a href="http://jakarta.apache.org/site/sourceindex.html";>Source Code</a> </li> </ul> <p><strong>Get Involved</strong></p> <ul> <li> <a href="http://jakarta.apache.org/site/getinvolved.html";>Overview</a> </li> <li> <a href="http://jakarta.apache.org/site/cvsindex.html";>CVS Repositories</a> </li> <li> <a href="http://jakarta.apache.org/site/mail.html";>Mailing Lists</a> </li> <li> <a href="http://jakarta.apache.org/site/library.html";>Reference Library</a> </li> <li> <a href="http://jakarta.apache.org/site/bugs.html";>Bug Database</a> </li> </ul> <p><strong>SubProjects</strong></p> <ul> <li> <a href="../alexandria/index.html">Alexandria</a> </li> <li> <a href="../ant/index.html">Ant</a> </li> <li> <a href="../avalon/index.html">Avalon</a> </li> <li> <a href="../bcel/index.html">BCEL</a> </li> <li> <a href="../cactus/index.html">Cactus</a> </li> <li> <a href="../commons/index.html">Commons</a> </li> <li> <a href="../ecs/index.html">ECS</a> </li> <li> <a href="../james/index.html">James</a> </li> <li> <a href="../jetspeed/index.html">Jetspeed</a> </li> <li> <a href="../jmeter/index.html">JMeter</a> </li> <li> <a href="../log4j/index.html">Log4J</a> </li> <li> <a href="../lucene/index.html">Lucene</a> </li> <li> <a href="../oro/index.html">ORO</a> </li> <li> <a href="../regexp/index.html">Regexp</a> </li> <li> <a href="../slide/index.html">Slide</a> </li> <li> <a href="../struts/index.html">Struts</a> </li> <li> <a href="../taglibs/index.html">Taglibs</a> </li> <li> <a href="../tomcat/index.html">Tomcat</a> </li> <li> <a href="../turbine/index.html">Turbine</a> </li> <li> <a href="../velocity/index.html">Velocity</a> </li> <li> <a href="../watchdog/index.html">Watchdog</a> </li> </ul> <p><strong>Misc</strong></p> <ul> <li> <a href="http://jakarta.apache.org/site/whoweare.html";>Who We Are</a> </li> <li> <a href="http://jakarta.apache.org/site/acknowledgements.html";>Acknowledgements</a> </li> <li> <a href="http://jakarta.apache.org/site/roles.html";>Management</a> </li> <li> <a href="http://jakarta.apache.org/site/jakarta-site2.html";>About This Site</a> </li> <li> <a href="http://jakarta.apache.org/site/contact.html";>Contact</a> </li> <li> <a href="http://jakarta.apache.org/site/legal.html";>Legal</a> </li> </ul> </td> <td width="80%" align="left" valign="top"> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#525D76"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="What is this?"><strong>What is this?</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> The Jakarta-Site2 module is where we store the code for building our static HTML website. We use XML files as our input and transform them into static HTML files (which is what you are reading now). The reason why we use static HTML is because the apache.org server gets a huge number of "hits" each day. Having a dynamic site would increase the load on the server to an even more unacceptable level because apache.org is a limited resource shared by hundreds of people. Using XML as our input allows us to change the look and feel of the entire site in a matter of seconds. </p> <p> Each Jakarta project has the choice of how they generate their website and documentation. The "encouraged" way is to use the Jakarta-Site2 module as the basis for generating the documentation. The provides a consistent look and feel for all of the Jakarta sites pages. As you browse various projects, you may notice slight variations in the look of the site. This is because other projects have chosen to use different technologies for transforming their XML files and have not kept up with the general look and feel of the main Jakarta Site. This is perfectly ok with us as we allow our developers the freedom to innovate. </p> <p> The jakarta-site2 module uses Anakia to do the XML->HTML transformations. Therefore, it is highly recommended that you read the Anakia <a href="/velocity/anakia.html">documentation</a> in order to get an overview of what you are dealing with (it really is quite simple as you will soon discover). </p> </blockquote> </p> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#525D76"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Modification of the Main Site Web Pages"><strong>Modification of the Main Site Web Pages</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> People who have accounts on apache.org can check in their changes to the jakarta-site2 module directly. If you get an error such as "Access denied: Insufficient Karma", then please send email to the [EMAIL PROTECTED] mailing list and we will grant you the appropriate access. If you do not have an account, then please feel free to send patches (<strong>against the .xml files and not the .html files!</strong>) to the [EMAIL PROTECTED] mailing list. </p> <p> You should edit the .xml files and then run build.sh. After you have done that, you should check in both the .xml files and the .html files. Once your changes have been checked in, you can do the following: </p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre> cd /www/jakarta.apache.org cvs update index.html cd site cvs update </pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> <p> This will cause the files checked into the jakarta-site2/docs directory to be checked out and updated on the live website. </p> </blockquote> </p> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#525D76"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Creating Web Pages For A (New) Project The Anakia Way"><strong>Creating Web Pages For A (New) Project The Anakia Way</strong></a> </font> </td></tr> <tr><td> <blockquote> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Using the jakarta-site2 module as a dependency"><strong>Using the jakarta-site2 module as a dependency</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> If you would like to use the jakarta-site2 module as a dependency for your project, here are the instructions for how to do that. The benefit of using it as a dependency is that you will be able to easily adopt the look and feel of the entire Jakarta website while being able to continue to have control over your own project's documentation navigation. It is the recommended, but optional way to develop documentation for projects hosted under the main Jakarta Project. </p> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Doing it your way"><strong>Doing it your way</strong></a> </font> </td></tr> <tr><td> <blockquote> <p>For reasons of expediency, you might be tempted to do things in your own way. Once you know HTML who needs Anakia, right? This is the incorrect approach but we will explore it so that the basic steps for updating your site on Jakarta become clearer. </p> <p>Assuming your project is called <em>myproject</em>, here are steps you should follow:</p> <ol> <li>Logon to the machine hosting the Jakarta web site.</li> <li>Create a directory named <code>myproject</code> under the <code>/www/jakarta.apache.org/</code> directory.</li> <li>Copy your HTML files under the newly created directory.</li> <li>That's it!</li> </ol> <p>The new project's web-pages should be accessible under <code>http://jakarta.apache.org/myproject</code>. </p> <p>The important point to remember is that <em>you are responsible for updating your project pages</em>. This statement remains true even if you switch to the recommended procedure described below.</p> <p>If you decide to place your project's web pages under CVS control, then the pages should pertain to your project's CVS module and <b>not</b> to the <code>jakarta-site2</code> module. For example, the contents of <code>/www/jakarta.apache.org/regexp/CVS/Repository</code> refer to <code>jakarta-regexp/docs</code> and in no way to the <code>jakarta-site2</code> module. Ask for help if you don't see what we are talking about.</p> <p>There are several problems with the do-it-your-way approach we have just outlined. First, the <code>myproject</code> pages are not linked to from the other Jakarta project pages. Your project is just dangling off Jakarta. Second, your web-pages do not follow the same look-and-feel as the other Jakarta projects. You can spend many hours trying to imitate the same look and feel. However, the Jakarta look-and-feel might change in the future. What will you do then? The solution is described below. Read on.</p> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="How To: Get things from CVS"><strong>How To: Get things from CVS</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> Check out the jakarta-site2 module into a directory that is "next" to your current project directory. </p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre> cd /projects cvs -d /home/cvs login cvs -d /home/cvs co jakarta-site2 cvs -d /home/cvs co jakarta-velocity <-- example other project </pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> <p>Your directory structure should then look something like this:</p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre> /projects /jakarta-site2 /jakarta-myproject /jakarta-velocity /jakarta-tomcat </pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="How To: From the included example"><strong>How To: From the included example</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> The jakarta-site2 module has an /examples directory. Within there is a jakarta-myproject directory that you can copy into your /projects directory. This directory has everything that you need to get started with the documentation portion of your project. Essentially, it contains all of the files and configuration that is documented below. </p> <p> Once you have copied the directory into /projects, you should read the instructions below to get a feeling for where everything is and how things are configured. </p> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="How To: From Scratch"><strong>How To: From Scratch</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> You should first create a directory structure within your project that can be used to store your documentation: </p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre> /projects /jakarta-myproject/ /build.sh <-- Your Ant build.sh file /build.xml <-- Your Ant build.xml file /docs/ <-- This is where the generated .html files will go. Your images and other resources will also end up in here. /xdocs/ <-- This is where your source .xml files will go. /images/ <-- This is where your images will go. /stylesheets/ <-- This is where your project.xml and optionally, your style.vsl will go. /project.xml <-- Your project.xml file. See below. /velocity.properties <-- A copy of the velocity.properties file. See below. </pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> <p> Copy the project.xml file from the jakarta-site2/xdocs/stylesheets/ directory into your jakarta-myproject/xdocs/stylesheets/ directory and modify it as needed to reflect the navigation needs of your project. If you are going to provide links to other projects within the Jakarta project, make sure to make their href attribute based on the "document root". For example, if your project links to the Ant project, then the href should be something like this: href="/ant/index.html" </p> <p> You will need to make a copy of the velocity.properties file from the jakarta- site2 module. Place it into the xdocs directory as outlined above. Within the file, you should modify the property shown below to point to the stylesheets directory within the jakarta-site2 directory. The path is relative to where the build.sh script is run from. This tells Velocity where to look for the style.vsl file. Since you want the same look and feel as the Jakarta website, you should at least start off by using this file. </p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre> resource.loader.1.resource.path = ../jakarta-site2/xdocs/stylesheets </pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> <p> Assuming that you are using <a href="/ant/index.html">Ant</a> as your build tool for your project, you should then be able to copy/paste the appropriate targets from the jakarta-site2/build.xml file into your own build.xml file for your project. You will need to make sure that the jar files in the jakarta-site2/lib directory are also added into your classpath in your build.sh script. The reason is that Ant does not have a way (that I know of) to add files to the classpath based on a conditional set of requirements. In other words, you want to allow people to build the rest of your project, but you do not want to require your users to have the jakarta-site2 module checked out in order to do so. You only want them to have to check out the jakarta-site2 module if they are going to build their documentation. Unfortunately, this isn't currently possible with Ant, therefore you need to specify the jakarta-site2 .jar files in the build.sh classpath using the examples below... </p> <p> Below is the stuff you should add to your build.xml file. Please note that the path to the docs.src and docs.dest would be relative to the directory where the build.sh script is run from. </p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre> <property name="docs.src" value="./xdocs"/> <property name="docs.dest" value="./docs"/> <target name="prepare"> <available classname="org.apache.velocity.anakia.AnakiaTask" property="AnakiaTask.present"/> </target> <target depends="prepare" name="prepare-error" unless="AnakiaTask.present"> <echo> AnakiaTask is not present! Please check to make sure that velocity.jar is in your classpath. </echo> </target> <target name="docs" depends="prepare-error" if="AnakiaTask.present"> <taskdef name="anakia" classname="org.apache.velocity.anakia.AnakiaTask"/> <anakia basedir="${docs.src}" destdir="${docs.dest}/" extension=".html" style="./site.vsl" projectFile="stylesheets/project.xml" excludes="**/stylesheets/** empty.xml" includes="**/*.xml" lastModifiedCheck="true" velocityPropertiesFile="${docs.src}/velocity.properties"> </anakia> <copy todir="${docs.dest}/images" filtering="no"> <fileset dir="${docs.src}/images"> <include name="**/*.gif"/> <include name="**/*.jpeg"/> <include name="**/*.jpg"/> </fileset> </copy> </target></pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> <p> Below is an example of what your build.sh file should look like. What is important to note is that it is building up the CLASSPATH to find the .jar files for Anakia. Because it adds itself to the CLASSPATH after you do, any .jar files in your project that duplicate the .jar files needed by Anakia will take precedence. So, if there are issues with running Anakia with a combined classpath, you can opt to make a separate build script for running Anakia with its own CLASSPATH. </p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre>#!/bin/sh if [ "$JAVA_HOME" = "" ] ; then echo You must set JAVA_HOME to point at your Java Development Kit directory exit 1 fi # convert the existing path to unix if [ "$OSTYPE" = "cygwin32" ] || [ "$OSTYPE" = "cygwin" ] ; then CLASSPATH=`cygpath --path --unix "$CLASSPATH"` fi # Add in your .jar files first for i in ./lib/*.jar do CLASSPATH=$CLASSPATH:"$i" done # Add in the jakarta-site2 library files for i in ../jakarta-site2/lib/*.jar do CLASSPATH=$CLASSPATH:"$i" done # convert the unix path to windows if [ "$OSTYPE" = "cygwin32" ] || [ "$OSTYPE" = "cygwin" ] ; then CLASSPATH=`cygpath --path --windows "$CLASSPATH"` fi BUILDFILE=build.xml #echo $CLASSPATH java $ANT_OPTS -classpath "$CLASSPATH" org.apache.tools.ant.Main \ -Dant.home=$ANT_HOME \ -buildfile ${BUILDFILE} \ "$@"</pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Constructing your documentation"><strong>Constructing your documentation</strong></a> </font> </td></tr> <tr><td> <blockquote> <p>Now, in order to build your website, all you need to do is:</p> <div align="left"> <table cellspacing="4" cellpadding="0" border="0"> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#ffffff"><pre>cd jakarta-myproject ./build.sh docs</pre></td> <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> <tr> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td> </tr> </table> </div> <p> The documentation will then be generated into the jakarta-myproject/docs directory. </p> <p> If you take a look at the project.xml file within your xdocs/stylesheets directory, you will notice that it is the side navigation portion of the website. If you want your project logo to appear in the upper right corner next to the Jakarta Project logo, then un-comment the <logo> tag and specify the path to the logo in your images directory or a full URI to your logo. If your project has its own navigation needs, simply modify the <menu> tags and place in your own navigation elements. </p> <p> Within your xdocs directory is also a sample index.xml file. It shows the basic things that you need to modify to create your own page. You can embed whatever HTML you want into this file so long as it conforms to the XHTML specification (essentially, these are XML files so you need to embed XHTML in order for them to be parsed correctly). You can look at the other .xml files within the jakarta-site2 module for more examples of the different things you can do. If there are errors in your .xml file, they will be reported in the output of running your build.sh script. </p> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#828DA6"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Tag Documentation"><strong>Tag Documentation</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> The list of tags which you can use within your XML/XHTML file are documented on another <a href="./jakarta-site-tags.html">page</a>. </p> </blockquote> </td></tr> <tr><td><br/></td></tr> </table> </blockquote> </p> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#525D76"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Modifying Web Pages For An Existing Project"><strong>Modifying Web Pages For An Existing Project</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> If your project doesn't use Anakia then you should stop reading this and start reading the project's documents describing how to build their web pages. From now on, we'll assume that you want to make some improvements to pages created the standard way. </p> <p> If you're not a committer, then you're almost done. You should submit patches for project web pages to the development list in the same way as any other patch. Make sure that you patch the xml files in the xdocs directory rather than the html files in the docs directory. That's it. Only committers need to read on. </p> <p> The project's web pages are stored under <code>/www/jakarta.apache.org/mySubProject</code>. This directory should be just a check out of the project's <code>docs</code> directory. So, you can update the live web pages by updating that directory from CVS. Here's the checklist to do just that: <ol> <li> generate documentation (project specific though most use anakia) </li> <li> commit to CVS </li> <li> SSH to jakarta.apache.org </li> <li> cd /www/jakarta.apache.org/mySubProject</li> <li> cvs login (This is because <code>anoncvs</code> requires a password. Note that this only needs to happen the <strong>FIRST</strong> time you update the website.) </li> <li> cvs up </li> <li> make sure that you have the correct permissions set for all the files you updated </li> <li> enjoy your new pages! </li> </ol> </p> <p> It is possible that you might find that you don't have permission to do 3. If this happens, just ask someone in the project who does or drop a note to the [EMAIL PROTECTED] mailing list and someone will finish off the update for you. </p> </blockquote> </p> </td></tr> <tr><td><br/></td></tr> </table> <table border="0" cellspacing="0" cellpadding="2" width="100%"> <tr><td bgcolor="#525D76"> <font color="#ffffff" face="arial,helvetica,sanserif"> <a name="Feedback"><strong>Feedback</strong></a> </font> </td></tr> <tr><td> <blockquote> <p> If there are parts of this document that are confusing to you or there are errors in the Anakia portion of the jakarta-site2 module, please send feedback to the [EMAIL PROTECTED] mailing list. Please try to give a detailed description of what is confusing so that I can update the page to make things more clear. </p> </blockquote> </p> </td></tr> <tr><td><br/></td></tr> </table> </td> </tr> <!-- FOOTER --> <tr><td colspan="2"> <hr noshade="" size="1"/> </td></tr> <tr><td colspan="2"> <div align="center"><font color="#525D76" size="-1"><em> Copyright © 1999-2002, Apache Software Foundation </em></font></div> </td></tr> </table> </body> </html> <!-- end the processing -->
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
![http://jakarta.apache.org/images/jakarta-logo.gif"](http://jakarta.apache.org/images/jakarta-logo.gif"){kind=link}