[petsc-dev] Documentation comment support

[Barry Smith]

On Dec 23, 2012, at 8:40 PM, Matthew Knepley <knepley at gmail.com> wrote:

> 
> On Sun, Dec 23, 2012 at 9:27 PM, Barry Smith <bsmith at mcs.anl.gov> wrote:
> 
> 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.
> 
> Is there any way to see what URL this thing is actually following in the browser and debug the failure?

   I didn't see anything obvious. If I just put gibberish instead of nameddest like #sdfsfs=value   it doesn't complain just loads the PDF so I don't know if it is ignoring the nameddest or if pdflatex is not putting the right thing in.   

    Using the #page=number requires a bit more work on our part then nameddest but does allow us to have links to multiple places in the manual.

  Barry

> 
>    Matt
>  
>    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.
> 
> 
> 
> 
> -- 
> What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead.
> -- Norbert Wiener