|
|
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.
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.
The purpose of Logging Services is to develop 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.
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 getting involved 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.
The rest of this page describes how to use the standard
logging-site module that we use to create the main
Logging Services web-site, and many of the sub-project sites.
The logging-site 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.
Each Logging Services sub-project has the choice of how they generate
their website and documentation. The "encouraged" way is to use the
logging-site module as the basis for generating the
documentation. The provides a consistent look and feel for all of the
Logging Services web-site 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.
The logging-site module uses Anakia to do the XML->HTML
transformations. Therefore, it is highly recommended that you read the
Anakia documentation
in order to get an overview of what you are dealing with (it really is
quite simple as you will soon discover).
logging-site module as a dependency
If you would like to use the logging-site 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.
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.
Assuming your project is called myproject, here are steps you should follow:
myproject under the
/www/logging.apache.org/ directory.The new project's web-pages should be accessible under
http://logging.apache.org/myproject.
The important point to remember is that you are responsible for updating your project pages. This statement remains true even if you switch to the recommended procedure described below.
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 not to the logging-site module. For various
reasons, the log4j web-site files are copied to our Web server machine
using scp and not CVS, so we cannot user log4j as an
example here.
However, the jakarta-regexp project uses CVS to copy
files to the server. Note that the contents of
/www/jkarta.apache.org/regexp/CVS/Repository refer to
jakarta-regexp/docs and in no way to the jakarta
-site2 module. Ask for help if you don't see what we are
talking about.
There are several problems with the do-it-your-way approach we have
just outlined. First, the myproject 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.
Check out the logging-site module into a directory that
is "next" to your current project directory.
cd /projects cvs -d /home/cvs login cvs -d /home/cvs co logging-site cvs -d /home/cvs co logging-log4j <-- example other project
Your directory structure should then look something like this:
/projects
/logging-site
/logging-myproject
/logging-log4j
/logging-log4net
You should first create a directory structure within your project that can be used to store your documentation:
/projects
/logging-myproject/
/build.xml <-- Your Ant build.xml file
/docs/ <-- This is where the generated .html
files, images and other
resources will go.
/src/xdocs/ <-- This is where your source .xml
files will go.
/stylesheets/ <-- This is where your project.xml and
optional style.vsl will go.
/project.xml <-- Your project.xml file. See below.
Copy the project.xml file from the
logging-site/xdocs/stylesheets/ directory into your
logging-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 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"
Assuming that you are using Ant as your build tool for your project, we will now list the modifications to your build file:
<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>
<!-- ============================ -->
<!-- ======= New targets ======== -->
<!-- ============================ -->
<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="${docs.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>
Now, in order to build your website, all you need to do is:
cd logging-myproject ant site
The documentation will then be generated into the
logging-myproject/docs directory.
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
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.
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
logging-site 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.
People who have accounts on apache.org can check in their changes to
the logging-site module directly. If you get an error
such as "Access denied: Insufficient Karma", then please send email to
the general AT logging DOT apache DOT org mailing list
and we will grant you the appropriate access. If you do not have an
account, then please feel free to send patches (against the
.xml files and not the .html files!) to that same
mailinglist.
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:
cd /www/logging.apache.org cvs update index.html cd site cvs update
This will cause the files checked into the
logging-site/docs directory to be checked out and updated
on the live website.
If there are parts of this document that are confusing to you or there
are errors in the Anakia portion of the logging-site
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.
The current velocity style-sheets transform most elements with empty
bodies into their shorter form, supposed to be equivalent. In
particular, an html anchor such as <a
name="foobar"></a> will be transformed into
<a name="foobar"/>. The latter form very much
confuses browsers into thinking that the rest of the document is a URL
link. It even causes Internet Explorer version 6.0 to crash.
The workaround is to insert a single character between the start
tag and the end tag. For example, writing
<a name="foobar"> </a> instead
of <a name="foobar"></a> where the entity
  represents non-breaking space.