Boost logo

Boost :

Subject: Re: [boost] [autoindex] Rationale Question
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-05-06 13:17:10


> Form the very brief look into AutoIndex documentation I see.
>
>> ... AutoIndex will automatically scan one or
>> more C/C++ header files and extract all the
>> function, class, macro and typedef names that
>> are defined by those headers, and then insert
>> the <indexterm>s into the Docbook XML document for you.
>>
>
> However, there is a tool Doxygen that already does
> this.

I'm not intending to compete with Doxygen, this is tool for creating indexes
for *Docbook* produced documentation. Period. Full stop. Nothing more.

It's also an indexing tool only, it's absolutely not a tool for creating
content (like Doxygen or Quickbook).

> So there is a well debugged, tested, supported
> indexing tool (Doxygen) that as far as I know
> works fine and is already used by Boost.
>
> So the question are
>
> 1. How does it differs from Doxygen indexing?
>
> I'm not talking about the integration with
> various pars of Boost documentation toolchain
> but rather what it does differently.

Simple: I happen to like the documentation that you can create with
quickbook/boostbook/docbook very much, and frankly I prefer it to Doxygen
produced docs (and yes I've used Doxygen, I just don't like it that much,
sorry).

There's also absolutely no way I'm going to rewrite the Boost.Math docs in
Doxygen or indeed force the Spirit guys to do the same, yet both of these
libraries can benefit from documentation indexing.

AutoIndex also integrates nicely with libraries that use both docbook and
doxygen - since these two input formats get converted to a single big
docbook file - AutoIndex can index the whole of that documentation
seamlessly and not just the Doxygen part.

In other words it brings real gains to existing documentation right now, as
well as to new docs, and doesn't force folks to rewrite using some other
tool - just as they're not being forced to use *this* tool.

HTH, John.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk