husted 02/01/16 14:29:25
Added: xdocs/site jakarta-site2b.xml
Log:
Post proposed revised version, submitted by robert burrell donkin
Revision Changes Path
1.1 jakarta-site2/xdocs/site/jakarta-site2b.xml
Index: jakarta-site2b.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<author email="[EMAIL PROTECTED]">robert burrell donkin</author>
<title>Using the jakarta-site2 module as a dependency</title>
</properties>
<body>
<section name="What is this?">
<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>
</section>
<section name="Modification of the Main Site Web Pages">
<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>
<source>
cd /www/jakarta.apache.org
cvs update index.html
cd site
cvs update
</source>
<p>
This will cause the files checked into the jakarta-site2/docs directory
to be checked out and updated on the live website.
</p>
</section>
<section name="Creating Web Pages For A (New) Project The Anakia Way">
<subsection 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. It is
the recommended, but optional way to develop documentation for projects
hosted under the main Jakarta Project.
</p>
</subsection>
<subsection name="Doing it your way">
<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>
</subsection>
<subsection 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 <-- 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>
</subsection>
<subsection 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>
</subsection>
<subsection 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 <-- 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.
</source>
<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>
<source>
resource.loader.1.resource.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 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>
<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 separate 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>
</subsection>
<subsection 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 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>
</subsection>
<subsection name="Tag Documentation">
<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>
</subsection>
</section>
<section name="Modifying Web Pages For An Existing Project">
<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>
</section>
<section name="Feedback">
<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>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
