Hi Aslak, I would be nice to document also the template file being used by default, the interfaces that a class must implement to be considered, the default pattern being used, the minimum Tag that must be present. (I think that is all)
The default template file and the default pattern of generated file are absolutely needed imho to have a complete doc. We can maybe add them the xdoclet tag, create method in TemplateSubTask that will get the values from the xdoclet.xml at run time. What do you think ? Vincent > > > ----- Original Message ----- > From: "Vincent Harcq" <[EMAIL PROTECTED]> > Date: Wednesday, May 22, 2002 9:02 am > Subject: Re: [Xdoclet-devel] RE: task documentation > >> Hi, >> +1 for Docbook >> +1 for the minimum hand coding as well. >> I will have a look how a Subtask could be docletted (in the docu >> sense) but > > Ara, IIRC you had some plans about "merging" DocletTask and SubTask. > Will this have an impact on the job of docletting SubTask? > > Aslak > >> at first sight the problem will come from a lot of code that is done >> in the >> constructor that we are not able to see. Have somebody already think >> about >> xml-ized a SubTask definition ? > > Who cares about the code in constructor or anywhere else? Isn't it > enough to know what setBlaBla and createFooBar methods that are > available? These are the methods that correspond to Ant attributes and > elements respectively. > > Of course, since we're using DynamicConfigurator in DocletTask, we > can't figure out (by looking at a DocletTask class' createBlaBla > methods alone) what subtasks are available. In order to gather that > information, we need to look at ALL the module's SubTask sources and > group them according to the @xdoclet parent="XXX" class. (Where XXX is > the parent/enclosing DocletTask class). All the modules' sources are > copied over to xdoclet/modules/build/all-src/ so this is where the > subtask xdoclet should go and look for classes. > >> Vincent >> >> > Hi! >> > >> > I mentioned in an earlier mail that I'm working with Docbook >> (Stylebook> isn't maintained AFAIK). >> > Here is what I have discovered so far: >> > >> > DocBook is essentially a vocabulary maintained by Oasis. The DocBook >> > vocabulary is described in different ways. This means you can write >> > DocBook documents in different "dialects". We'll use the XML >> dialect,> which is described in the DocBook DTD. I have downloaded >> DocBook DTD >> > 4.1.2 from here: http://www.oasis-open.org/docbook/xml/index.shtml. >> > This will appear under xdoclet/lib/docbookx (when I commit it to >> CVS).> >> > There are various tools available (not maintained by Oasis) that can >> > render documents that conform to the DocBook DTD. There is a >> project on >> > SF (docbook.sf.net) which provides a bunch of XSL stylesheets >> that will >> > transform our DocBook XML documents to HTML or FO (for further >> > processing by Apache FOP to produce PDF). >> > >> > The transformation itself is done by Xalan or Saxon (I haven't >> settled> on which one to use yet) and invoked from Ant using the >> <xslt> task. >> > Pretty simple. >> > >> > DocBook will be used (at least for starters) to generate general >> > XDoclet documentation (the stuff which is currently in HTML under >> > xdoclet/core/docs/*.html). I'm converting these to XML right >> now. It's >> > a bit tedious, since I'm not familiar with the (enormous) >> DocBook DTD >> > yet. I might use some GUI editor to ease the job. >> > >> > TASKS/SUBTASKS >> > I reckon we have a good tool to do that job: XDoclet! We need a >> > template that will look for setXXX methods on subclasses of >> DocletTask> and SubTask. It also needs to look at some tags we >> have to define to >> > figure out whether a parameter is optional, what are the legal >> values> etc. This template could produce a DocBook XML, or it >> could produce >> > HTML directly. Since we have the opportunity to write it from >> scratch,> I think we should let it produce DocBook XML. This makes it >> easier to >> > incorporate it into the general DocBook documentation. >> > >> > TAGS >> > The current tag documentation is currently not based on DocBook, but >> > based on our own xtags DTD and a home-grown stylesheet. This works >> > great. Especially the awsome table sorting. Very useful, and we >> won't> get that with the DocBook stylesheets (unless we hack >> them). In the >> > long run, we should probably write an XSL that will transform >> xtags.xml> to a DocBook conformant XML. -So we can have all our docs >> in DocBook >> > and produce a nice PDF manual. (Low pri, but let's keep it in our >> > head). >> > >> > The current tag docs don't tell whether a tag is meant to be on >> class> level or method level (or field or constructor level for that >> matter). >> > We need a way to get that into the docs. Currently the >> information is >> > in the xtags.xml (in condition elements). We have three options: a) >> > Make the xsl smarter and extract the class/method level from >> the XML >> > using today's DTD >> > b) Add (redundant) information to the xtags DTD/XML that is >> easier to >> > grab with XSL >> > c) Swithc to Anakia and do the same as a) (might be easier with >> Anakia> than XSL) >> > >> > I'll await your comments and turn this mail into several TODOs. >> > >> > Cheers, >> > Aslak >> > >> >> -----Original Message----- >> >> From: Mathias Bogaert [mailto:[EMAIL PROTECTED]] >> >> Sent: 22. mai 2002 08:29 >> >> To: Aslak Helles�y >> >> Cc: [EMAIL PROTECTED] >> >> Subject: task documentation >> >> >> >> >> >> OK, we have tag documentation, template documentation, javadoc >> and a >> >> todo list. But how are we going to handle the task documentation? >> >> Stylebook? Or Docbook? Or also some sort of XML files with an XSL? >> >> >> >> Regards, >> >> >> >> Mathias >> >> >> > >> > >> > _______________________________________________________________ >> > >> > Don't miss the 2002 Sprint PCS Application Developer's Conference >> > August 25-28 in Las Vegas -- http://devcon.sprintpcs.co >> > >> > _______________________________________________ >> > Xdoclet-devel mailing list >> > [EMAIL PROTECTED] >> > https://lists.sourceforge.net/lists/listinfo/xdoclet-devel >> >> >> >> _______________________________________________________________ Don't miss the 2002 Sprint PCS Application Developer's Conference August 25-28 in Las Vegas -- http://devcon.sprintpcs.com/adp/index.cfm _______________________________________________ Xdoclet-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
