On 1/10/02 11:34 AM, "Gabriel Sidler" <[EMAIL PROTECTED]> wrote:
> "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. Not forever :) We can always move it as long as we do smart things re the code package. However, I think of it as 'special', because it's a bridge to another project, and it's much bigger than simply using a tool - a tool is self contained - the struts stuff by definition links to Struts things. I also have a donated table formatter to put in there when I get a free second. Velocity based. > > >> 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.... I don't think that's so bad. Lets keep struts out for now, but document the tools the same exact way - so then it keeps some visibility right now at the top, and if I am wrong, it's easy to fold in as we kept the same doc approach. How's that? > > [...] >>> 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. Yes - *technically* it's just a toolset. But for a user coming over from JSP-based Struts-land, it has to be a complete 'experience'. We can't just make it like another math tool - with the math tool, you have a clue what this velocity thing is all about, and then know that how to use it. With /struts, I suspect many people who look at it will be Struts users, or people evaluating Struts, and you can't have the requirement that they understand the "velocity way" first, or we will never get them to try it. We need to remember how much we know, and how we look at the world... > 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. Right - and technically you are right. 'Socially', there's a whole other bit we need to manage. > 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. Have fun :) > > >>> 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. The benefit is that the content .xml is the same for DVSL as for Anakia, if you use site.dvsl, as it is (supposed to be) compatible with jakarta-site2/stylesheets/site.vsl > > 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. Ok. I'll take a look. >> 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. Ok. -- Geir Magnusson Jr. [EMAIL PROTECTED] System and Software Consulting You're going to end up getting pissed at your software anyway, so you might as well not pay for it. Try Open Source. -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
