ceki 01/03/13 10:56:29
Added: xdocs/site dirlayout.xml
docs/site dirlayout.html
Log:
An first attempt at a common directory structure as requested item 3.6 on the the
PMC agenda.
Revision Changes Path
1.1 jakarta-site2/xdocs/site/dirlayout.xml
Index: dirlayout.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Ceki Güulcü</author>
<title>Jakarta Directory Layout</title>
</properties>
<body>
<section name="Rationale">
<p>
Having a common directory layout would allow for users familiar with
one Jakarta project to immediately feel at home in another Jakarta
project. The advantages are analogous to adopting a site-wide
look-and-feel as jakarta-wide procedures strengthen the Jakarta brand.
</p>
<p>
The directory structure proposed below is not binding. We recognize
that the cost of changing an existing directory structure can be
high. However, we expect all projects to eventually move to the
proposed layout assuming that the migration can be accomplished with
reasonable effort. <b>The layout is subject to approval.</b>
</p>
</section>
<section name="Common Directory Layout">
<table>
<tr>
<th>Directory name</th>
<th>Content</th>
<th>Comment</th>
<th>Under CVS Control?</th>
</tr>
<tr>
<td>LICENSE</td>
<td>A copy of the Apache Public License</td>
<td>The LICENSE should be placed at a prominent location.</td>
<td>YES</td>
</tr>
<tr>
<td>src/</td>
<td>Source code.</td>
<td>If the source code contains only code in the Java language, then
the contents of the src/ directory should mirror the package
hierarchy. Otherwise, if the code contains a mix of languages, then
an extra directory level could be used to separate source code by
language, as in src/java/ and src/php for source code in the java and
php languages respectively.
</td>
<td>YES</td>
</tr>
<tr>
<td>xdocs/</td>
<td>Documentation file in XML format.</td>
<td>The Jakarta site uses Velocity/Anakia to transform dcumentation
files in XML into HTML. The generated HTML files automatically
inherit the Jakarta look-and-feel.
</td>
<td>YES</td>
</tr>
<tr>
<td>docs/</td>
<td>Documentation files intended for the end user.</td>
<td>The docs/ directory contain most of the documentation for the
Jakarta sub-project. This includes Velocity/Anakia generated HTML
files. This directory may also contain other documentation files.
</td>
<td>YES</td>
</tr>
<tr>
<td>docs/index.html</td>
<td>Starting point for browsing the documentation.</td>
<td>Browsing the documentation locally should yield the same results
as browsing the documentation on the sub-project home page on the
Jakarta web site.
</td>
<td>YES</td>
</tr>
<tr>
<td>docs/api/</td>
<td>API documentation as generated by the Javadoc tool.</td>
<td>Placing the API documenation under docs/api/ makes it slightly
easier for other documentation files under docs/ to reference API
documentation and vice versa.
</td>
<td>NO</td>
</tr>
<tr>
<td>build/</td>
<td>Files required for building the sub-project.</td>
<td>Building includes compiling source code, generating javadoc
documentation, the creation of jar files and the distribution files
in tar.gz or zip formats.
</td>
<td>YES</td>
</tr>
<tr>
<td>build/build.xml</td>
<td>The ANT build script.</td>
<td>All Jakarta projects are encouraged to use ANT as their build tool.
</td>
<td>YES</td>
</tr>
<tr>
<td>build/build.sh (or .bat)</td>
<td>Shell scripts for Unix and DOS environments to bootstrap the ANT
build process.</td>
<td>The existence of these files implies the existence of binary jar
files, such as ant.jar and xerces.jar under CVS control
</td>
<td>YES</td>
</tr>
<tr>
<td>build/lib/</td>
<td>Binary jar files required in building the sub-project.</td>
<td>The jar files are added to the classpath by the bootstrapping
shell scripts before invoking ANT.
</td>
<td>YES</td>
</tr>
<tr>
<td>dist/</td>
<td>Generated jar files and other sub-project binaries.</td>
<td>This directory contains jar files for the
sub-project. Distribution binaries in .tar.gz and .zip formats should
also be placed in this directory.
</td>
<td>NO</td>
</tr>
<tr>
<td>dist/classes/</td>
<td>Class files generated from the source code contained in the src/
directory.</td>
<td>Other binary files such as icons and images should also be placed
under dist/classes/.
</td>
<td>NO</td>
</tr>
<tr>
<td>contribs/</td>
<td>Contributions not officially part of the sub-project.</td>
<td>Some projects use other names such as whiteboard/ or proposals/.
</td>
<td>YES</td>
</tr>
</table>
</section>
<section name="ANT build files">
<p>Should we also include directives for ANT build scripts, common
target names, etc. in this document?
</p>
</section>
</body>
</document>
1.1 jakarta-site2/docs/site/dirlayout.html
Index: dirlayout.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 -->
<!-- ====================================================================== -->
<!-- Main Page Section -->
<!-- ====================================================================== -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="author" value="Ceki
G�ulc�">
<meta name="email" value="[EMAIL PROTECTED]">
<title>The Jakarta Site - Jakarta Directory Layout</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td colspan="2">
<a href="http://jakarta.apache.org"><img
src="http://jakarta.apache.org/images/jakarta-logo.gif" align="left" border="0"/></a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td valign="top" nowrap="true">
<p><strong>Essentials</strong></p>
<ul>
<li> <a href="../index.html">Front Page</a>
</li>
<li> <a href="http://jakarta.apache.org/site/news.html">News
& Status</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/mission.html">Mission</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/guidelines.html">Guidelines Notes</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/faqs.html">FAQs</a>
</li>
</ul>
<p><strong>Download</strong></p>
<ul>
<li> <a
href="http://jakarta.apache.org/site/binindex.html">Binaries</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/sourceindex.html">Source Code</a>
</li>
</ul>
<p><strong>Get Involved</strong></p>
<ul>
<li> <a
href="http://jakarta.apache.org/site/getinvolved.html">Overview</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/cvsindex.html">CVS Repositories</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/mail.html">Mailing Lists</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/library.html">Reference Library</a>
</li>
<li> <a href="http://jakarta.apache.org/site/bugs.html">Bug
Database</a>
</li>
</ul>
<p><strong>SubProjects</strong></p>
<ul>
<li> <a href="../ant/index.html">Ant</a>
</li>
<li> <a href="../avalon/index.html">Avalon</a>
</li>
<li> <a href="../ecs/index.html">ECS</a>
</li>
<li> <a href="../james/index.html">James</a>
</li>
<li> <a href="../jetspeed/index.html">Jetspeed</a>
</li>
<li> <a href="../jmeter/index.html">JMeter</a>
</li>
<li> <a href="../log4j/index.html">Log4J</a>
</li>
<li> <a href="../oro/index.html">ORO</a>
</li>
<li> <a href="../regexp/index.html">Regexp</a>
</li>
<li> <a href="../slide/index.html">Slide</a>
</li>
<li> <a href="../struts/index.html">Struts</a>
</li>
<li> <a href="../taglibs/index.html">Taglibs</a>
</li>
<li> <a href="../tomcat/index.html">Tomcat</a>
</li>
<li> <a href="../turbine/index.html">Turbine</a>
</li>
<li> <a href="../velocity/index.html">Velocity</a>
</li>
<li> <a href="../watchdog/index.html">Watchdog</a>
</li>
</ul>
<p><strong>Misc</strong></p>
<ul>
<li> <a
href="http://jakarta.apache.org/site/whoweare.html">Who We Are</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/acknowledgements.html">Acknowledgements</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/roles.html">Management</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/jakarta-site2.html">About This Site</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/contact.html">Contact</a>
</li>
<li> <a
href="http://jakarta.apache.org/site/legal.html">Legal</a>
</li>
</ul>
</td>
<td align="left" valign="top">
<table
border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<strong>Rationale</strong>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Having a common directory layout would allow for users familiar with
one Jakarta project to immediately feel at home in another Jakarta
project. The advantages are analogous to adopting a site-wide
look-and-feel as jakarta-wide procedures strengthen the Jakarta brand.
</p>
<p>
The directory structure proposed below is not binding. We recognize
that the cost of changing an existing directory structure can be
high. However, we expect all projects to eventually move to the
proposed layout assuming that the migration can be accomplished with
reasonable effort. <b>The layout is subject to approval.</b>
</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<strong>Common Directory Layout</strong>
</font>
</td></tr>
<tr><td>
<blockquote>
<table>
<tr>
<td bgcolor="#039acc" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Directory name
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Content
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Comment
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Under CVS Control?
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
LICENSE
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
A copy of the Apache Public License
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The LICENSE should be placed at a prominent location.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
src/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Source code.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
If the source code contains only code in the Java language, then
the contents of the src/ directory should mirror the package
hierarchy. Otherwise, if the code contains a mix of languages, then
an extra directory level could be used to separate source code by
language, as in src/java/ and src/php for source code in the java and
php languages respectively.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
xdocs/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Documentation file in XML format.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The Jakarta site uses Velocity/Anakia to transform dcumentation
files in XML into HTML. The generated HTML files automatically
inherit the Jakarta look-and-feel.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
docs/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Documentation files intended for the end user.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The docs/ directory contain most of the documentation for the
Jakarta sub-project. This includes Velocity/Anakia generated HTML
files. This directory may also contain other documentation files.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
docs/index.html
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Starting point for browsing the documentation.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Browsing the documentation locally should yield the same results
as browsing the documentation on the sub-project home page on the
Jakarta web site.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
docs/api/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
API documentation as generated by the Javadoc tool.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Placing the API documenation under docs/api/ makes it slightly
easier for other documentation files under docs/ to reference API
documentation and vice versa.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
NO
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
build/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Files required for building the sub-project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Building includes compiling source code, generating javadoc
documentation, the creation of jar files and the distribution files
in tar.gz or zip formats.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
build/build.xml
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The ANT build script.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
All Jakarta projects are encouraged to use ANT as their build tool.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
build/build.sh (or .bat)
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Shell scripts for Unix and DOS environments to bootstrap the ANT
build process.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The existence of these files implies the existence of binary jar
files, such as ant.jar and xerces.jar under CVS control
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
build/lib/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Binary jar files required in building the sub-project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The jar files are added to the classpath by the bootstrapping
shell scripts before invoking ANT.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
dist/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Generated jar files and other sub-project binaries.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
This directory contains jar files for the
sub-project. Distribution binaries in .tar.gz and .zip formats should
also be placed in this directory.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
NO
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
dist/classes/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Class files generated from the source code contained in the src/
directory.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Other binary files such as icons and images should also be placed
under dist/classes/.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
NO
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
contribs/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Contributions not officially part of the sub-project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Some projects use other names such as whiteboard/ or proposals/.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
YES
</font>
</td>
</tr>
</table>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<strong>ANT build files</strong>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Should we also include directives for ANT
build scripts, common
target names, etc. in this document?
</p>
</blockquote>
</td></tr>
</table>
</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-2001, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->
