Bill, Agreed... we could keep the ant build as the official version, but put project.xml and maven.xml in as well to test the waters.
-Pat ----- Original Message ----- From: "Bill Burton" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Thursday, December 12, 2002 1:13 PM Subject: Re: [OS-webwork] Documentation > Hello, > > Mike Cannon-Brookes wrote: > > Ken, > > > > <snip/> > > > Personally I'd vote for xdocs without Maven at the moment, that gives us a > > good upgrade path to Maven (if we decide to use it) or to any other XML > > based doc format (as xdocs are XML files already). > > Sure. However, why not check in the Maven project.xml, > project.properties, etc. Aslak wrote so WW is "Maven aware." This > doesn't imply that Maven will be used officially but would allow any > developer with Maven installed to run it against WW to get the other > benefits it provides. > > Conceptually, this is really no different than included IDEA project > file already in WW. > > -Bill > > > -mike > > > > On 12/12/02 10:37 PM, "Ken Egervari [eXtremePHP]" ([EMAIL PROTECTED]) > > penned the words: > > > > > >>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. > >> > >>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
