Well, I certainly sympathize with Dan's comments. Being defensive, I might point out that it took me (and
others ) hours, if not days to get DocBook working before Roberto and I started working on the process, so if it took Dan only 30 minutes, then that is an improvement 😉
Unfortunately, I only have access to my own system, so I've tried to get things working for me, hoping that others would step in where I've screwed things up. When I start creating XSL stylesheets, I'm way at the frontiers of my realm of expertise.
I think we might be able to improve things by having the openacs.xsl sheet point to a docbook installation on the web somewhere. The index.xml sheet already does this. That way, having Docbook installed locally might not even be needed. I haven't tested this yet though.
Also, if anyone can figure out if it's possible just to generate certain desired pages instead of the whole damn thing, that would be great. I've tried without success.
I'm not going to try to defend Docbook too vigorously. It was what we were given, so I've tried to make it work. I do think it is a standard and that is a good thing. We definitely do need docs to be in HTML and PDF formats at least, judging from the multiple *ahem* "feedback" emails that I received before we had PDF docs available. I think there's also a benefit to separating content from presentation (although you need to be an XSL wizard to do it properly). But I agree with Dan that it's most important to lower the bar for documentation submissions, and I don't know the best way to do that.
