Re: [boost] Re: Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-11-04 12:45:48

On Monday 04 November 2002 11:29 am, William E. Kempf wrote:
> > Actually, I'm not extending DocBook at all. DocBook's support for
> > documenting  code is very Java/C-centric, and not nearly rich enough to
> > deal with  templates, specialization, or metafunctions. We could extend
> > it, of course,  but it would be a massive effort to introduce changes of
> > this magnitude into  DocBook... I'm not sure we're up to that.
>
> No, but letting the DocBook folks know about this effort would be a good
> idea.  They could take where we left off and incorporate a solution into
> DocBook, which would be a good thing for everyone.

Let's wait until we have something a little more substantial to show.

> Also, I've not had a chance to dig deeply yet, but I hope you're using
> DocBook tag names when they do exist.  Even if we don't have any hopes for
> this ever becomming part of the official DocBook, it would help the
> learning curve for anyone who knows DocBook.

Good point. At the moment, the tag names are different, but the structure is 
very similar. When I get a chance, I'll change the current syntax to (try to) 
make it a pure superset of the DocBook syntax. 

> I agree totally, and the use of tools like reST is what could make writing
> documentation simple!  But we need to figure out how to get all of this
> stuff to work together the way we want with little effort on the
> developers... and then document the heck out of how to use the various
> tools together.

I'm hoping that the Jam folks can help us out once we've gotten a bit further 
along. It would be really nifty if we could have Jam support for formatting 
the documentation. Wouldn't it be great to type "bjam pdf-doc" and get a PDF 
of all of Boost's documentation?

        Doug

P.S. I've now converted most of the Boost.Function documentation to DocBook w/ 
the C++ XML included. The chunked HTML output is here:
  http://www.cs.rpi.edu/~gregod/Boost/Function/