<div dir="ltr"><div class="gmail_extra">On Tue, Jan 8, 2013 at 11:35 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_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div id=":5h1">I could only find a manual way:<br>
<a href="http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample" target="_blank">http://www.stack.nl/~dimitri/<u></u>doxygen/manual/commands.html#<u></u>cmdexample</a></div></blockquote><div><br></div><div style>
But that is writing "\example someexample.cpp" in the API man page. I want that link automatically when we _call_ the function from any example in EXAMPLE_PATH, without messing with the API man page.</div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div id=":5h1"><br>
HTML output is here:<br>
<a href="http://www.stack.nl/~dimitri/doxygen/manual/examples/example/html/examples.html" target="_blank">http://www.stack.nl/~dimitri/<u></u>doxygen/manual/examples/<u></u>example/html/examples.html</a><br>
<br>
Basically, you just need to set EXAMPLE_PATH to the respective example directories. It creates two-way references, but it does not link directly to the respective *line*. It should be possible to inject such \example blocks automatically into source files before creating the documentation...<div class="im">
<br>
<br>
<br>
<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<br>
    reference) over a PDF version. With the issues of linking into PDFs<br>
    showing up repeatedly, having everything in one place seems to be<br>
    the better bet. It doesn't need to be Doxygen, though.<br>
<br>
<br>
What are the alternatives? Doxygen seems to be much more popular than<br>
any alternative for API documentation (man pages). For HTML manuals,<br>
there is doxygen (best integration with API docs), Sphinx (popular, but<br>
only well integrated with Python), wikis (no a priori integration, but<br>
maybe hackable), and LaTeX (one-way integration in PETSc by our<br>
preprocessing).<br>
</blockquote>
<br></div>
I'm not aware of other alternatives. What I was trying to point out is that I'm not a Doxygen militant, I'm open to whichever tool provides the best results.<br>
<br>
I just went over the list of new features and was actually surprised by the many new features added to Doxygen during 2012, particularly Markdown support since 1.8.0:<br>
  <a href="http://www.stack.nl/~dimitri/doxygen/changelog.html" target="_blank">http://www.stack.nl/~dimitri/<u></u>doxygen/changelog.html</a></div></blockquote><div><br></div><div style>Yeah, Markdown support increased my interest significantly.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div id=":5h1">
Thus, Doxygen is presumably the better option over wikis anyway, even if we ignore the burden of hacking existing wiki systems.</div></blockquote></div><br></div><div class="gmail_extra" style>This isn't clear to me. Doxygen is all static so even minor doc fixes necessarily involve a context switch (to find the file in your editor) and you don't see results immediately. Gollum and Gitit are hosted in a normal repository so you can work on them offline and use normal tools for batch processing. Writing a Doxygen input filter to convert [[Some Wiki Page]] in source code to fully marked up links would be very easy, so the only "hacking" would be the reverse links (from wiki to API man page). So I'm not sold either way.</div>
</div>