Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Mateusz Łoskot (mateusz_at_[hidden])
Date: 2011-10-21 16:53:36

On 21 October 2011 17:22, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> 2011/10/21 Mateusz Łoskot <mateusz_at_[hidden]>:
>> 2011/10/21 Mateusz Łoskot <mateusz_at_[hidden]>:
>> > On 21 October 2011 12:02, Paul A. Bristow <pbristow_at_[hidden]> 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