[petsc-dev] Documentation comment support

[Karl Rupp]

Hi,

I haven't yet thought about the system proposed by Jed below. The reason 
for this mail is that interestingly the Eigen guys have just started a 
similar discussion a couple of days ago driven by the new capabilities 
of doxygen:

http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/2013/01/msg00001.html

A brief summary:
Out of five proposals, they prefer two variants, both being a big user 
and a big reference manual accessible via a common navigation tree:
  - Not tightly coupled. Includes cross references:
  http://eigen.tuxfamily.org/doc_test/4/

  - A slightly modified variant of the above with a different structure:
  http://eigen.tuxfamily.org/doc_test/5/
They will stick with this variant in the future.

Note the small 'search' field on the top right for both variants.

If I'm not mistaken, Eigen always preferred HTML manuals (user and 
reference) over a PDF version. With the issues of linking into PDFs 
showing up repeatedly, having everything in one place seems to be the 
better bet. It doesn't need to be Doxygen, though.

Best regards,
Karli



On 12/25/2012 01:49 AM, Jed Brown wrote:
> Here's a possible system that might be attainable. I probably won't
> implement in the near future. Maybe I'll get lucky and the wiki authors
> will fix the quirks. ;-)
>
> Basic idea is to have man pages generated from source code roughly as
> now, but "user's manual" stored as a wiki. The wiki source can be in the
> repository for convenient batch editing. Here are a couple example pages
> from a nicely-done project wiki that you can clone (git clone
> https://github.com/snowplow/snowplow.wiki):
>
> https://github.com/snowplow/snowplow/wiki/Technical-architecture
> https://github.com/snowplow/snowplow/wiki/SnowPlow-setup-guide
>
> This wiki system (named "gollum") is nice because it supports many
> markup dialects, stores all its data in a normal repository, supports
> mathjax, is open source (MIT license), and is hackable.
>
> Exporting as an attractive PDF is possible with MediaWiki (e.g.,
> download the PDF for http://en.wikibooks.org/wiki/LaTeX), but MediaWiki
> isn't backed by a versioned repository so you can't edit it offline.
> Gollum claims that it would be easy to write a PDF exporter as a plugin;
> I don't know if anyone has yet.
>
> Now we want cross-references between source documentation and wiki. The
> forward direction can be implemented as an input filter (e.g.,
> translating "[[Manual Section]]" appearing in source man pages to use
> the link keyword). Probably the nicest way to do the reverse would be to
> dynamically translate "wiki" URLs to display man pages. I'd have to look
> more closely to see if that would be implementable using a plugin or if
> it would need to modify the base system. Best would be to teach the wiki
> about doxygen-style autolinks (similar to PETSc, SomeFunction(),
> #ENUM_VALUE, ::SomeTypedef) so that natural text would produce those links.
>
> Finally, doxygen can do references with \cite{} and BibTeX. MediaWiki
> also has a BibTeX extension
> (http://www.mediawiki.org/wiki/Extension:Bibtex).