Includes HTML in source control ----- Jakarta-Site Struts Lucene Ant Log4j Tomcat
Doesn't include HTML in source control ---- Turbine Geronimo Maven
So it looks like if we pull the HTML out of the repo, we'll be in the minority but not alone.
WILL
----- Original Message ----- From: "Nathan Bubna" <[EMAIL PROTECTED]>
To: "Velocity Developers List" <[email protected]>
Sent: Thursday, February 17, 2005 12:11 PM
Subject: Re: generated docs in repo
On Thu, 17 Feb 2005 09:33:07 -0800, Will Glass-Husain <[EMAIL PROTECTED]> wrote:Well, bottom line is that there's only 5 people people who have the ability
to update the Velocity site. (3 Velocity committers and 2 tools
committers - is that right?)
sorta. but Marino and i can really only edit the tools docs given the current publishing system. since we can't commit to the core, we can't update and commit new core docs either.
I vote with Nathan to leave out the generated docs. (That's two). It's
easy enough to create them on demand. Any of the other committers available
to comment?
As a side note, we should be sure it's clearly stated in the readme how to
make the docs for those brave enough to download the nightly source drops.
(And of course the docs should be generated for released versions).
it might be nice to include some policy on published documentation along with that. at present, we have docs for velocity 1.5 published when we haven't even released 1.5 yet. this has confused many who can't understand why the map syntax doesn't work in 1.4.
here's a quick, unrefined suggestion for a web site/publishing policy:
1. published javadoc and user's guide type stuff should match latest released version (including betas and release candidates to encourage early adoption).
2. published change log or other "news" type pages should be regularly updated to show changes since last release (also to encourage early adoption)
3. typos in published javadoc or user's guide should be fixed to match latest release's actual functioning, even if that puts them at odds with the docs bundled along with that release.
4. any docs that do not reflect the latest release--whether because they are obsolete or cutting edge--should not be placed or left up on the project web site
thoughts?
Best, WILL
----- Original Message ----- From: "Florin Vancea" <[EMAIL PROTECTED]> To: "Velocity Developers List" <[email protected]> Sent: Thursday, February 17, 2005 8:36 AM Subject: Re: generated docs in repo
> Suggestion (may be foolish, since I'm not familiar with Apache's > internal
> workings):
>
> Split the docs in a completely separate repository tree and let the
> developers check in and work with the "unpolluted" pure source in the
> remaining tree.
> At build time, generate docs in the "doc" tree from sources and commit
> them,
> keeping the simple_publishing_method happy.
>
> Just my 2c.
>
> Florin.
>
> ----- Original Message -----
> From: "Tim Colson (tcolson)" <[EMAIL PROTECTED]>
> To: "Velocity Developers List" <[email protected]>
> Sent: Thursday, February 17, 2005 6:28 PM
> Subject: RE: generated docs in repo
>
>
>>
>> > > Which brings me back to the question: Do we really want
>> > > *auto-generated* documents in the repo?
>> >
>> > for the record, i've been told that this was done to make updating >> > the
>> > site "easier". rather than uploading the generated docs to the site
>> > directly, we check them in to the repo and just do a cvs (or svn)
>> > update of them at the web site's root. but personally, i've never
>> > been convinced that this is that much easier.
>>
>> I'm in the same boat as Shinobu... seems anything that can be >> generated
>> doesn't belong in the repo. But based on Nathans info, I can >> understand
>> reasons* why it may have evolved as the "easiest way to publish".
>>
>> *Although some Apache/Jakarta decisions are simply baffling to me >> (Moin
>> Moin powered by Pything instead of a free intance of Confluence built >> in
>> 100% java, for example.)
>>
>>
>> Cheers,
>> Timo
>> P.S. I haven't forgotten about my offer to try and help create a css
>> layout and printable stylesheet for the docs.... so many ideas, so
>> little time.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [EMAIL PROTECTED]
>> For additional commands, e-mail: [EMAIL PROTECTED]
>>
>>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
