Hani, That's pretty much my opinion about Maven and Cocoon (minus all the antagonism towards Jakarta and related OSS projects :P).
I want to build something simple, but I also want to have the flexibility to do the 3 things we need: HTML (for local use), JSP (as currently being used) and PDF. In the case of PDF, the actual generated document should be very different than the html version, but in some of the projects I've look at, they have degenerated the content of a PDF file to be as low as a simple ASCII document with a few uses of text styles and colours. In my view, this isn’t a powerful utilize PDF documents since it would probably be productive and efficient to use plan ASCII then. To get the desired quality for our documentation, we need to use different tools rather than a generic tool that is less powerful. I mean, the only thing that relates HTML to PDF is the content itself. However, the way the content is organized, its presentation, the usability issues, etc. are completely different when you compare PDF to HTML. A generic tool doesn’t really play to the strengths of either. This is why I considered hand-written XSLT documents and a simple Java program to make PDF documents. I figured it was important to make ‘quality’ documentation rather than ‘easy-to-generate’ documentation’. This approach is still very simple. It doesn’t rely on any complex frameworks. The main principle for our documentation should be: “it only generates documentation and it does it well”. Personally, I really like this approach despite some of the upfront work to make it happen. I had a lot of ideas as to how the PDF document was going to look and iText/SAX (or some higher level xdoc library) seemed like a pretty way to make quality and customized documentation. Of course, this is up to debate and if I’m wrong here, that’s okay too. I just want to do the best possible work for the project. That’s really what this is all about :) Suggestions are always welcome. Regards, Ken Egervari ----- Original Message ----- From: "Hani Suleiman" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Thursday, December 12, 2002 6:52 AM Subject: Re: [OS-webwork] Documentation I'm actually fairly strongly against maven. It's a huge project, and almost all of the websites produced by it have a cookie cutter feel to it. I also disagree with it being 'the way of the future'. It might be a fashionable choice for many OSS projects, but so are a lot of other things that have little beyond 'coolness' factor attached. I have no objections to xdocs, as it'd actually be a useful relevant tool for the point at hand. Bringing in maven just to use xdocs though is like buying a house with toolshed attached when all you wanted is a screwdriver. It's not a case of 'not invented here', it's a case of 'not jumping off the same lemming cliff that everyone else does, just because everyone else is'. A severe example of this is xdoclet. It's a great tool, I use it and rely on it completely. However, whenever I've tried working on bits of it to improve/contribute, I throw my arms up and give up, because it's so damn unwieldy. Having to installl maven just to read the cvs docs makes me very suspicious. Heck, someone even thought it necessary to internationalise the build messages! Featuritis gone mad, from where I stand (sorry Aslak!). Webwork's beauty to me is precisely because I don't have to commit to 20 other jars just to get trivial stuff to happen. While that too might be 'the way of the future' (if you consider the future to be jakarta projects + jakarta project wannabes), it'd be a sad day for webwork to conform to that particular wave. I know this argument has come up before, and I hope this thread doesn't degenerate into another flamefest (hilarious as I found the last one). So please take my comments for what they are; a heartfelt plea from the webwork user/occasional contributor gallery. On Thursday, December 12, 2002, at 06:03 AM, Mike Cannon-Brookes wrote: > Ken, > > You bring up a lot of interesting things here, I’ll try to reply below > (note: I’m far from a documentation expert). > >> Well, I've been looking at a bunch of technologies that we can use to >> build >> the documentation, but I'm not convinced that Maven will help us. >> Maven is an >> interesting project in that it does a hundred different things, but >> in terms >> of simplicity and the information available on the website, it's not >> there. I >> think the documentation generation features are not nearly as >> important in the >> developer's minds in comparison to the project information, tools to >> simplify >> build/test cycles and all the other stuff it does. It also seems to >> integrate >> with Turbine and all these other frameworks that I didn't know exist. >> I think >> if people were worried about bloating this part of the project with a >> tool >> like Xalan, then they would definitely have some pretty strong >> opinion to not >> using Maven (I think I agree with them). Since we aren't using Maven >> for it's >> other strengths, it's kind of clumsy to start using it for >> documentation now >> when simpler solutions make more sense. > > I think people suggested Maven because it's 'the way of the future'. > We have > just started to use it at work, and it is fantastic once you get it > running. > As far as producing 'simple' documentation, it is very good. It uses > xdoc > from Apache, which would be my preferred way to generate the > documentation > (it's very simple, and 'mere mortals' can actually use it to write!). > >> I seriously think simple tools like Xalan are more than enough because >> everyone probably has them in their classpath already, but I'm >> looking into >> Cocoon and Forrest right now (I'll put up another post to the >> newsgroup about >> my opinions on those) to see if they can simplify the required >> plumbing. > > Cocoon and Forrest are huge overkill here I feel. > >> I'm much more interested in offline documentation generation where I >> can >> simply include the static documents, the PDF files and the source >> code to >> build all of that (rather than include the necessary targets in the >> build.xml). It doesn't make much sense to have every person in >> WebWork have >> these documentation generation tools on their computer right now >> since we >> haven't rolled out the documentation yet. I would only include the >> documentation generation code and jars into the build.xml when we have >> something we are happy with. > > Well, I'm quite sure WebWork will end up using Maven after 1.3 (ie in > the > next few months), so using it to build documentation probably makes > sense > there. As for simplicity, it couldn't be easier to generate 'maven > doc' :) > >> iText was another library I was thinking about using due to its >> simplicity and >> flexibility. I'd need to code a few Java classes to convert the xml >> document >> to PDF, but this wouldn't take more than a day. Again, I would only >> do this >> just so we wouldn't need a full-blown framework like Cocoon or >> Forrest. Like >> others have said, it's not a good idea to have Webwork developers or >> the user >> base that compiles from the source to be dependant on Cocoon or >> Forrest and I >> agree with that. I'd like to look into them anyway just so I know >> for myself >> how they work. If one of them will truly make our job much simpler >> to the >> point where I don't have to write a line of Java code, then I'll >> consider >> them. Otherwise, I don't see the point to use them. > > Gah! Let's not fall into the 'not invented here' syndrome, surely we > don't > need to write any tools to do this. > > This is why people suggested HTML, it's much _simpler_! :) > > The point is, surely the tools are an ancilliary issue? It's fairly > trivial > to move between tools at any time (half an hour of copy / paste at the > most). Let's concentrate on the big issues! > >> Since the documentation is going to be static pages, I'll have to >> redesign the >> layout of the documentation obviously. This means that the left-side >> will be >> a little different to accommodate the documentation while I'll >> probably keep >> the top bar very similar. We also need to coordinate integrating >> this on the >> www.opensymphony.com <http://www.opensymphony.com> website as well >> as it >> won't use sitemesh or whatever other gadgets the site is using now. >> These >> issues aren't a huge rush, but we could begin to talk about them. > > Well, that's the beauty of SiteMesh - just drop the documentation in > and it > will be decorated automatically. The actual HTML produced should be > _very_ > simple, and use CSS to style everything. That way we can reuse it in > many > places. > > Again - concentrate on the bigger issues of writing it, adding / > moving a > logo is trivial! > > Good thoughts though all of them - it's great to have someone thinking > about > it. My advice, let's start simple and just get things down first - we > can > worry about the details of the layout / tools later? > > -mike > >> Regards, >> Ken Egervari >> > > > > > ------------------------------------------------------- > This sf.net email is sponsored by: > With Great Power, Comes Great Responsibility > Learn to use your power at OSDN's High Performance Computing Channel > http://hpc.devchannel.org/ > _______________________________________________ > Opensymphony-webwork mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > ------------------------------------------------------- This sf.net email is sponsored by: With Great Power, Comes Great Responsibility Learn to use your power at OSDN's High Performance Computing Channel http://hpc.devchannel.org/ _______________________________________________ Opensymphony-webwork mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork ------------------------------------------------------- This sf.net email is sponsored by: With Great Power, Comes Great Responsibility Learn to use your power at OSDN's High Performance Computing Channel http://hpc.devchannel.org/ _______________________________________________ Opensymphony-webwork mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
