[petsc-dev] User manual converted to/for Doxygen

[Karl Rupp]

Dear all,

I've finally completed my conversion of the user manual to Doxygen. An 
online copy can be found here:
http://krupp.iue.tuwien.ac.at/petsc-doxygen/usermanual.html
This completes the raw conversion of the existing documentation to a 
doxygen-based system. Further polishing is certainly required, but 
certain parts may not be possible without actually touching the existing 
sowing-centered code comments in the source tree.

The not-so-ideal thing is that the LaTeX manual and the doxygen pages 
exist in parallel. Converting from either of them to the other is not 
possible in an automatic way. Thus, I suggest to introduce a unified 
Markdown-like format, from which we can generate both types of 
documentation.

Some customizations is certainly necessary because of the way the text 
needs to be written. For example, in a PDF it is natural to write
"Further explanation is given in Chapter 42", while in an HTML 
documentation one ideally provides a link of the type
"[More information on Foo]". Similarly, some large code snippets 
included directly in the PDF manual can be linked easily within an HTML 
documentation.

Best regards,
Karli

PS: To avoid confusion: PETSc will keep its existing documentation 
system for a while. We did not yet agree on the/any future of this 
doxygen-based approach.