At 15:22 08.05.2001 +0100, you wrote:
>Peter Donald wrote:
>> The other group was
>> 1. name of directory of generated local docs if any
>> 2. name of directory of generated www docs if any
>> 3. Whether local docs == www docs
>>
>> Some projects don't have any generated docs in CVS. Others only have one
>> version. Others have one version in CVS and one local, the version in CVS
>> being dated to last release.
>>
>> Ideally we wouldn't have any generated docs in CVS but as no-one has
>> stepped up to fix that - I guess we gotta keep it.
>>
>> Some projects don't do "releases" as such and thus can synch the web docs
>> whenever they want. Thus they don't need to have a separate www and local
>> docs (assuming local==www).
>>
>> In an ideal world there would not be a need at all for any docs in CVS and
>> (thus no www/docs dir) however until this is in place I am really not sure
>> what to do.
>>
>> I think we should make it mandatory that local==www for simplicity sake.
>
>-1 I think we should let projects choose whether local (ie /docs) ==
>www. For projects doing releases I guess they would normally want www to
>describe latest release but /docs to describe current cvs.
Charles,
Agreed. Mandating that the docs contained in the distribution and the docs available
on the jakarta web server match exactly is too restrictive. However, allowing the user
to browse the documentation locally from the files contained within the distribution
is a nice feature. Wouldn't you agree?
>Ceki's description of log4j's doc dance works, but makes altering www
>docs post-release tricky. I think docs are likely to be a bit behind the
>curve, particularly for smaller projects.
True.
>So, the current system of checking out www docs from cvs makes sense - it allows doc
>amends for
>last release to be tracked.
I think no one is contesting that tracking source files using CVS is a good idea.
However, the CVS update operation is one way of copying the latest version of doc
files to the jakarta web server. It is certainly not the only way. Reading your
comments below, I think that we are actually in total agreement.
>On the other hand, do we need generated docs in cvs /docs? Obviously we
>need generated docs in the (binary) dist for nightly builds and
>milestone releases. But that comes from the build / release process.
>
>So I suggest:
>/src/xdocs - Documentation files in XML format (no change)
>/docs - empty, standard location for generated docs of current
>code.
>/www - if no releases - copy of generated docs
> if releases - copy of generated docs at last release.
I am afraid I don't get it. First, by generated documentation I assume you mean the
javadocs. Right?
Wouldn't it be possible to have a single top-level documentation directory, says
docs/, and have the javadocs go under docs/api/? I believe this is the way the XML
projects do it.
What do you think? Regards, Ceki
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
