I think you are right on. +1
Quoting Jose Gonzalez Gomez <[EMAIL PROTECTED]>: > 2005/10/25, Jason van Zyl <[EMAIL PROTECTED]>: > > On Tue, 2005-10-25 at 09:35 +0200, Jose Gonzalez Gomez wrote: > > > Brett, > > > > > > Do you mean docbook support in Doxia or are you talking about anything > else? > > > > He meant find a general approach that works. If it can be done in Doxia > > that's great, otherwise you might need a separate tool. > > > > Please, correct me if I'm wrong, as I have made some assumptions from > my little knowledge of the inner operations of Maven and Doxia... > > I think the problem here is trying to match two completely different > approaches: > > 1. In first place, we have Doxia that (I think) was created as a tool > to parse and generate documentation in several formats. I guess > (correct me if I'm wrong) that the original primary purpose of Doxia > was being able to integrate documentation written in several formats > in a Maven site. The problem with such an approach is that you have to > stablish a common group of elements that all those source formats must > share (the Sink interface in Doxia), so if you have a source format > richer than that, you're losing in the process. > > 2. In second place we have Docbook, a format that was created to write > technical documentation. The real power of Docbook (IMHO) is not the > format itself but the possibility of using almost WYSIWYG editors and > the style sheets available that let you generate documentation in a > lot of formats: HTML, XHTML, PDF, JavaHelp, Eclipse Help,... Here you > have just a source format you use to generate whatever you want, so > you don't have the need to limit your output, as you come from a known > input. > > I have the feeling that wahtever you do in Doxia regarding Docbook: > 1. You are reinventing the wheel in some sense, as you already have > the Docbook stylesheets, and > 2. You are losing a lot of the power and richness of Docbook > > So I have the feeling that this is not the right approach... What I > would probably do is drop the docbook support in Doxia (or keep it > deliberately simple), as I see no reason to write a Maven site using > Docbook: APT or HTML/XHTML are much more adequate to do that. > > Any way, I think a plugin for managing Docbook files is needed, as I > may want to generate project documentation in PDF format, JavaHelp > files, whatever that doesn't go directly into the Maven site... this > should be included in the build process of the project, as it's just > another deliverable, or artifact in the Maven vocabulary. And this > should be done using the Docbook stylesheets, as there is a lot of > effort put into them, and they're proved and reliable. Also I don't > think writing all this support into Doxia is neither sensible nor > possible. > > What do you think about this? > > Best regards > Jose > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
