Return-Path: 
 <cocoon-docs-return-669-apmail-xml-cocoon-docs-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-docs-archive@xml.apache.org
Received: (qmail 7270 invoked by uid 500); 20 Mar 2003 09:29:23 -0000
Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:cocoon-docs-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-docs-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-docs@xml.apache.org>
Reply-To: cocoon-docs@xml.apache.org
Delivered-To: mailing list cocoon-docs@xml.apache.org
Received: (qmail 7211 invoked from network); 20 Mar 2003 09:29:22 -0000
Received: from mta07-svc.ntlworld.com (62.253.162.47)
  by daedalus.apache.org with SMTP; 20 Mar 2003 09:29:22 -0000
Received: from oscar ([81.100.206.62]) by mta07-svc.ntlworld.com
          (InterMail vM.4.01.03.37 201-229-121-137-20020806) with ESMTP
          id <20030320092933.TCPR25105.mta07-svc.ntlworld.com@oscar>
          for <cocoon-docs@xml.apache.org>; Thu, 20 Mar 2003 09:29:33 +0000
Received: from savs (helo=localhost)
	by oscar with local-esmtp (Exim 3.36 #1 (Debian))
	id 18vwMX-0001YH-00
	for <cocoon-docs@xml.apache.org>; Thu, 20 Mar 2003 09:29:25 +0000
Date: Thu, 20 Mar 2003 09:29:25 +0000 (GMT)
From: Andrew Savory <andrew@luminas.co.uk>
X-X-Sender: savs@oscar
To: cocoon-docs@xml.apache.org
Subject: Deprecating and cleaning up the docs
Message-ID: <Pine.LNX.4.51.0303200916460.2309@oscar>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: Andrew Savory <savs@luminas.co.uk>
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N


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