On 1/10/02 6:20 AM, "Gabriel Sidler" <[EMAIL PROTECTED]> wrote:
> Geir, > I have fix and improved the documentation somewhat. I saw - very cool! > > 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... 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? We can always have build targets in the /tools subdir that produce jars of separate kinds of tools, and we certainly can organize by package in the source tree. > o A top level doc documents the tools support in general and points to > the existing tool categories. Yep - that was next when I found some time. That why I started sketching out the top level /lib, /xdocs and /docs. > 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 :) Same with view - I look at /view and /struts as 'special' structurally - it's not a toolset, but a little more.. > .... > > > 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. Of course, If we just javadoc nicely, the problem take care of itself... > > > Agree? > > Gabe > > > -- > Gabriel Sidler > Software Engineer, Eivycom GmbH, Zurich, Switzerland > > -- > To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> > For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> > -- Geir Magnusson Jr. [EMAIL PROTECTED] System and Software Consulting "We will be judged not by the monuments we build, but by the monuments we destroy" - Ada Louise Huxtable -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
