<br><br><div class="gmail_quote">On Sat, Aug 18, 2012 at 5:36 PM, Michael Lehn <span dir="ltr"><<a href="mailto:michael.lehn@uni-ulm.de" target="_blank">michael.lehn@uni-ulm.de</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Am 18.08.2012 um 11:32 schrieb Matthieu Monrocq:<br>
> I must admit that the .doc file looks pretty weird (format-wise), especially the *---[XXX]---* parts, with | delimiters etc... but after looking at all the different things that can go within it, I suppose it makes (some) sense. I would still advise to make it more lightweight by removing the trailing | (and blanks),<br>

<br>
As an alternative, more lightweight notation I already have<br>
<br>
--- CODE -----------<br>
// some code example<br>
--------------------<br>
<br>
Only the 3 dashes before and after CODE are required (the rest is optional).  The block must<br>
be ended with at least 6 dashes.  The indent of "--- CODE ---" and "------" has to match.<br>
As code snippet, shell command and Latex formulas are not treated as restructured text the<br>
indent between these can vary.<br>
<br>
Instead of dashes one can use "=" or "_"<br>
<br>
> something as light as:<br>
><br>
> | [CODE]<br>
> | // some code example<br>
> |<br>
<br>
Yes, I really like this notation and will add it.<br>
<br>
><br>
> Would be at least as simple to parse and be much easier to compose manually.<br>
<br>
For composing documents with reStructured Text macros for your text editor of choice are really<br>
handy.  For example, here's a demo of a Vincent Driessen's VIM plugin dealing with tables<br>
<br>
<a href="http://vimeo.com/14300874" target="_blank">http://vimeo.com/14300874</a><br>
<br>
<br>
><br>
> Otherwise, it does seem like a great tool. The debate for in-source vs out-of-source documentation has been raging for a while already and though I initially appreciated in-source documentation like you I have found that there are issues; my personal peeve is the amount of screen estate "lost": when I am looking for a function, having only 3 signatures per screen because each is preceded by a large (mostly auto-generated and mind-numbing) doyxgen stub is extremely annoying.<br>

<br>
Very true.<br>
<br>
><br>
> Is this tool available somewhere ?<br>
<br>
<br>
You can get it from gitHub:<br>
<a href="https://github.com/michael-lehn/DocTool" target="_blank">https://github.com/michael-lehn/DocTool</a><br>
<br>
But please understand, so far I used this tool only for myself.  And extended it<br>
from time to time for my own needs. So it really lacks documentation of itself.<br>
And it also don't know how hard it will be to install on other platforms (I am<br>
using Mac OS X).  I just wrote this short getting started today (but it's really<br>
basic):<br>
<a href="http://www.mathematik.uni-ulm.de/%7Elehn/DocTool/" target="_blank">http://www.mathematik.uni-ulm.de/~lehn/DocTool/</a><br>
<br>
<br>
<br>
<br>
Michael<br></blockquote><div><br>Do not worry, I do understand it is a work in progress.<br><br>I already have clang working correctly on two environments (Ubuntu server at home and Suse 11 at work) so I don't think getting the tool to work on one or the other would be much of a problem. Not sure I'll have much time before October to really check it out, but it does seem really handy.<br>
<br>Thanks for the links.<br><br>-- Matthieu <br></div></div>