<div dir="ltr">On Tue, Jan 8, 2013 at 9:54 AM, Karl Rupp <span dir="ltr"><<a href="mailto:rupp@mcs.anl.gov" target="_blank">rupp@mcs.anl.gov</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi,<br>
<br>
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:<br>
<br>
<a href="http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/2013/01/msg00001.html" target="_blank">http://listengine.tuxfamily.<u></u>org/lists.tuxfamily.org/eigen/<u></u>2013/01/msg00001.html</a><br>
<br>
A brief summary:<br>
Out of five proposals, they prefer two variants, both being a big user and a big reference manual accessible via a common navigation tree:<br>
- Not tightly coupled. Includes cross references:<br>
<a href="http://eigen.tuxfamily.org/doc_test/4/" target="_blank">http://eigen.tuxfamily.org/<u></u>doc_test/4/</a><br>
<br>
- A slightly modified variant of the above with a different structure:<br>
<a href="http://eigen.tuxfamily.org/doc_test/5/" target="_blank">http://eigen.tuxfamily.org/<u></u>doc_test/5/</a><br>
They will stick with this variant in the future.<br>
<br>
Note the small 'search' field on the top right for both variants.<br></blockquote><div><br></div><div style>They should make that box 10x bigger. ;-)</div><div style><br></div><div style>Those cross-references still look one-way. Is there a way to make a two-way link, so that anywhere I mention X, the man page for X includes a link the other way?</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
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.<br>
</blockquote><div><br></div><div style>What are the alternatives? Doxygen seems to be much more popular than any alternative for API documentation (man pages). For HTML manuals, there is doxygen (best integration with API docs), Sphinx (popular, but only well integrated with Python), wikis (no a priori integration, but maybe hackable), and LaTeX (one-way integration in PETSc by our preprocessing).</div>
<div style><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Best regards,<br>
Karli<div class="HOEnZb"><div class="h5"><br>
<br>
<br>
<br>
On 12/25/2012 01:49 AM, Jed Brown wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Here's a possible system that might be attainable. I probably won't<br>
implement in the near future. Maybe I'll get lucky and the wiki authors<br>
will fix the quirks. ;-)<br>
<br>
Basic idea is to have man pages generated from source code roughly as<br>
now, but "user's manual" stored as a wiki. The wiki source can be in the<br>
repository for convenient batch editing. Here are a couple example pages<br>
from a nicely-done project wiki that you can clone (git clone<br>
<a href="https://github.com/snowplow/snowplow.wiki" target="_blank">https://github.com/snowplow/<u></u>snowplow.wiki</a>):<br>
<br>
<a href="https://github.com/snowplow/snowplow/wiki/Technical-architecture" target="_blank">https://github.com/snowplow/<u></u>snowplow/wiki/Technical-<u></u>architecture</a><br>
<a href="https://github.com/snowplow/snowplow/wiki/SnowPlow-setup-guide" target="_blank">https://github.com/snowplow/<u></u>snowplow/wiki/SnowPlow-setup-<u></u>guide</a><br>
<br>
This wiki system (named "gollum") is nice because it supports many<br>
markup dialects, stores all its data in a normal repository, supports<br>
mathjax, is open source (MIT license), and is hackable.<br>
<br>
Exporting as an attractive PDF is possible with MediaWiki (e.g.,<br>
download the PDF for <a href="http://en.wikibooks.org/wiki/LaTeX" target="_blank">http://en.wikibooks.org/wiki/<u></u>LaTeX</a>), but MediaWiki<br>
isn't backed by a versioned repository so you can't edit it offline.<br>
Gollum claims that it would be easy to write a PDF exporter as a plugin;<br>
I don't know if anyone has yet.<br>
<br>
Now we want cross-references between source documentation and wiki. The<br>
forward direction can be implemented as an input filter (e.g.,<br>
translating "[[Manual Section]]" appearing in source man pages to use<br>
the link keyword). Probably the nicest way to do the reverse would be to<br>
dynamically translate "wiki" URLs to display man pages. I'd have to look<br>
more closely to see if that would be implementable using a plugin or if<br>
it would need to modify the base system. Best would be to teach the wiki<br>
about doxygen-style autolinks (similar to PETSc, SomeFunction(),<br>
#ENUM_VALUE, ::SomeTypedef) so that natural text would produce those links.<br>
<br>
Finally, doxygen can do references with \cite{} and BibTeX. MediaWiki<br>
also has a BibTeX extension<br>
(<a href="http://www.mediawiki.org/wiki/Extension:Bibtex" target="_blank">http://www.mediawiki.org/<u></u>wiki/Extension:Bibtex</a>).<br>
</blockquote>
<br>
</div></div></blockquote></div><br></div></div>