Re: [ublas] Retiring the HTML documentation

From: Andreas Klöckner (kloeckner_at_[hidden])
Date: 2005-05-18 06:35:10

Gunter Winkler schrieb:
> Interesting. Is there a way to include parts generated by doxygen? There are 
> already some functions documented this way.

Can Doxygen output docbook? If so, there is a facility for including
Docbook sections, so I believe that this wouldn't be hard.

The main benefit of the conversion to Quickbook is that the
documentation would be more consistent (since there is "only one way to
do it" in Quickbook--as opposed to, for example, <pre>, <code>, <tt> or
combinations thereof, all of which are used for code examples in the
current documentation.) Dead links are reported during generation.
Arguably, the generated HTML also looks nicer, has syntax highlighting.
Further, tables of content and other boilerplate info is generated
automatically. One thing that my converter doesn't do (and will not) is
word-wrapping its output, which explains the long lines in ublas.qbk. I
imagine that would be done as needed by those who need to edit the
documentation. (M-q in emacs, gqap in vim)

If one of the UBlas maintainers indicate that there is an interest to
replace the current HTML with the Quickbook version, I would continue
working on this prototype.

Also, for those not immediately familiar with Quickbook: It is
maintained as part of the boost tree under tools/quickbook, and it
generates plain Docbook content from a simpler wiki-like markup. Joel de
Guzman wrote it based upon his Spirit parser framework, initially as a
"weekend hack" to make writing documentation for Boost.Python more fun.

> PS: I am not able to get your public key from pgp.net. Where did you upload 
> it?

Oops. Fixed. It was on sks.keyserver.penguin.de.

Andreas
-- 
--------------------------------------+-----------------------------
Andreas Klöckner                      | FON [phone]
Institut für Angewandte Mathematik II | FAX [phone]
Universität Karlsruhe                 | EMAIL kloeckner_at_[hidden]
Englerstraße 2                        |
76128 Karlsruhe                       | RAUM 022
Germany                               | Kollegiengebäude Mathematik
--------------------------------------+-----------------------------