jakarta-site-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@locus.apache.org
Subject cvs commit: jakarta-site2/xdocs/site jakarta-site2.xml news.xml
Date Mon, 27 Nov 2000 03:21:13 GMT
jon         00/11/26 19:21:12

  Modified:    xdocs/site news.xml
  Added:       xdocs/site jakarta-site2.xml
  Log:
  added news about the site and also jakarta-site2 documentation
  
  Revision  Changes    Path
  1.2       +18 -0     jakarta-site2/xdocs/site/news.xml
  
  Index: news.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-site2/xdocs/site/news.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- news.xml	2000/11/25 21:36:36	1.1
  +++ news.xml	2000/11/27 03:21:12	1.2
  @@ -9,6 +9,24 @@
   <body>
   
     <section name="News &amp; Status">
  +
  +<h3>11-26-00 - New Website Design</h3>
  +
  +<p>We finally have a new website design! The old one was getting stale and we 
  +needed to update our look. We also have a new <a href="/site/jakarta-
  +site2.html">process</a> that allows our sub-projects to easily adopt the same

  +look and feel as our primary site. The site is now being generated from XML 
  +files using <a href="/velocity/anakia.html">Anakia</a> 
  +as the transformation engine. Thanks to the magic of the <a 
  +href="http://www.apache.org/docs/mod/mod_alias.html#redirectmatch">RedirectMatch 
  +</a> rule, all of our old links should also work as well. If you find any 
  +problems with the site, everything is checked into <a 
  +href="/cvsweb/index.cgi/jakarta-site2/">CVS</a> and we 
  +would appreciate <a href="./contact.html">sending</a> us patches to fix the

  +problems.</p>
  +
  +<hr noshade="" size="1"/>
  +
   <h3>7-23-00 - Jakarta-ORO Project Now Available</h3>
   
   <p>A couple months ago we announced that Daniel F. Savarese would be donating his

  
  
  
  1.1                  jakarta-site2/xdocs/site/jakarta-site2.xml
  
  Index: jakarta-site2.xml
  ===================================================================
  <?xml version="1.0"?>
  <document>
  
    <properties>
      <author email="jon@latchkey.com">Jon S. Stevens</author>
      <title>Using the jakarta-site2 module as a dependency</title>
    </properties>
  
  <body>
  
    <section name="Using the jakarta-site2 module as a dependency">
  <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.
  </p>
  <p>
  Currently, 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>
    </section>
  
    <section name="How To: Get things from CVS">
  <p>
  Check out the jakarta-site2 module into a directory that is "next" to your 
  current project directory.
  </p>
  
  <source>
  cd /projects
  cvs -d /home/cvs login
  cvs -d /home/cvs co jakarta-site2
  cvs -d /home/cvs co jakarta-velocity &lt;-- example other project
  </source>
  
  <p>Your directory structure should then look something like this:</p>
  
  <source>
  /projects
      /jakarta-site2
      /jakarta-myproject
      /jakarta-velocity
      /jakarta-tomcat
  </source>
    </section>
  
    <section name="How To: From the included example">
    <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>    
    </section>
  
    <section name="How To: From Scratch">
  
  <p>You should first create a directory structure within your project that can be used

  to store your documentation:</p>
  
  <source>
  /projects
      /jakarta-myproject/
          /build.sh           &lt;-- Your Ant build.sh file
          /build.xml          &lt;-- Your Ant build.xml file
          /docs/              &lt;-- This is where the generated .html
                                     files will go. Your images and other
                                     resources will also end up in here.
          /xdocs/             &lt;-- This is where your source .xml files
                                     will go.
              /images/        &lt;-- This is where your images will go.
              /stylesheets/   &lt;-- This is where your project.xml and
                                    optionally, your style.vsl will go.
                  /project.xml &lt;-- Your project.xml file. See below.
              /velocity.properties &lt;-- A copy of the velocity.properties
                                         file. See below.
  </source>
  
  <p>
  Copy the project.xml file from the jakarta-site2/xdocs/stylesheets/ directory 
  into your jakarta-myproject/xdocs/stylesheets/ directory.
  </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>
  
  <source>
  template.loader.1.template.path = ../jakarta-site2/xdocs/stylesheets
  </source>
  
  <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 for your build.sh script. 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>
  
  <source><![CDATA[
      <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>]]></source>
  
  <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 seperate build script for running Anakia with its own CLASSPATH.
  </p>
  
  <source><![CDATA[#!/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} \
                   "$@"]]></source>
  
    </section>
  
      <section name="Constructing your documentation">
      <p>Now, in order to build your website, all you need to do is:</p>
      
      <source>cd jakarta-myproject
      ./build.sh docs</source>
  
      <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 uncomment the &lt;logo&gt; 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 
      &lt;menu&gt; 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>
      </section>
  
  </body>
  </document>
  
  
  
  

Mime
View raw message