Stefano Mazzocchi wrote:
Stephan Michels wrote:
Stefano Mazzocchi wrote:
<snip/>
So, at the end, here is what I propose:
1) we remove all the old docs targets from the build
To remove the "build docs" target, i agree. To remove the webapp docs generation, i do not agree.
Ok.
2) documentation will be done thru forrest. This requires forrest be available on the machine separately. since users won't update the documentation this should not be a problem.
But we do want to encourage the users to update doco and send patches. So i would not use them as an excuse.
I'm not finding excuses, David, I'm trying to move this shit forward and the dependencies between cocoon and forrest are *SO* interconnected that I could not find a solution to the problem.
Moreover, to be honest, I think that we should aim to improve forrest/lenya and make it a structured wiki and setup a CMS and point users to that for editing.
that's the only way they can help up writing docs because our current xdocs-patch workflow is too much a stinking pain in the ass.
3) we ship the pregenerated documentation in the distribution and we ship along the xml source files. if the documentation is included in the webapp cocoon will simply *read* them (not process them as right now).
Why would you want many megabytes of generated docs in the cvs? This seems to defeat the purpose of Cocoon. Surely there is a way for Cocoon to continue to generate its own doco via its webapp.
yes, there is: ship forrest skins and xml/xslt machinery with cocoon.
We had some discussion about that on cocoon-docs but there did not seem to be any followup. Re: Stages of Forrest Transition http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=104847388622334
ok
4) this breaks the flow samples that depend on those stylesheets but they are going to be refactored anyway, so don't worry.
5) finally, remove all the doc-generation stylesheets from the CVS
what do you think?
That an xml framework that needs to deliver pre-built documentation is an old hack.
I agree, but any other solution would leave to a duplication of effort between cocoon and forrest and I'm not sure this is worth the hackiness of shipping prebuilt docs.
Stefano.
