Here are my thoughts: 1. Someone mentioned on the list that the current xtags.xml are not strong enough to do the validation he required, and he proposed we should look into XML Schema to use for this. But offcourse, this is again more work. I like the current way, the XSL renders the docs nicely.
2. Yes, I like the idea of a fully generated documentation. We should however still include concrete, real-world examples of xdoclet build files. 3. Definatily low priority. For the stylebook: IMO a left and right frame is easier to navigate than an integrated TOC like the cactus one. And since we will have a pretty large TOC (lotsa modules), it is not reset every time you go to another page (reload). I would also use the XTree for all navigation. Regards, Mathias -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] Sent: donderdag 16 mei 2002 11:22 To: Mathias Bogaert Cc: [EMAIL PROTECTED] Subject: [Xdoclet-devel] Strategies for doc generation Here are some thoughts about the strategy for module generation. Please read, please comment. All the module-specific docs can be generated from "information" provided by each module. This could be: 1) xdoclet/modules/foo/src/META-INF/xtags.xml This file is hand-written, and should be maintained by the module authors. We are already able to generate a nice table describing the tags. Done with XSLT. result: xdoclet/dist/docs/tags/foo-tags.html 2) xdoclet/modules/foo/src/xdoclet/modules/foo/FooSubTask.java We can add @tags on the setFoo and createFoo methods. Then use XDoclet to generate subtask docs. (describing what to put in the build.xml scripts) result: xdoclet/dist/docs/subtasks/foo-subtask.html This needs to be done. 3) xdoclet/modules/foo/src/xdoclet/modules/foo/FooTagsHandler.java We already have a documentation "engine" for taghandlers. However, I think we should give this low priority, as it is only xdoclet module developers that care about these docs. Users first! Besides, when we move to Velocity (which I expect start pretty soon on a VELOCITY branch after our next release), taghandlers will disappear, and we'll need a different documentation system for that part of XDoclet. Today, these documents mentioned under 1) and 2) are hand-written. They are also in the same document. I suggest we keep them separate. The core docs (tutorial, architecture, general blabla) can be generated using stylebook. That means that we maintain this doco in XML documents. Stylebook converts it to HTML using an XSL-based skin we can tailor to our taste. If we go for stylebook, it would be nice to have the TOC for modules in the left menu (see cactus site). In order to achieve that, we can have the book.xml (the source of the left stylebook menu) generated from a book.xdt. This template would fill in the links to the module docs. We should come to a consensus on these matters quickly, since it has an impact on what strategy we choose for generating the docs. -Especially on the generation of the modules-toc which Mathias is working on right now. Thoughts? Aslak _______________________________________________________________ Have big pipes? SourceForge.net is looking for download mirrors. We supply the hardware. You get the recognition. Email Us: [EMAIL PROTECTED] _______________________________________________ Xdoclet-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-devel _______________________________________________________________ Have big pipes? SourceForge.net is looking for download mirrors. We supply the hardware. You get the recognition. Email Us: [EMAIL PROTECTED] _______________________________________________ Xdoclet-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
