donaldp 01/03/21 01:22:52
Modified: docs/site dirlayout.html
Log:
Update generated dirlayout with my take on it
Revision Changes Path
1.10 +92 -90 jakarta-site/docs/site/dirlayout.html
Index: dirlayout.html
===================================================================
RCS file: /home/cvs/jakarta-site/docs/site/dirlayout.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- dirlayout.html 2001/03/20 19:48:54 1.9
+++ dirlayout.html 2001/03/21 09:22:50 1.10
@@ -15,6 +15,8 @@
<meta name="email" value="[EMAIL PROTECTED]">
<meta name="author" value="Jon S. Stevens">
<meta name="email" value="[EMAIL PROTECTED]">
+ <meta name="author" value="Peter Donald">
+ <meta name="email" value="[EMAIL PROTECTED]">
<title>The Jakarta Site - Jakarta Directory Layout</title>
</head>
@@ -124,7 +126,7 @@
<table
border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <strong>Rationale</strong>
+ <a name="Rationale"><strong>Rationale</strong></a>
</font>
</td></tr>
<tr><td>
@@ -154,7 +156,7 @@
<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>
+ <a name="Common Directory Layout"><strong>Common Directory
Layout</strong></a>
</font>
</td></tr>
<tr><td>
@@ -190,7 +192,7 @@
</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
+ A copy of the Apache License
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -221,9 +223,9 @@
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<p>The code may be placed into separate source code directories
by language, as in src/java/ and src/php/ for source code in the Java
- and PHP languages respectively. Some Jakarta projects organize source
- code differently but in all cases source code is placed under the
- src/ directory.</p>
+ and PHP languages respectively. Other projects may separate the code
+ according to function (src/share, src/testcases, src/compat). It is
+ highly recomended that sub-directories be used under src/.</p>
</font>
@@ -247,9 +249,9 @@
</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. Documentation is <a
href="./jakarta-site2.html">available</a>.
+ The Jakarta site uses Velocity/Anakia or Stylebook to transform
+ dcumentation 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>
@@ -273,13 +275,47 @@
<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.
- Generally, all documentation is stored in the src/xdocs/ directory
- and then "transformed" into this directory. It is then checked into
+ Jakarta sub-project. This includes Velocity/Anakia or Stylebook
+ generated HTML files. This directory may also contain other
+ documentation files. Generally, all documentation is stored in the
+ src/xdocs/ directory and then "transformed" into this directory.
+
+ It is then checked into
CVS and checked out of CVS on the live website. This allows the user
to browse the documentation on the local host without requiring
- network connectivity as well as on the live website.
+ network connectivity as well as on the live website. Alternatively
+ some projects may place
+
+ </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">
+ docs/ or www/
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ Web site documentation.
+ </font>
+</td>
+ <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
+ <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+ Some projects choose to check in documentation for their website
+ to ease maintanence of site. This may be a superset of the documentation
+ included in the documentation provided in distributions. If the project
+ includes regular distributions then the website should be an image of
+ documentation of last release. For projects that don't have regular releases
+ and whos website does not have highly volatile information (news, bug reports
+ etc.) then it is acceptable to use docs/ subdirectory otherwise the www/ directory
+ is recomended. Once checked into the CVS it is expected that the documentation will
+ also be checked out on live website.
</font>
</td>
@@ -292,7 +328,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- docs/index.html
+ www/index.html
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -317,7 +353,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- docs/api/
+ docs/api
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -345,7 +381,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- build/
+ tools/ or build/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -370,7 +406,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- build/build.xml
+ build.xml or build/build.xml
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -395,7 +431,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- build/build.sh build/build.bat
+ build.sh build.bat
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -408,8 +444,7 @@
<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.
+ Note, it is allowable to place the shell scripts in subdirectory build/.
</font>
</td>
@@ -422,7 +457,7 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- build/lib/
+ tools/lib or build/lib/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
@@ -436,7 +471,7 @@
shell scripts before invoking ANT. The jar files should consist of
ant.jar as well as jar files needed for XML parsing.
- <p>The build/lib/ directory should contain jar files needed during
+ <p>The tools/lib/ or build/lib/ directory should contain jar files needed during
build time and during build time only. If an XML parser
is also required during the runtime of the project, then the jar
files for the parser should be placed under dist/lib/.</p>
@@ -458,14 +493,16 @@
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- This directory contains most of the binaries related with the
- sub-project, generated or not.
+ This directory is an image of the distribution files. Hence why it
is called "dist" (short
+ for distribution).
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The contents of the dist/ directory should be enough to use the
- project.
+ project. The particular format of distribution is project dependent. Some may
generate
+ a project.jar and a README while others may have dist the image of a .war file. It
is
+ commong to have dist/bin for scripts and dist/lib for jars related to runtime.
</font>
</td>
@@ -477,75 +514,55 @@
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
- <font color="#000000" size="-1" face="arial,helvetica,sanserif">
- dist/bin/
- </font>
-</td>
- <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
- <font color="#000000" size="-1" face="arial,helvetica,sanserif">
- Scripts and executables that the end-user will invoke to run the
- project.
- </font>
-</td>
- <td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
- <font color="#000000" size="-1" face="arial,helvetica,sanserif">
- A one-stop location to run the project as an application.
- </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/lib/
+ bin/ or build/
</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 during runtime.
+ Intermediate files files generated while building the project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- This directory and the build/lib/ directories are used to store
- library files that the project depends on at runtime.
+ <p>It is to this directory that intermediate files are generated.
+ Different types are generally generated to sub-directories (ie .class files
+ stored in bin/classes, build/classes, .jar files in bin/lib or build/lib.</p>
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- YES
+ 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/
+ distributions/
</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.
+ This directory contains the project release distributions. These
are often
+ project.tar.gz, project.zip, project.rpm or project.war format.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- <p>In other words, when the project is compiled, the output
- directory should be this directory.</p>
+
+ <p>There are generally two forms of releases. Binary releases and
+ source releases. Binary releases consist of all the components end-users
+ require to use the product. This may include jars and generated documentation.</p>
+
+ <p>A source release generally includes an image of CVS repository. Files excluded
+ include any proposals/ or whiteboard/ code and the www/ directory. The source
+ release will often include generated documentation.</p>
- <p>Other binary files such as icons and images may also be placed
- under dist/classes/. The contents of this directory can be used to
- generate jar files.</p>
+ <p>This directory is meaningful only to release managers. End-user
+ should be oblivious to it.</p>
- <p>Note that including raw classes in a distribution will waste
- network bandwidth as well as disk space.</p>
</font>
</td>
@@ -558,54 +575,39 @@
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- dist/release/
+ contribs/
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- This directory contains the project release binaries in .tar.gz
- and .zip format.
+ 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">
-
- <p>A project release typically consists of build scripts, source
- code, documentation including javadoc generated documentation, jar
- files required at runtime or everyting that an end-user needs to
- successfully use the project.
- </p>
-
- <p>It is common practive to split the release image to parts,
- separating documentation, source code and binary.</p>
-
- <p>This directory is meaningful only to release managers. End-user
- should be oblivious to it.</p>
-
-
-
+
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- NO
+ YES
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan="" valign="top"
align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
- contribs/
+ whiteboard/ or proposals/
</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.
+ Revolutions and other untested code bases.
</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/.
+ It is here where developers will host revolutions, forks and other
deviations of codebase.
</font>
</td>
@@ -622,12 +624,12 @@
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <strong>Points to keep in mind</strong>
+ <a name="Points to keep in mind"><strong>Points to keep in
mind</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
- <p>It is recommended to include a
<code>.cvsignore</code> file in each
+ <p>It is recommended to include a
<code>.cvsignore</code> file in top-level
directory under CVS control in order to avoid the distracting
"?" message output during CVS update.
</p>
@@ -646,7 +648,7 @@
<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>
+ <a name="ANT build files"><strong>ANT build files</strong></a>
</font>
</td></tr>
<tr><td>
