ceki 2004/01/23 10:04:30
Added: docs/site logging-site.html
src/xdocs/site logging-site.xml
Log:
Added a page explaining the maintenance of web-pages, includes
material for sub-projects
PR:
Obtained from:
Submitted by:
Reviewed by:
Revision Changes Path
1.1 logging-site/docs/site/logging-site.html
Index: logging-site.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 -->
<!-- ====================================================================== -->
<!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
<!-- 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="jon.AT.latchkey.DOT.com">
<meta name="author" value="Ted Husted">
<meta name="email" value="husted.AT.apache.DOT.org">
<meta name="author" value="Ted Husted">
<meta name="email" value="ceki.AT.apache.DOT.org">
<link href="../css/site.css" rel="stylesheet" type="text/css"/>
<title>Logging Services - About the Logging Services web-site</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table id="main" border="0" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td colspan="2">
<a href="http://logging.apache.org";>
<img src="http://logging.apache.org/images/ls-logo.jpg"; align="left"
border="0"/>
</a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4" cellpadding="0">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td width="20%" valign="top" nowrap="true">
<!--
============================================================ -->
<table id="navbar" width="160" border="0" cellspacing="2" cellpadding="1">
<tr >
<td><strong>About Logging Services</strong></td>
</tr>
<tr><td><small> <a
href="../index.html">Welcome</a>
</small></td></tr>
<tr><td><small> <a
href="../site/news.html">News</a>
</small></td></tr>
<tr bgcolor="#999999">
<td><html:img page="/images/space2.gif" height="1"></html:img></td>
</tr>
<tr >
<td><strong>Projects</strong></td>
</tr>
<tr><td><small> <a href="..">log4cxx</a>
</small></td></tr>
<tr><td><small> <a
href="../log4j/docs">log4j</a>
</small></td></tr>
<tr><td><small> <a href="..">log4net</a>
</small></td></tr>
<tr><td><small> <a href="..">log4php</a>
</small></td></tr>
<tr bgcolor="#999999">
<td><html:img page="/images/space2.gif" height="1"></html:img></td>
</tr>
<tr >
<td><strong>Information</strong></td>
</tr>
<tr><td><small> <a
href="../site/mission-statement.html">Mission statement</a>
</small></td></tr>
<tr><td><small> <a
href="../site/bylaws.html">Bylaws</a>
</small></td></tr>
<tr><td><small> <a
href="../LICENSE">License</a>
</small></td></tr>
<tr><td><small> <a
href="../site/who-we-are.html">Who we are</a>
</small></td></tr>
<tr bgcolor="#999999">
<td><html:img page="/images/space2.gif" height="1"></html:img></td>
</tr>
<tr >
<td><strong>Support</strong></td>
</tr>
<tr><td><small> <a
href="../site/cvs-repositories.html">CVS Repositories</a>
</small></td></tr>
<tr><td><small> <a
href="../site/mailing-lists.html">Mailing Lists</a>
</small></td></tr>
<tr><td><small> <a
href="../site/bugreport.html">Bug Reporting</a>
</small></td></tr>
<tr bgcolor="#999999">
<td><html:img page="/images/space2.gif" height="1"></html:img></td>
</tr>
<tr >
<td><strong>Reference</strong></td>
</tr>
<tr><td><small> <a
href="../site/logging-site.html">Web-site maintenance</a>
</small></td></tr>
</table>
</td>
<td width="80%" align="left" valign="top">
<div style="position: relative; left: 8px;">
<h2>What is
the Logging Services web site?</h2>
<p>
The Logging Services web-site is a container for the various products
hosted by the project. The development team for each product maintains
their area of the web-site, along with rest of the product's
documentation.
</p>
<p>
The main area of the Logging Services web-site provides some
background information about the project, and links to common
resources, like the bug database and mailing lists.
</p>
<h2>Why isn't the Logging Services web-site more user friendly?"</h2>
<p>
The purpose of Logging Services is to <b>develop</b> software, not
market it. The web-site is functional and easy to maintain, since that
is what the project requires. We do not have paid staff to maintain a
consumer-orientated web-site. The development teams do the best job
they can with maintaining the web-site for their product, but it is
not reasonable to expect the same group of volunteers to both create
great code and slick web-sites.
</p>
<p>
All of our teams are always looking for people to help with the
documentation and web-site. Getting involved with these aspects of the
product is no different than <a
href="http://jakarta.apache.org/site/getinvolved.html";>getting
involved</a> with the actual code. Find something that needs fixing,
fix it, submit a patch. Rinse and repeat until someone recognizes your
hard work, and invites you to join the team.
</p>
<p>
The rest of this page describes how to use the standard
<code>logging-site</code> module that we use to create the main
Logging Services web-site, and many of the sub-project sites.
</p>
<h2>What is the 'logging-site' Module"</h2>
<p>
The <code>logging-site</code> 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 Logging Services sub-project has the choice of how they generate
their website and documentation. The "encouraged" way is to use the
<code>logging-site</code> module as the basis for generating the
documentation. The provides a consistent look and feel for all of the
Logging Services 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 Logging Services Site. This is perfectly ok
with us as we allow our developers the freedom to innovate.
</p>
<p>
The <code>logging-site</code> module uses Anakia to do the XML->HTML
transformations. Therefore, it is highly recommended that you read the
Anakia <a href="http://jakarta.apache.org/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>
<h2>Using the <code>logging-site</code> module as a dependency</h2>
<p>
If you would like to use the <code>logging-site</code> 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 Logging Services
website while being able to continue to have control over your own
project's documentation navigation. It is the recommended, but
non-mandatory way to develop documentation for projects hosted under
the main Logging Services Project.
</p>
<h2>Doing it your way</h2>
<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 Logging Services 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 Logging Services web-site.</li>
<li>Create a directory named <code>myproject</code> under the
<code>/www/logging.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://logging.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 use CVS to copy your project's web pages to the
web-server, then the pages should pertain to your project's CVS module
and <b>not</b> to the <code>logging-site</code> module. For various
reasons, the log4j web-site files are copied to our Web server machine
using <code>scp</code> and not CVS, so we cannot user log4j as an
example here.
</p>
<p>However, the <code>jakarta-regexp</code> project uses CVS to copy
files to the server. Note that the contents of
<code>/www/jkarta.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 Logging Services project pages. Your project is
just dangling off Logging Services. Second, your web-pages do not
follow the same look-and-feel as the other Logging Services
projects. You can spend many hours trying to imitate the same look and
feel. However, the Logging Services look-and-feel might change in the
future. What will you do then? The solution is described below. Read
on.</p>
<h2>How To: Get things from CVS</h2>
<p>
Check out the <code>logging-site</code> 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 logging-site
cvs -d /home/cvs co logging-log4j <-- 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
/logging-site
/logging-myproject
/logging-log4j
/logging-log4net
</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>
<h3>How To: From Scratch</h3>
<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
/Logging Services-myproject/
/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.
/src/xdocs/ <-- This is where your source .xml files
will go.
/stylesheets/ <-- This is where your project.xml and
optionally, your style.vsl will go.
/project.xml <-- Your project.xml 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 <code>project.xml</code> file from the
<code>logging-site/xdocs/stylesheets/</code> directory into your
<ocde>logging-myproject/xdocs/stylesheets/</ocde> 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 Logging
Services project, make sure to make their href attribute based on the
"document root". For example, if your project links to the log4j
project, then the href should be something like this:
href="/log4j/index.html"
</p>
<p>
Assuming that you are using <a href="http://ant.apache.org";>Ant</a> as
your build tool for your project, we will now list the modifications
to your build file.
<source><![CDATA[
<property name="docs.src" value="./src/xdocs"/>
<property name="docs.dest" value="./docs"/>
<property name="logging-site"
value="your copy of logging-site dir"/>
<!-- Construct classpath for building the html pages-->
<path id="site.classpath">
<fileset dir="${logging-site}/lib">
<include name="*.jar"/>
</fileset>
</path>
<target name="prepareSite">
<available classname="org.apache.velocity.anakia.AnakiaTask"
property="AnakiaTask.present">
<classpath refid="site.classpath"/>
</available>
</target>
<target name="checkSite" depends="prepareSite" unless="AnakiaTask.present">
<echo>
AnakiaTask is not present! Please check to make sure that
velocity.jar is in your classpath.
</echo>
</target>
<target name="site" depends="checkSite" if="AnakiaTask.present">
<taskdef name="anakia" classname="org.apache.velocity.anakia.AnakiaTask">
<classpath refid="site.classpath"/>
</taskdef>
<mkdir dir="${docs.dest}/css"/>
<copy file="${logging-site}/docs/css/site.css"
tofile="${docs.dest}/css/site.css"/>
<anakia basedir="${xdocs.src}" destdir="${docs.dest}/"
extension=".html"
style="site.vsl"
projectFile="stylesheets/project.xml"
excludes="**/stylesheets/**, empty.xml"
includes="**/*.xml"
lastModifiedCheck="true"
templatePath="${logging-site}/src/xdocs/stylesheets">
</anakia>
</target>]]></source>
</p>
<h2>Constructing your documentation</h2>
<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 logging-myproject
ant site</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
<code>logging-myproject/docs</code> directory.
</p>
<p>
If you take a look at the <code>project.xml</code> file within
your <code>xdocs/stylesheets</code> 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
Logging Services 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
<code>logging-site</code> 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>
<h2>Modification of the Logging Services web-site itself</h2>
<p>
People who have accounts on apache.org can check in their changes to
the <code>logging-site</code> module directly. If you get an error
such as "Access denied: Insufficient Karma", then please send email to
the <code>general AT logging DOT apache DOT org</code> 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 that same
mailinglist.
</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/logging.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
<code>logging-site/docs</code> directory to be checked out and updated
on the live website.
</p>
<h2>Feedback</h2>
<p>
If there are parts of this document that are confusing to you or there
are errors in the Anakia portion of the <code>logging-site</code>
module, please send feedback to the "general AT logging DOT apache DOT
org" mailing list. Please try to give a detailed description of what
is confusing so that we can update the page to make things clearer.
</p>
</div>
</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-2004, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->
1.1 logging-site/src/xdocs/site/logging-site.xml
Index: logging-site.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="jon.AT.latchkey.DOT.com">Jon S. Stevens</author>
<author email="husted.AT.apache.DOT.org">Ted Husted</author>
<author email="ceki.AT.apache.DOT.org">Ted Husted</author>
<title>About the Logging Services web-site</title>
</properties>
<body>
<h2>What is the Logging Services web site?</h2>
<p>
The Logging Services web-site is a container for the various products
hosted by the project. The development team for each product maintains
their area of the web-site, along with rest of the product's
documentation.
</p>
<p>
The main area of the Logging Services web-site provides some
background information about the project, and links to common
resources, like the bug database and mailing lists.
</p>
<h2>Why isn't the Logging Services web-site more user friendly?"</h2>
<p>
The purpose of Logging Services is to <b>develop</b> software, not
market it. The web-site is functional and easy to maintain, since that
is what the project requires. We do not have paid staff to maintain a
consumer-orientated web-site. The development teams do the best job
they can with maintaining the web-site for their product, but it is
not reasonable to expect the same group of volunteers to both create
great code and slick web-sites.
</p>
<p>
All of our teams are always looking for people to help with the
documentation and web-site. Getting involved with these aspects of the
product is no different than <a
href="http://jakarta.apache.org/site/getinvolved.html";>getting
involved</a> with the actual code. Find something that needs fixing,
fix it, submit a patch. Rinse and repeat until someone recognizes your
hard work, and invites you to join the team.
</p>
<p>
The rest of this page describes how to use the standard
<code>logging-site</code> module that we use to create the main
Logging Services web-site, and many of the sub-project sites.
</p>
<h2>What is the 'logging-site' Module"</h2>
<p>
The <code>logging-site</code> 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 Logging Services sub-project has the choice of how they generate
their website and documentation. The "encouraged" way is to use the
<code>logging-site</code> module as the basis for generating the
documentation. The provides a consistent look and feel for all of the
Logging Services 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 Logging Services Site. This is perfectly ok
with us as we allow our developers the freedom to innovate.
</p>
<p>
The <code>logging-site</code> module uses Anakia to do the XML->HTML
transformations. Therefore, it is highly recommended that you read the
Anakia <a
href="http://jakarta.apache.org/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>
<h2>Using the <code>logging-site</code> module as a dependency</h2>
<p>
If you would like to use the <code>logging-site</code> 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 Logging Services
website while being able to continue to have control over your own
project's documentation navigation. It is the recommended, but
non-mandatory way to develop documentation for projects hosted under
the main Logging Services Project.
</p>
<h2>Doing it your way</h2>
<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 Logging Services 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 Logging Services web-site.</li>
<li>Create a directory named <code>myproject</code> under the
<code>/www/logging.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://logging.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 use CVS to copy your project's web pages to the
web-server, then the pages should pertain to your project's CVS module
and <b>not</b> to the <code>logging-site</code> module. For various
reasons, the log4j web-site files are copied to our Web server machine
using <code>scp</code> and not CVS, so we cannot user log4j as an
example here.
</p>
<p>However, the <code>jakarta-regexp</code> project uses CVS to copy
files to the server. Note that the contents of
<code>/www/jkarta.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 Logging Services project pages. Your project is
just dangling off Logging Services. Second, your web-pages do not
follow the same look-and-feel as the other Logging Services
projects. You can spend many hours trying to imitate the same look and
feel. However, the Logging Services look-and-feel might change in the
future. What will you do then? The solution is described below. Read
on.</p>
<h2>How To: Get things from CVS</h2>
<p>
Check out the <code>logging-site</code> 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 logging-site
cvs -d /home/cvs co logging-log4j <-- example other project
</source>
<p>Your directory structure should then look something like this:</p>
<source>
/projects
/logging-site
/logging-myproject
/logging-log4j
/logging-log4net
</source>
<h3>How To: From Scratch</h3>
<p>
You should first create a directory structure within your project that
can be used to store your documentation:
</p>
<source>
/projects
/Logging Services-myproject/
/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.
/src/xdocs/ <-- This is where your source .xml files
will go.
/stylesheets/ <-- This is where your project.xml and
optionally, your style.vsl will go.
/project.xml <-- Your project.xml file. See below.
</source>
<p>
Copy the <code>project.xml</code> file from the
<code>logging-site/xdocs/stylesheets/</code> directory into your
<ocde>logging-myproject/xdocs/stylesheets/</ocde> 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 Logging
Services project, make sure to make their href attribute based on the
"document root". For example, if your project links to the log4j
project, then the href should be something like this:
href="/log4j/index.html"
</p>
<p>
Assuming that you are using <a href="http://ant.apache.org";>Ant</a> as
your build tool for your project, we will now list the modifications
to your build file.
<source><![CDATA[
<property name="docs.src" value="./src/xdocs"/>
<property name="docs.dest" value="./docs"/>
<property name="logging-site"
value="your copy of logging-site dir"/>
<!-- Construct classpath for building the html pages-->
<path id="site.classpath">
<fileset dir="${logging-site}/lib">
<include name="*.jar"/>
</fileset>
</path>
<target name="prepareSite">
<available classname="org.apache.velocity.anakia.AnakiaTask"
property="AnakiaTask.present">
<classpath refid="site.classpath"/>
</available>
</target>
<target name="checkSite" depends="prepareSite" unless="AnakiaTask.present">
<echo>
AnakiaTask is not present! Please check to make sure that
velocity.jar is in your classpath.
</echo>
</target>
<target name="site" depends="checkSite" if="AnakiaTask.present">
<taskdef name="anakia" classname="org.apache.velocity.anakia.AnakiaTask">
<classpath refid="site.classpath"/>
</taskdef>
<mkdir dir="${docs.dest}/css"/>
<copy file="${logging-site}/docs/css/site.css"
tofile="${docs.dest}/css/site.css"/>
<anakia basedir="${xdocs.src}" destdir="${docs.dest}/"
extension=".html"
style="site.vsl"
projectFile="stylesheets/project.xml"
excludes="**/stylesheets/**, empty.xml"
includes="**/*.xml"
lastModifiedCheck="true"
templatePath="${logging-site}/src/xdocs/stylesheets">
</anakia>
</target>]]></source>
</p>
<h2>Constructing your documentation</h2>
<p>Now, in order to build your website, all you need to do is:</p>
<source>cd logging-myproject
ant site</source>
<p>
The documentation will then be generated into the
<code>logging-myproject/docs</code> directory.
</p>
<p>
If you take a look at the <code>project.xml</code> file within
your <code>xdocs/stylesheets</code> 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
Logging Services 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
<code>logging-site</code> 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>
<h2>Modification of the Logging Services web-site itself</h2>
<p>
People who have accounts on apache.org can check in their changes to
the <code>logging-site</code> module directly. If you get an error
such as "Access denied: Insufficient Karma", then please send email to
the <code>general AT logging DOT apache DOT org</code> 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 that same
mailinglist.
</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/logging.apache.org
cvs update index.html
cd site
cvs update
</source>
<p>
This will cause the files checked into the
<code>logging-site/docs</code> directory to be checked out and updated
on the live website.
</p>
<h2>Feedback</h2>
<p>
If there are parts of this document that are confusing to you or there
are errors in the Anakia portion of the <code>logging-site</code>
module, please send feedback to the "general AT logging DOT apache DOT
org" mailing list. Please try to give a detailed description of what
is confusing so that we can update the page to make things clearer.
</p>
</body>
</document>
![http://logging.apache.org/images/ls-logo.jpg"](http://logging.apache.org/images/ls-logo.jpg"){kind=link}