Can we also hide all the internal stuff? On Jan 12, 2013 6:21 PM, "Barry Smith" <bsmith at mcs.anl.gov> wrote:
> > Not bad. > > Any way to strip the ierr = and CHKERRQ(ierr); from all the html > versions of the source code. I find it cluttering and ugly. > > Barry > > On Jan 12, 2013, at 3:10 PM, Karl Rupp <rupp at mcs.anl.gov> wrote: > > > Dear PETScians, > > > > as indicated in a previous thread, I spent some time on investigating > what Doxygen can do for us (thanks to Peter for some pointers). I set > myself the constraint of not touching any existing sources in order to keep > the generation of FORTRAN stubs intact. > > > > Actually, it turns out that even under this harsh constraints, Doxygen > produces good results. Particularly the dynamic tree-view and the search > feature are very nice. Have a look here: > > http://krupp.iue.tuwien.ac.at/petsc-doxygen/ > > To keep the effort for this evaluation reasonable, only the first two > chapters of the user manual are currently migrated. > > > > The doxygen run is not integrated in any makefiles. One needs to run > doxygen (version 1.8.0 or higher) from petsc-dev/doc by > > $> doxygen ../src/docs/doxygen/Doxyfile > > > > Pros: > > - Three-way-linking: > > > > Examples > > / \ > > Man-Pages -- Manuals > > > > I injected a minor test case linking an example with a man page and > the developer manual: > > > http://krupp.iue.tuwien.ac.at/petsc-doxygen/docs_2doxygen_2examples_2ex1_8c-example.html > > > http://krupp.iue.tuwien.ac.at/petsc-doxygen/ex1_8h_a4204a07ed0f7e0571f0b2b934759b6b0.htm > > > http://krupp.iue.tuwien.ac.at/petsc-doxygen/dev-minimal-class-standards.html > > > > - Everything in one place > > - Convenient browsing using Tree-View > > - Search feature at the top right (yes, it should be 10x larger...) > > - BibTeX support > > - Just needs simple filters for the existing sources > > - Examples, References and 'Referenced by' automatically provided. I > think 'Referenced by' should be turned off, but I kept it for demonstration > purposes. > > > > > > Cons: > > - The manuals are converted partly by hand (see discussion below) > > - Size: The full output consumes 1GB. Some things can still be turned > off, though. > > - Link names: The URLs for the man pages contain some hash rather than > the function name. Former versions of Doxygen used to have the full > function name in the URL, similar to what sowing produces. > > - Group examples: I haven't found a way to group examples, there's only > the list of all examples > > - External Dependency rather than 'our own dependency'. > > > > > > The most time consuming part was/is the migration of the manuals. This > is partly a technical thing (Doxygen does not parse all LaTeX stuff, so > this needs to be filtered), but also a semantic thing. For example, in a > PDF you naturally refer to another Chapter by something like 'as we know > from Chapter 1 ...', while in an HTML document it is preferable to have > something like 'as we know from <a>the introductory discussion</a> ...'. > > > > Doxygen allows to have commands for switching between different output > targets, so in principle it would be possible to transfer the current > manuals to a markup-time format, which can then be used with doxygen as > well as for dedicated standalone PDFs as we have it now. For that to happen > it is essential to come to a conclusion on whether we want to use Doxygen > in the future, or whether we want to stick with the current tools. Barry? > ;-) > > > > Best regards, > > Karli > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130112/68e6e152/attachment.html>
