"Geir Magnusson Jr." wrote: [...] > > I'd like to define a documentation structure and templates for the tools > > such that I can document them step by step. Here a proposal (repeating some of > > today's facts just to be clear): > > > > o We have categories of tools. Each category get its subdirectory below > > jakarta-velocity-tools, for example > > > > jakarta-velocity-tools/view - toolbox, tool loader, > > jakarta-velocity-tools/struts - tools for struts integration > > jakarta-velocity-tools/math - math tools > > jakarta-velocity-tools/forms - HTML form validation tools > > ... > > Hm. Ok. I was thinking we bundle everything besides view and struts under > one pile, /tools. > > I thought about it this way because > > 1) view is different than a tool > 2) Struts is 'special' - it's a combination of specific tools, > documentation, examples, etc...
To 1) Yes, I agree. To 2) I would't treat Struts in any special way. Many of the tools I'd like to see added in the future will need documentation, examples, etc. very much like Struts (just to illustrate, I am thinking of tools like Dave Winterfeldt's form validation framework and the powerful table formater that is growing at http://edhill.its.uiowa.edu/display-examples/). I see struts as just one among many tools and wouldn't give it a special place in the directory hierarchie. It will leave us with an inconsistency forever. > I am not married to the idea, but what I am afraid of happening is that > there will be a huge # of cross dependencies between the various tool > 'groups'. > > For example, something in /forms uses a tool from /math... (not a great > example, but illustrates the point...) > > Comments? I see your concern but personally I am not really much worried that dependencies will become a serious problem. Tools that depend on each other should be in the same group (package). Groups shoundn't be too fine-grained. Common tool sets can be taken care of with special build targets. Considering all this, I think my favourite structure would be: jakarta-velocity-tools/ view tools/ struts math form table ..... Not very nice is the tools/tools part. Can't think of any better solution right now.... [...] > > o Each tool category has it tutorial-style doc about purpose, applications, > > examples. It points to reference docs for each tool within that tool > > category. > > Huge +1 > > > o Each tools has a reference-style doc about supported methods, parameters, > > etc. > > Definitely. > > > > > This would make the following structure: > > > > jakarta-velocity-tools > > docs > > index.html - top level tutorial > > view > > docs > > index.html - view tools tutorial > > toolX.html - reference doc for toolX > > toolY.html - reference doc for toolY > > struts > > docs > > index.html - struts tools tutorial > > toolX.html > > toolY.html > > We can start this way for struts, but should be careful we don't force the > Struts package to conform, as it's more than a toolset, right? It's a way > of life :) Well, I wouldn't go that far :-) As above, I wouldn't give Struts a special place in the hierarchy... > Same with view - I look at /view and /struts as 'special' structurally - > it's not a toolset, but a little more.. Yes, /view is special. /struts is just a toolset. That really is one of the cool things about this Struts integration. We don't do any special hacks, tweaks or work arounds. We have the simple concept of a toolbox with loadable tools and using this simple concept we are able to interface Velcity with Struts. I just like to reduce problems to simple bits that can be dealt with with simple solutions. :-) That's at least the technical side. On the documentation side struts is probably one of the more complex tools that will be integrated and therefore will need some special effort there. > > Templates for the following are needed: (for dvsl) > > - tutorials (at top level and tool category level) > > - tool reference documentation > > Hm. Why can't we use the current site.dvsl for the tutorials, so it looks > like every other piece of doc here in Jakarta-land? > > Maybe I agree with you for the references, but still - if we can add that > concept to the site.dvsl, then other projects can format the same way. I didn't want to suggest that we use anything else than the site.dvsl. I studied DVSL yesterday in a little more detail. It's a great tool and I definitely think we should use it for the docs. I was thinking more in terms of content. For me the nice example is the php documentatation at for example http://www.php.net/manual/en/ref.calendar.php Each function group has a tutorial-type overview and a one-page reference documentation for each function. > Of course, If we just javadoc nicely, the problem take care of itself... I think template designers shouldn't have to deal with javadoc. o Javadoc contains too much information that is not relevant to the template designers o Working with long HTML texts in Java files is quite cumbersome and the formating options limited. I'd rather use DVSL for the designer's documentation. Gabe -- Gabriel Sidler Software Engineer, Eivycom GmbH, Zurich, Switzerland -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
