Hi all, dbdoclet is great, but at least the pre 1.x versions were somewhat difficult to customize for publishing in the format we wanted, without hacking the source code and creating custom versions. That might have improved since.
I've been working on a toolchain that uses the JavaDoc API from a custom doclet and creates intermediate markup, which is very close to the old abandoned Apache JavaDoc DTD. That markup is transformed into DocBook with an XSLT stylesheet, and the rest is fairly standard (to HTML or to PDF). Contrary to what Michael wrote, the DocBook markup for reference pages and object-oriented concepts has worked pretty well for me, without the need to create a customized DocBook schema. That impression might change if and when I introduce generics and other Java 5 features. BoostBook was new for me; interesting but not immediately useful to me, given that I just got this system off the ground for internal use. Best regards, Jere P.S. Mike, you probably got this twice. Sorry... 2007/6/28, Michael(tm) Smith <[EMAIL PROTECTED]>:
Hi Paul, > @2007-06-27 16:48 -0500: > I need to mark up some API information that includes classes, methods, > functions, and so forth. It would be helpful to be able to look at > some "prior art". Can anyone point me to some DocBook source that > uses elements such as <classsynopsis>, <methodsynopsis>, <ooclass>, > <funcsynopsis>, etc.? Thanks. In my experience, people who venture out to do serious work on API documentation using DocBook often find that the standard set of elements for object-oriented programming that DocBook provides is nowhere close to being adequate for the task (which is mostly sorta by design[1]). If you end up finding that to be the case for your situation, I guess the way to handle it is to either create a DocBook schema customization/extension on your own, or to try to find and re-use extensions that others have made. Along those like, you might want to take a look at BoostBook - http://www.boost.org/doc/html/boostbook.html It's specifically designed for documenting C++ libraries. The element reference for it is here: http://www.boost.org/doc/html/reference.html The code, including an XSL stylesheet customization layer for generating output from it, is here: http://boost.cvs.sourceforge.net/boost/boost/tools/boostbook/ I just learned about BoostBook myself on #docbook IRC the other day from Stefan Seefeld (who I think has put a lot of thought himself into ways to produce better API documentation using DocBook). Anyway, from what I've seen from looking through the docs and code for it so far, it looks to be pretty well designed. --Mike [1] By design, the set of elements that DocBook provides for marking up "inlines for modern programming languages" (to borrow the description from the DocBook RFE in which it was proposed, RFE 96): - is not intended to model code - is not biased toward any particular programming language (C++ or Java or whatever) but intended instead to be useful across a "wide range of object-oriented language semantics" So those design principles (intentionally) limit the degree to which standard DocBook can be used/useful for marking up API documentation for any particular programming language. I think the expectation was the people/organizations would extend on it to more closely meet their particular needs (as BoostBook has). -- Michael(tm) Smith http://people.w3.org/mike/ http://sideshowbarker.net/
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
