Looking for documents that use DocBook API markup

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.

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

One way to get a bunch of api docs in DocBook in a hurry is
to run
dbdoclet <http://www.michael
-a-fuchs.de/> on some Java 

David 

> -----Original Message-----
> From: Paul DuBois [mailto:paulkitebird.com] 
> Sent: Wednesday, June 27, 2007 4:49 PM
> To: docbook-appslists.oasis-open.org
> Subject: [docbook-apps] Looking for documents that use

> DocBook API markup
> 
> 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.

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

kde documentation? (just a guess)

On 6/27/07, Paul DuBois <paulkitebird.com> wrote:
> 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.
>
>
------------------------------------------------------------
---------
> To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
> For additional commands, e-mail: docbook-apps-helplists.oasis-open.org
>
>


-- 
http://chris.chiasson.nam
e/

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org

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://w
ww.boost.org/doc/html/boostbook.html

It's specifically designed for documenting C++ libraries.
The
element reference for it is here:

  http://w
ww.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/

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 <smithsideshowbarker.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://w
ww.boost.org/doc/html/boostbook.html
>
> It's specifically designed for documenting C++
libraries. The
> element reference for it is here:
>
>   http://w
ww.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: docbook-apps-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-apps-helplists.oasis-open.org