On Jan 7, 2013, at 4:56 PM, Jed Brown <jedbrown at mcs.anl.gov> wrote:
> Karl, do you know a way to make man pages automatically link to use cases in > .../examples/tutorials/? (The other direction is fine and dandy, but the > reverse links are extremely useful.) Jed, Do you mean like the Examples section in http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMDACreate3d.html? but linking directly to the line that uses the function instead of just to the file? Barry > > It could be implemented in an input filter, but that would have to parse the > input well enough to know where to insert links to examples. > > > On Sun, 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: > Aside from the usual warnings a compiler has to issue if it detects a > potentially faulty use of a variable, is there really anything beyond > matching comments with the actual variable declarations? The release notes > just state: > > 'Clang parses the comments and can detect syntactic and semantic errors in > comments.' > > So even though in principle it *could* do all the nice traces and such, I > doubt that developers will make clang an all-in-one-suite-for-everything > including a documentation generator, because this monolithic thingy is > exactly what they complain about in GCC. > > Sure, but they already have a features like "this is uninitialized" that > trace through function calls. If someone passes in a real *foo as > @param[out], but the function itself depends on the value of foo[0], that > should be a documentation warning. I.e., some system should be able to > generate that warning. Meanwhile, it's most convenient for the compiler to be > the unified front-end to all warnings about your code. The main reasons are > > * configuration: only the compiler is guaranteed to see the right paths and > have the right macros defined > * interface: we run the compiler frequently and it's integrated into our > workflows > > > 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. > > 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. >
