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 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 ? 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.com/adp/index.cfm > > _______________________________________________ > 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
