Ceki G�lc� wrote:
>
> 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?
Yes - but that doesn't mean that CVS has too contain any generated docs
(see below)
>
> >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.
Woops, what i meant by 'generated docs' is the output of Anakia or
Stylebook. Javadocs in docs/api is fine. My point was its really only
the binary dists that need generated docs. (And www possibly - see
Craig's email)
Charles
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
