Aslak, You raise some good points. Referring to what I said earlier, it would be worth using if all the developers if it was guarenteed that all the contributors had installed on their machine.
I'm going to play with it a bit more with some sample xdoc files and see if I can configure it to look right in html and pdf. If I can do this easily and to my satisfaction, then I'll put in a vote to use it. I'll might as well look into this right now. Ken ----- Original Message ----- From: "Aslak Hellesøy" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Thursday, December 12, 2002 7:10 AM Subject: RE: [OS-webwork] Documentation > > > > -----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 > ------------------------------------------------------- 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
