[petsc-dev] Documentation comment support

[Barry Smith]

On Dec 23, 2012, at 4:16 PM, Jed Brown <jedbrown at mcs.anl.gov> wrote:

> On Sun, Dec 23, 2012 at 9:56 AM, Karl Rupp <rupp at mcs.anl.gov> wrote:
> 
> 
> As for the cross-referencing manuals and man-pages: I talked with Barry about that two weeks ago, since I had to produce a HTML version of my PhD thesis:
>   http://www.iue.tuwien.ac.at/phd/rupp/
> I used tex4ht, which is still not perfect, but worked with reasonable effort. At least one can get reasonable HTML output from LaTeX.
> Maybe one could customize the anchors so that one can not only reference out of the HTML output, but also *into* the output - however, I still have to check that...
> 
> I think that is the most important part. I would love for the DMDACreate2d man page to have a link into that section of the manual, for example. PETSc's manual already has links running the other direction.

   My understanding is that in our manual pages we should be able to make links like http://www.mcs.anl.gov/petsc/petsc-current/docs/manual.pdf#nameddest=SNESSolve and when clicked on in the browser the browser would jump to that link in the pdf file; sadly I cannot get nameddest to work in ANY browser.

   However I could get #page=number to work correctly in both Firefox and Chrome (but sadly to an Apple dude, not Safari). So I suggest we scarf up the index created by make manual.pdf with a little python script and use it to add to each manual page something like

In users manual number, number, number    

where the user can click on the number and it jumps to the pdf page of that number so DMDACreate2d has a link to the page in manual.

Much nicer that using some ugly non-PDF presentation of the users manual.

Good idea, bad idea, ???

   Barry

We can add a message to Safari users to use another browser for this feature.


>  
> About two years ago I went through the deal.II documentation generator, at that time it used quite a number of scripts in order to extract the necessary information from the files. These were required to overcome some of the deficiencies of Doxygen at that time, e.g. math fonts and I think some cross-links. Meanwhile Doxygen also supports math formulae, and a couple of additional structuring mechanisms. I haven't tried any of the three items you mentioned, though...
> 
> Yeah, I see some hackery in doc/doxygen/tutorial/Makefile.
> 
> I might experiment with doxygen filters in a young project to see if it can be coerced into doing the things we'd like.