Vladimir Prus wrote:
On Thursday 24 March 2005 19:43, Joel de Guzman wrote:
I can see more clearly how the second model (presented by Jo�o) would
work, but I don't like adding the snippet delimiters in comments. It
cuts across the Doxygen comment processing. Remember also that the
comment syntax will be different for different source modes. That said,
James Fowler has already gone some way towards implementing inclusion
of snippets.
I agree. When Joao and I had the chat, I wasn't quite anxious
about the include snippet proposal. I didn't have a strong
case against it at the time and thought that both solutions
are orthogonal anyway. Now, it seems that you provided a
strong case against it: that 1) Qbk needs to know something about
the target language and each markup syntax will be different for
different langauges. This is unwieldy. 2) I too do not like
special tagged comments in my source code. In that sense, I am
not quite fond of Doxygen, in fact.
For me, "include source" model is superior to "source inside docs" model. The
first reason is that Emacs won't indent source inside docs propertly, and
won't even syntax highlight them properly. I'm not kidding -- this is rather
Well, that's a problem of Emacs, not QuickBook ;-)
important. And in general, modifying code embedded inside docs is rather
hard. I've tried this once and this was just horrible -- when I wanted to
change the implementation I had to find relevant snippets scattered all over
the document and modify them. And with docs and source interleaved, the
structure of the program gets lost. Some non-intrusive markup in source file,
plus inclusion mechanism, would work much better for me.
Fair enough.
OTOH, I've got my bad experience when implementing some nontrivial algorithm,
maybe for documenting library examples interleaved docs and source are not as
bad.
Alright then, I guess we have enough proponents of the include scheme.
Let's carry on with it then. I guess there's no strong reason why we
can't have both.
Cheers,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
