[petsc-dev] Documentation comment support

[Matthew Knepley]

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=SNESSolveand 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?

   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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20121223/a7eb6af3/attachment.html>