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

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-11-04 11:29:15

Douglas Gregor said:
> On Friday 01 November 2002 09:50 pm, Jeff Garland wrote:
>> As I said before, we don't really need to choose one extraction tool
>> or another.  We can use one or both.  I think the point that is being
>> missed here is that Doug has a proposal on the table, but to my eye it
>> looks like mostly an extension of DocBook.  What I see in Doug's stuff
>> looks like solid XML, but I don't understand how DocBook
>> extends so I'm just a little worried that the standard DocBook
>> tools will be less useful than we think...
>
> 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.

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.

> What I'm proposing is a layer of XML to represent C++, with a
> transformation  into DocBook. So, for instance, the example
> "function.xml" that I've been  working with is not actually a DocBook
> document -- it's just raw XML that  expresses C++ declarations. The XSLT
> stylesheet transforms that XML into a  DocBook reference section, and
> uses as many DocBook features as can  reasonably be used. For instance,
> it'll use <refentry> for class templates so  that each class template is
> considered one entity (e.g., one page in chunked  HTML output or one man
> page), and will identify the synopsis sections, man  page title, etc.
> But it won't use <funcprototype>, <classsynopsis>, or any of  the other
> code documentation features because they won't give us the C++
> Standard-like output that many Boost libraries seem to use.

Sounds very reasonable to me.

> The "whole" system might look something like this:
>
>
> +---------+
> | Doxygen |------+                                     +---------+
> +---------+      |                              +----->| (X)HTML |
>                  v                              |      +---------+
>              +---------+     +-------------+    |      +-----+
> +--------+ | C++ XML |---->| DocBook XML |----+----->| TeX
> |--->| PS/PDF | +---------+     +-------------+    |
> +-----+    +--------+
>                  ^                              |      +----+         |
> +----------+     |                              +----->| FO |---------+
> | Synopsis |-----+                                     +----+
> +----------+
>
> I've got a good start on the C++ XML -> DocBook XML conversion (that's
> what's  in the sandbox). I've been testing with DocBook XML->HTML (works
> fine, and we  don't have to change anything to do it), but I've also
> toyed with DocBook  XML->FO->PDF (not perfect yet, but getting better).

I really need to find the time to look at this stuff in depth ;).

> There's not really anything in this toolchain we could take out. Going
> from  Doxygen/Synopsis->DocBook directly would make things tougher,
> because we  would have to keep the formatting consistent between the two
> DocBook  generators and with authors not using either generator.
>
> We could go from the C++ XML directly to some other format (e.g., HTML,
> which  the prototype supports), but then we have to have backends for
> all output  format we need, and we have to have some other way of
> introducing  non-reference documentation. As I see it now, tutorials,
> design documents,  etc. could be written directly in DocBook (or
> transformed into DocBook from a  tool like reST), whereas reference
> documents would be transformed into  DocBook via the above flow-chart
> soup.

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.

> It sounds complicated, and it probably is, but I think we can make it
> easy to  use with a little work. The consistency and cross-referencing
> will be worth  it.

Amen.  And my thanks to you for heading up the effort so far.

And it would still be interesting if someone could provide the same (or at
least a portion of the same) using LaTeX, so that we can actually compare
the two intelligently.

-- 
William E. Kempf