logging-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c...@apache.org
Subject cvs commit: logging-site/src/xdocs/site logging-site.xml
Date Fri, 23 Jan 2004 18:04:30 GMT
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>&nbsp;&nbsp;    <a href="../index.html">Welcome</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <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>&nbsp;&nbsp;    <a href="..">log4cxx</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <a href="../log4j/docs">log4j</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <a href="..">log4net</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <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>&nbsp;&nbsp;    <a href="../site/mission-statement.html">Mission
statement</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <a href="../site/bylaws.html">Bylaws</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <a href="../LICENSE">License</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <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>&nbsp;&nbsp;    <a href="../site/cvs-repositories.html">CVS
Repositories</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <a href="../site/mailing-lists.html">Mailing
Lists</a>
  </small></td></tr>
                	 <tr><td><small>&nbsp;&nbsp;    <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>&nbsp;&nbsp;    <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-&gt;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 &lt;-- 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          &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.
          /src/xdocs/             &lt;-- This is where your source .xml files
                                     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.
  </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 &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
      <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 &#169; 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 &lt;-- 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          &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.
          /src/xdocs/             &lt;-- This is where your source .xml files
                                     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.
  </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 &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
      <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>
  
  
  
  

Mime
View raw message