cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Savory <and...@luminas.co.uk>
Subject Deprecating and cleaning up the docs
Date Thu, 20 Mar 2003 09:29:25 GMT

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: andrew@luminas.co.uk
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

Mime
View raw message