You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Andrew Savory <an...@luminas.co.uk> on 2003/03/20 10:29:25 UTC
Deprecating and cleaning up the docs
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
Re: Deprecating and cleaning up the docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
> ....How would you see us handling the example:
>
> <tr>
> <td>xsp-request:get-session-attribute</td>
> <td></td>
> <td>no</td>
> <td>Gets a given attribute of a session.</td>
> </tr>
>
> I guess if we marked it with <tr deprecated-see=""> that would do?
>
yes, then in the XSLT transforms the attribute can be inherited using
an ancestor::* XPath, which shouldn't be too slow in the kinds of
documents that we have (as I don't think the nesting is very deep).
This would allow such a table to be marked as deprecated with just one
attribute.
-Bertrand
Re: Deprecating and cleaning up the docs
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 20, 2003, at 05:18 AM, Andrew Savory wrote:
>
>> I don't know if there are issues/dependencies related to changing the
>> DTDs though (maybe related to Forrest?).
>
> Just taken a look at Forrest DTDs, and I can't see any deprecated
> element
> or attribute ... the closest is "warning". So I guess we'd need to add
> it
> to both cocoon and forrest ...
Thoughts:
1. Please let's not add anything new capabilities to our currently used
document-v10 dtds. Last I checked, all our v10- docs translate to
doc-v11 with existing transition tools. Sorry to sound like a broken
record, but we need to either transition to Forrest first or add this
capability to the transition trial files currently located in the
Forrest cvs. That is, build a prototype of a "transitioned" Cocoon docs
(which will reveal a few outstanding problems which you are welcome to
fix), copy over your suggested changes, and go/report/advise from there.
2. It's my impression that supplementing the v11 dtds is an
ongoing/unresolved issue at Forrest. You might get more information if
you discuss it on the Forrest list. Seems to me there are different
approaches:
a. Ssk forrest to change a particular dtd -- or add it to the dtd
changes wishlist, (sorry, can't find the link)
b. Make our own more expressive dtd which then gets transformed in an
intermediate step to doc v11 or xhtml2 before the final "presentation"
processing step
3. In some ways, marking content with deprecation tags feels like the
wrong approach. Technically, these docs are reference pages which could
be generated in a uniform way, with deprecation status etc. pulled from
the source code, in this case,
src/java/org/apache/cocoon/components/language/markup/xsp/java/request.xsl.
We discussed this previously for java source files, not sure how it
would work in the above case with the logicsheets.
I'm not against this type of approach, or course, for docs like user
manuals, how-tos, etc. Still, I wish we could implement the above need
by looking up the components/code referred to by the content, checking
for deprecation status there, instead of manually inserting this info in
docs, but that probably would probably kill doc-generation performance.
Thanks.
Diana
Re: Deprecating and cleaning up the docs
Posted by Andrew Savory <an...@luminas.co.uk>.
Hi,
On Thu, 20 Mar 2003, Bertrand Delacretaz wrote:
> I wouldn't use an element for this though, but rather an attribute, for
> example
>
> <p deprecated-see="/xsp-deprecated">
> <li deprecated-see="#release-2.1">
>
> This attribute could be used for paragraphs, sections, list items, etc.
>
> Using an attribute requires less changes to the DTD structure I think,
> and conceptually "deprecated" *is* an attribute of a piece of
> information.
Ok, makes sense. My reasoning behind the element was that we can wrap
blocks of content in one go - especially useful where the content happens
to be table rows and cells. It would then be trivial to produce
documentation without deprecated content, for example.
How would you see us handling the example:
<tr>
<td>xsp-request:get-session-attribute</td>
<td></td>
<td>no</td>
<td>Gets a given attribute of a session.</td>
</tr>
I guess if we marked it with <tr deprecated-see=""> that would do?
> I don't know if there are issues/dependencies related to changing the
> DTDs though (maybe related to Forrest?).
Just taken a look at Forrest DTDs, and I can't see any deprecated element
or attribute ... the closest is "warning". So I guess we'd need to add it
to both cocoon and forrest ...
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
Re: Deprecating and cleaning up the docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Hi Andrew,
Le Jeudi, 20 mars 2003, à 10:29 Europe/Zurich, Andrew Savory a écrit :
> ....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)....
I agree on the principle - being able to indicate the validity of the
docs is a good thing.
I wouldn't use an element for this though, but rather an attribute, for
example
<p deprecated-see="/xsp-deprecated">
<li deprecated-see="#release-2.1">
This attribute could be used for paragraphs, sections, list items, etc.
Using an attribute requires less changes to the DTD structure I think,
and conceptually "deprecated" *is* an attribute of a piece of
information.
I don't know if there are issues/dependencies related to changing the
DTDs though (maybe related to Forrest?).
-Bertrand