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 =================================================================== Logging Services - About the Logging Services web-site

What is the Logging Services web site?

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.

Why isn't the Logging Services web-site more user friendly?"

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.

What is the 'logging-site' Module"

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 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.

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).

Using the 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.

Doing it your way

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:

  1. Logon to the machine hosting the Logging Services web-site.
  2. Create a directory named myproject under the /www/logging.apache.org/ directory.
  3. Copy your HTML files under the newly created directory.
  4. That's it!

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.

How To: Get things from CVS

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
  

How To: From Scratch

You should first create a directory structure within your project that can be used to store your documentation:

  /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.
  

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. AnakiaTask is not present! Please check to make sure that velocity.jar is in your classpath. ]]>

Constructing your documentation

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.

Modification of the Logging Services web-site itself

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.

Feedback

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.


Copyright © 1999-2004, Apache Software Foundation
1.1 logging-site/src/xdocs/site/logging-site.xml Index: logging-site.xml =================================================================== Jon S. Stevens Ted Husted Ted Husted About the Logging Services web-site

What is the Logging Services web site?

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.

Why isn't the Logging Services web-site more user friendly?"

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.

What is the 'logging-site' Module"

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 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.

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).

Using the 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.

Doing it your way

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:

  1. Logon to the machine hosting the Logging Services web-site.
  2. Create a directory named myproject under the /www/logging.apache.org/ directory.
  3. Copy your HTML files under the newly created directory.
  4. That's it!

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.

How To: Get things from CVS

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

How To: From Scratch

You should first create a directory structure within your project that can be used to store your documentation:

/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.

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. AnakiaTask is not present! Please check to make sure that velocity.jar is in your classpath. ]]>

Constructing your documentation

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.

Modification of the Logging Services web-site itself

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.

Feedback

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.