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

["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/

smime.p7s