To clean up old cruft. I just don't see any need to keep including in the documentation stuff that we don't want people using anyway.
Is there any harm in documenting it as deprecated, and then removing it altogether once the feature is actually removed according to the two-release-rule?
The reason I think this is a better idea is that users will Know up front that a feature is deprecated. Right now, I can't tell whether something doesn't exist in the documentation because no one has gotten around to it or because it has been removed. I often rely on <antstructure> to tell me what I can REALLY do in terms of attributes. And forcing someone to build a system that uses a feature in order to find out that feature is deprecated strikes me as badness.
Then there is the question of learning how ant works by reading other people's build files. If the build files work and you can't figure out how they work by reading the documentation, that can be a frustrating experience for a new user (who may not recognize the significance of the deprecation warnings when they come up).
So why not have the documentation match the program as much as possible? Document deprecation, and remove documentation for removed features.
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
