Hi,
In preparation for cleaning up the docs on the site, I'm wondering if we
should add "deprecated" to the DTD for docs (it already exists for
javadocs).
My reasoning:
- it allows us to highlight content that is deprecated on the web site, to
provide visual warnings against using it;
- it will allow us to more accurately hunt down deprecated content in the
docs prior to the next major release (presuming we'd want to remove some
deprecated stuff);
- it will allow us to do better comparisons between deprecated code and
deprecated documentation (to help keep docs up-to-date);
- adding more semantic meaning to our content is generally a good thing as
long as the overhead is not too great.
So for example we might have:
<deprecated>
<tr>
<td>xsp-request:get-session-attribute</td>
<td></td>
<td>no</td>
<td>Gets a given attribute of a session.</td>
</tr>
</deprecated>
which we'd perhaps transform to:
<tr class="deprecated">
<td>xsp-request:get-session-attribute</td>
<td></td>
<td>no</td>
<td>Gets a given attribute of a session.</td>
</tr>
Some issues:
- 'deprecated' should perhaps be smart enough to point to the replacement
functionality if it exists. Perhaps an attribute "by", so we'd have
<deprecated by="xsp-session:get-attribute"/> (possibly with a URI to the
new code?).
- We could have a standard "deprecated" text, such as "this feature is
deprecated in the @version@ release of Cocoon, and may be removed in
future releases".
What do you think?
Andrew.
--
Andrew Savory Email: [EMAIL PROTECTED]
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
