Re: The beauty of LATEX

On 21 October 2011 17:22, Paul A. Bristow <[email protected]> wrote:
> 2011/10/21 Mateusz Łoskot <[email protected]>:
>> 2011/10/21 Mateusz Łoskot <[email protected]>:
>> > On 21 October 2011 12:02, Paul A. Bristow <[email protected]> wrote:
>> >> If we have a C++ function in a header, and provide some 'concept'
>> >> info in Doxygen syntax inside a
>> >> C++ comment.
>> >>
>> >> /*!
>> >>       nontype template function that just returns the template value.
>> >>      \tparam size is a constant integer argument.
>> >>      \returns constant integer size always.
>> >>      \pre No preconditions.
>> >>      \post No side effects.
>> >>      \throws Never.
>> >>      \warning This is not a very useful function.
>> >>      \see More useful functions.
>> >>  */
>> >>  template <int size>
>> >>  int template_parameter_size()
>> >>  {
>> >>    return size;
>> >>  }
>> >>
>> >> Could we invent a better syntax?  I'm sceptical - it seems so simple.
>> >
>> > Doxygen is greedy (in regexp terms).
>> > To make Doxygen greedy, you need to juggle comment styles what leads to mess.
>> ---------------------------^^^^^^^^^^^
>>
>> I made mistake, it should read "not greedy", of course.
>
> So what sort of syntax would you chose instead?

I brainstormed some based on Quickbook in my previous post.
As a user of reStructuredText, Markdown and other similar syntaxes, I
find Quickbook syntax friendly and intuitive.

(I have become a fun of the idea to have Quickbook as the best C++
documentation tool ever,
so Doxygen is losing its priority for me.)

>  (Bearing in mind that it is also of considerable use to the reader of the C++ header/source, so it doesn't
> want to be too inscrutable or terse.

If the instructions neatly correspond with natural language, as I have
tried to show in my examples,
then I don't see anything wrong with instructable syntax. It makes
markup and the content
combined seamlessly.

> Or are proposing something in a separate file - when it is less useful to the C++ reader.)

I assume Quickbook could easily handle it as written in form of C++ comments
as well as in separate .qbk files.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org
_______________________________________________
Boost-docs mailing list
[email protected]
http://lists.boost.org/mailman/listinfo.cgi/boost-docs