jon 01/03/13 14:50:08
Modified: docs/site dirlayout.html
xdocs/site dirlayout.xml
Log:
#1. Yes, I know that Ceki's name is screwed up again. I still need to spend
some time figuring out why my OSX JVM is screwing this up. :-( Note, I removed
an extra "u".
#2. added my comments and ideas on how things should be done. of course
you are welcome to check your ideas on top of mine and we can argue about
it in CVS. :-)
-jon
Revision Changes Path
1.2 +73 -17 jakarta-site2/docs/site/dirlayout.html
Index: dirlayout.html
===================================================================
RCS file: /home/cvs/jakarta-site2/docs/site/dirlayout.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dirlayout.html 2001/03/13 18:56:29 1.1
+++ dirlayout.html 2001/03/13 22:50:03 1.2
@@ -11,8 +11,10 @@
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=iso-8859-1"/>
- <meta name="author" value="Ceki
G�ulc�">
+ <meta name="author" value="Ceki
G�ulc�">
<meta name="email" value="[EMAIL PROTECTED]">
+ <meta name="author" value="Jon S. Stevens">
+ <meta name="email" value="[EMAIL PROTECTED]">
<title>The Jakarta Site - Jakarta Directory Layout</title>
</head>
@@ -182,7 +184,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- LICENSE
+ LICENSE.txt
</font>
</td>
@@ -194,7 +196,9 @@
</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.
+ The LICENSE.txt should be placed at a prominent location.
+ This file should have the suffix .txt so that it can be opened
+ easily on platforms that use suffix mappings.
</font>
</td>
@@ -221,13 +225,19 @@
</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.
-
+ The code should be placed into separate source code directories by
+ language, as in and for
+ source code in the java and PHP languages respectively. If the source
+ is the Java language, then it should follow a package structure that is
+ defined like this: . For example, for
+ the project, it is
+ .
+
+ <code>src/java/</code>
+ <code>src/php/</code>
+ <code>org.apache.PROJECT</code>
+ <a href="/velocity/">Velocity</a>
+ <code>org.apache.velocity</code>
</font>
</td>
@@ -255,9 +265,10 @@
<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.
+ files in XML into HTML. The generated HTML files automatically inherit
+ the Jakarta look-and-feel. Documentation is .
+ <a href="./jakarta-site2.html">available</a>
</font>
</td>
@@ -286,7 +297,11 @@
<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.
+ files. This directory may also contain other documentation files.
+ Generally, all documentation is stored in the xdocs directory and then
+ "transformed" into this directory. It is then checked into CVS and
+ checked out of CVS on the live website. This can serve a dual purpose
+ of being the documentation for a project as well as the website.
</font>
@@ -346,8 +361,12 @@
<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.
+ documentation and vice versa. It is not recommended to check this into
+ CVS. At some point, we will have the project building the documentation
+ for all of the Jakarta Projects and making the API documentation
+ available that way.
+ <a href="/alexandria/">Alexandria</a>
</font>
</td>
@@ -404,7 +423,9 @@
</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.
+ All Jakarta projects are required to use ANT as their build tool.
+ Note, it is allowable to place this file at the top level directory
+ structure.
</font>
@@ -435,6 +456,8 @@
<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
+ Note, it is allowable to place the shell scripts at the top level
+ directory structure.
</font>
@@ -463,8 +486,10 @@
<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.
+ shell scripts before invoking ANT. Note, it is allowable to place
+ the .jar files at the top level directory.
+ <code>/lib</code>
</font>
</td>
@@ -564,6 +589,37 @@
</td>
</tr>
+ <tr>
+ <td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ lib/
+
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ .jar or other library files that the project depends on.
+
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ This directory and the directories
+ are used to store library files that the project depends on. It is
+ allowable to choose to store files in one or both directories.
+
+ <code>build/lib/</code>
+
+ </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>
@@ -577,7 +633,7 @@
<tr><td>
<blockquote>
<p>Should we also include directives for ANT
build scripts, common
-target names, etc. in this document?
+target names, etc. in this document? [JSS] Yes.
</p>
</blockquote>
</td></tr>
1.2 +54 -20 jakarta-site2/xdocs/site/dirlayout.xml
Index: dirlayout.xml
===================================================================
RCS file: /home/cvs/jakarta-site2/xdocs/site/dirlayout.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dirlayout.xml 2001/03/13 18:56:26 1.1
+++ dirlayout.xml 2001/03/13 22:50:06 1.2
@@ -2,7 +2,8 @@
<document>
<properties>
- <author email="[EMAIL PROTECTED]">Ceki Güulcü</author>
+ <author email="[EMAIL PROTECTED]">Ceki Gülcü</author>
+ <author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<title>Jakarta Directory Layout</title>
</properties>
@@ -38,9 +39,12 @@
</tr>
<tr>
- <td>LICENSE</td>
+ <td>LICENSE.txt</td>
<td>A copy of the Apache Public License</td>
- <td>The LICENSE should be placed at a prominent location.</td>
+
+ <td>The LICENSE.txt should be placed at a prominent location.
+ This file should have the suffix .txt so that it can be opened
+ easily on platforms that use suffix mappings.</td>
<td>YES</td>
</tr>
@@ -49,12 +53,13 @@
<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>The code should be placed into separate source code directories by
+ language, as in <code>src/java/</code> and <code>src/php/</code> for
+ source code in the java and PHP languages respectively. If the source
+ is the Java language, then it should follow a package structure that is
+ defined like this: <code>org.apache.PROJECT</code>. For example, for
+ the <a href="/velocity/">Velocity</a> project, it is
+ <code>org.apache.velocity</code>.
</td>
<td>YES</td>
</tr>
@@ -64,8 +69,9 @@
<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.
+ files in XML into HTML. The generated HTML files automatically inherit
+ the Jakarta look-and-feel. Documentation is <a
+ href="./jakarta-site2.html">available</a>.
</td>
<td>YES</td>
</tr>
@@ -76,7 +82,11 @@
<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.
+ files. This directory may also contain other documentation files.
+ Generally, all documentation is stored in the xdocs directory and then
+ "transformed" into this directory. It is then checked into CVS and
+ checked out of CVS on the live website. This can serve a dual purpose
+ of being the documentation for a project as well as the website.
</td>
<td>YES</td>
</tr>
@@ -98,7 +108,11 @@
<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.
+ documentation and vice versa. It is not recommended to check this into
+ CVS. At some point, we will have the <a
+ href="/alexandria/">Alexandria</a> project building the documentation
+ for all of the Jakarta Projects and making the API documentation
+ available that way.
</td>
<td>NO</td>
</tr>
@@ -117,7 +131,10 @@
<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>All Jakarta projects are required to use ANT as their build tool.
+ Note, it is allowable to place this file at the top level directory
+ structure.
</td>
<td>YES</td>
</tr>
@@ -127,26 +144,28 @@
<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
+ Note, it is allowable to place the shell scripts at the top level
+ directory structure.
</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.
+ shell scripts before invoking ANT. Note, it is allowable to place
+ the .jar files at the top level <code>/lib</code> directory.
</td>
<td>YES</td>
</tr>
<tr>
- <td>dist/</td>
-
+ <td>dist/</td>
<td>Generated jar files and other sub-project binaries.</td>
<td>This directory contains jar files for the
@@ -160,8 +179,10 @@
<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/.
+ under dist/classes/. In other words, when the project is built, the
+ output directory should be this directory.
</td>
<td>NO</td>
</tr>
@@ -169,10 +190,23 @@
<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>
+
+ <tr>
+ <td>lib/</td>
+ <td>.jar or other library files that the project depends on.</td>
+
+ <td>This directory and the <code>build/lib/</code> directories
+ are used to store library files that the project depends on. It is
+ allowable to choose to store files in one or both directories.
+ </td>
+ <td>YES</td>
+ </tr>
+
</table>
</section>
@@ -180,7 +214,7 @@
<section name="ANT build files">
<p>Should we also include directives for ANT build scripts, common
-target names, etc. in this document?
+target names, etc. in this document? [JSS] Yes.
</p>
</section>
