[petsc-dev] Documentation comment support

[Jed Brown]

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