Re: [docbook-apps] Looking for documents that use DocBook API markup

["Jere Käpyaho" <jere.kapyaho@gmail.com>]

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 <smith@sideshowbarker.net>:
> 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/
>
>