[autoindex] Rationale Question
Hello, It is not a review but rather questions about this tool rationale. 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. Doxygen is fully capable system for indexing source files and providing references for them. For example: http://cppcms.sourceforge.net/boost_locale/html/namespacemembers.html http://cppcms.sourceforge.net/boost_locale/html/namespacemembers_func.html 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. 2. Why have you decided to develop entirely new tool instead of using existing one. I probably miss some points but I rather see a great tool Doxygen that already does many things and does them well but still Boost creates its own tools (and this does not happen first time) Thanks, Artyom
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.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Artyom Sent: Friday, May 06, 2011 5:45 PM To: boost@lists.boost.org Subject: [boost] [autoindex] Rationale Question
Hello,
It is not a review but rather questions about this tool rationale.
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.
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?
It indexes *everything* in Docbook documentation text, not just the functions, macros ... that Doxygen does (and should be done by Doxygen in the Library Reference section). (Actually you can control what it indexes and what it doesn't, quite finely, and create sub-indexes, etc but the simple default action is to index everything). The *big* limitation of a Doxygen index is that you have to know (or guess) the name of the function/class... If you just want to know 'how to do something', you are stuck - and I often find I am :-) You can get the flavour of a trivial (silly even) demo/template at https://svn.boost.org/svn/boost/sandbox/guild/mylibrary/doc/mylibrary.pdf and bit more of the flavour of a small real-life Boost library refurbishment project at https://svn.boost.org/svn/boost-sandbox/guild/pool/libs/pool/doc/pool.pdf and if you are prepared to wait download 6 Mbyte https://svn.boost.org/svn/boost/sandbox/SOC/2007/visualization/libs/svg_plot... has quite full Doxygen function documentation AND an index of the documentation. None of these are as good as I would wish, but that's lack of time and enthusiasm, not the tool. So AutoIndex is *additional to*, not instead of Doxygen indexing. HTH Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
participants (3)
-
Artyom -
John Maddock -
Paul A. Bristow