My preliminary reaction:
I agree that a common directory layout is a very good idea, but it appears
to me that we are talking about 3 layouts:
1. the repository
2. the distribution
3. the website
1. The repository is under CVS. IMO it should not include any files
generated by the project's Ant build. So distributed doc and website doc
(whether identical or not) should not be in the repository. I think the
repository should include a tools dir, not a build dir, for binaries
required to do the build.
2. As the jakarta document acknowledges, many distributions include a
source distribution and a binary distribution. I agree that the source
distribution should mimic the repository. I do not think it should include
generated doc. For that, the user runs the build or downloads the binary
distribution. I think the binary distribution should include JARs and the
generated doc. I do not think it makes sense to include the class tree.
That makes the download more cumbersome and duplicates what is already in
the JARs.
When the user runs an Ant build, then I think the results should be put in
a build tree. I think it is a good idea not to overwrite the binary
distribution (assuming the user downloaded it). I prefer build/ to bin/.
for this build tree. In response to a question that was raised, the build
tree does include a number of "intermediate" files that are not required in
the binary distribution (such as a class tree, which the user can get by
expanding the JAR).
I see no reason for dist/. This is not in the repository and the user gets
it by downloading and expanding the distribution. Likewise not reason for a
separate docs/ tree somehow distinct from the website. If the distributed
doc is different, the user gets it by downloading and expanding the binary
distribution file, or by downloading the source distribution and running a
build.
3. We need a directory tree to hold the website (docs and docs/api). I
don't think we should put any of this in CVS. The jakarta proposal appears
to put the docs generated from XML in the repository but not the api doc.
As long as we are copying the javadoc to the website (or to a staging
area?), we might as well do the same with the other doc.
I'm sure I'll have more to say (hopefully helpful!) as this discussion
continues.
-- Don Leslie
---------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
