On Mon, 2002-06-03 at 09:09, Berin Loritsch wrote: > > From: Jason van Zyl [mailto:[EMAIL PROTECTED]] > > > > Hi, > > > > Was just chatting with Bob in IRC about supporting Latex > > within Maven as a documentation tool and I know that Cocoon > > will be an option too so does anyone have any thoughts on how > > to handle this generically. > > > > I know a couple of projects, including drools, that have a > > lot of Latex documentation so it would be good to support (in > > addition to Latex being very cool) and tons of people use > > Cocoon so I think it would be good to support that option as well. > > > Here is where I start spouting my Component Oriented Programming > doctrine :)
I've got no problem with that :-) > Plugins are a type of plugin, so in order for it to work, we need > to define the contracts and relationships with Maven. > > In this case we are talking about documentation, so we need to > understand commonness and differences between the documentation > standards. > > First: Documentation formats for TeX/LaTeX, Cocoon, and DVSL > are all very different. Cocoon is pretty flexible in that it > can work with any XML format (I don't recall if LaTeX uses something > different from XML or not...). DVSL templates are basically just > a way to add more formatting to a minimalist HTML file. (Yes I know > that they can be used with generic XML, but I haven't seen any > templates that allow better semantic representation of the documents > like DocBook affords). > > Given that fact, and the fact that different projects may have > different standards for documentation, we cannot force a standard > XDoc format. I think one should be suggested. Here I am personally more concerned with comprehension than allowing every possible condition. I am all for moving toward something like docbook simple or even docbook. I like the simplicity of the anakia format but documentation isn't really an arena for infinite possibilities, I think the requirements are finite and that a single format should be decided upon for consistency. > Second: Not all engines provide standard stylesheets that can be > easily exchanged (instead they are site-wide or computer wide settings). > However, we do need to work with systems like DVSL/Cocoon that allow > you to specialize the look & feel--or at least work with different > source > documents. > > So the two contracts we can really extend to the document rendering > tools are 1: the directory where the source docs are located, and 2: > the directory where the control/stylsheet docs are located. These are the sorts of things I consider to require flexibility only where absolutely necessary. I don't want to end up with every project having artifacts in any number of locations. This is the situation now and it's hard to find anything. I am not a proponent of myriad possibilities in this type of scenerio. It is certainly required for integration but it's something I would like to prevent as a whole. I say let the creativity flow at the application level but as far as build/project management things should be fairly regimented. For new projects adopting Maven I don't think there will be many reasons to stray from what we define and for projects who currently have settings that are slightly different I think it is in everyone's best interested that they converge on what is decided on as a standard practice in this particular case the format of the documents, say docbook, and the location of the transformations. As far as the rendering system I can back off my dogmatic approach somewhat because I understand users wanting to eat their own dogfood i.e. if someone wanted to put in the effort to plugin cocoon then cool. This wasn't the opinion that I started with but I'm not, and can't, ignore users who really want to use something else. Here I can only think of Cocoon as an example but I'm sure others might crop up. > > -- > To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> > For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> -- jvz. Jason van Zyl [EMAIL PROTECTED] http://tambora.zenplex.org -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
