> -----Original Message----- > From: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED]]On Behalf Of > Ken Egervari [eXtremePHP] > Sent: 12. desember 2002 12:38 > To: [EMAIL PROTECTED] > Subject: Re: [OS-webwork] Documentation > > > Hi Mike, > > Well, we have a few issues. I'm thinking about the big picture > in that XML > some form of XSLT (or something else) is beneficial, but I also wanted to > stike a balance in that many people didn't want the bloated > libraries to be > involved (or to be abstracted away from them if they were). Maven seemed > like one of those projects. >
That's not quite how Maven works. Maven is something you install once in one single place on your machine. -Like your IDE for example. Then you can use that installed instance over and over again on different projects. So it's not a "library" that you bloat your project with. The only Maven "thingy" that would have to be part of the WebWork codebase would be the single project.xml file. Kind of like bundling e.g. your IDE project file (small), but not the whole IDE itself (big). Although Maven can be hard to grasp in the beginning I believe the effort pays back in the long run. The best way to migrate a project to Maven is actually to start using only its documentation features. Believe me, it's very easy. Just add a project.xml file and commit it to the root of the project. Then force all people who want to generate docs to install Maven locally on their machine. I think that if the WebWork development team is planning to use Maven as a build tool in the future, choosing an auxiliary documentation tool now is a step back rather than a step forward. Finally, the best argument I can think of to use Maven is what has come up in previous posts in this thread. Maven makes sure all the documentation is integrated in one static bundle. General docs, Javadocs, JUnit test reports, Clover coverage reports, PDF, HTMLised browsable source code, checkstyle reports, bla bla bla. It's also possible to customise the L&F of the docs that Maven produces. Cheers, Aslak > I just looked at cocoon for the past hour and it's too much for > what we have > to do. I can see this being useful for other projects perhaps, > but not this > one. I was just about to look at Forrest when I got your email, so I > decided to stop and read it. I'm pretty glad I did. > > I wanted to avoid the use with sitemesh since the documentation shouldn't > rely on a servlet engine. I mentioned this before, but I could also > generate a sitemesh-aware html version of the documentation that > strips out > the layout and allows sitemesh to take care of that. For local > documentation, however, sitemesh won't (and shouldn't) be > available. Tools > like XSLT can help generate both forms of documentation (the > website and the > local documentation). As far as coding 2 stylesheets to do those > transformations, that's not a big deal. I understand XSLT and > can make both > stylesheets in a couple of hours. This solves the layout > problems since it > also contains it in a single spot. > > The only reason I suggested using something like iText (or > another) is that > I'll have a lot more flexibility in the way I can build the PDF documents. > By looking at others, they seem to be very generic and don't > really provide > the feel for a book but rather a text file with a few text styles > and that's > it. I want to make a PDF that have a table of contents with links and a > bookmark list for easy navigating. Any technology that will do that > automatically is great, but fromt he examples I seen, they never took > advantage of those features I could also just use a simple > template method > pattern to encapsulate the layout as well. > > If the project is moving to maven, then maybe there is more merit to using > it. I don't like projects that try to tackle 100 different things. They > are hard to learn initially and they expect infrastructural configuration > and code in places that have no importance to the tool you need it for in > the first place. I'll have to look into it some more as I'm no expect on > it - I've read the website and downloaded it today and played > with it for a > bit. I liked the xdoc format, however and was planning on using that > regardless. > > For me, writing is actually the easier part so I wanted to tackle these > issues first. I'm one of those people that tries to tackle the > uncertainty > first so the rest of the project can run smoothly. > > If you have any comments than I have said here, be sure to let me know as > I'll keep my email client open. > > Regards & Thanks for the comments, > Ken Egervari > > --- > > 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
