cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Deprecating and cleaning up the docs
Date Thu, 20 Mar 2003 13:20:28 GMT

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


Mime
View raw message