Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-10-21 23:22:12

on Fri Oct 21 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:

>> -----Original Message-----
>
>> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
>> Dave Abrahams
>> Sent: Wednesday, October 19, 2011 9:00 PM
>> To: boost-docs_at_[hidden]
>> Subject: Re: [Boost-docs] The beauty of LATEX
>> 
>> on Wed Oct 19 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:
>> 
>> > But I'm still adamant that a good toolchain should allow us to build a
>> > source-linked C++ reference automatically, pulling in what has been
>> > 'handwritten' about classes, functions, macros, typdefs - the info
>> > that might be described as 'concepts' - parameters, returns, throws...
>> 
>> +1.  I support that vision, even if Doxygen fails to deliver it.
>
> OK, so how do we tackle this requirement?

Synopsis is still out there as a possibility.  Something based on Clang
is a more obvious choice.

> It seems that starting with the compiler is obvious - it really does
> understand C++ ;-) But that's a big step.  However Doxygen
> 'understands' C++ well enough - gets (reasonably) confused if the C++
> doesn't compile!
>
> Quickbook might do this as well using some of Boost's hyper parsers?
> (So hyper that it sounds like a Friday afternoon job;-)
>
> But we still need to add our 'Plain English' concepts stuff.
>
> Do we use an existing syntax like Doxygen commands or invent our own
> 'language' for the above info, and how do we link it up with the info
> the compiler knows about?

I personally hate Doxygen syntax and would prefer to use something that
is better for human consumption (e.g. http://tomdoc.org/).

However, Doxygen /is/ something many people already know and use.

> For a naïve and trivial contrived (but concrete) example with some
> imaginary info about a function template_parameter_size .
>
> 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;
>   }
>
> At present
> (stripping of any layout beauty issues) we get something
> like this out in the C++ Reference info
>

At present?  I thought you were talking about a hypothetical system(?)

> Function template template_parameter_size
>
> boost::mylibrary:: template_parameter_size
>
> Synopsis
> // In header: <boost/mylibrary/mylibrary.hpp>  (Note this is a handy hyperlink to source).
> template<int size> int template_parameter_size ();
>
> Description Nontype template function that just returns the template value.
> Template Parameters:  size  is a constant integer argument.
> Requires:  No preconditions.
> Postconditions: No side effects.
> Returns:  constant integer size always.
> Throws: Never.
> Warning This is not a very useful function.
> See Also: More useful functions.
>
> which seems pretty straightforward and tells users what they need to know.
>
> (<aside>In an amusing - beautiful even;-) - feature, the Steven has
> made the warning appear with the usual Quickbook Warning 'road'
> sign. Nice one Steven! </aside>)
>
> (And of course, we also need an *index* to get straight to this, if
> one knows the function name).
>
> (and it must work for C++ classes, members, macros, typedefs ...)
>
> Could we invent a better syntax?  I'm sceptical - it seems so simple.

See above.  But your syntax is much less offensive to me than Doxygen's.

> Could Quickbook extract this from the header files?  

I don't know enough about QB... but I think you want to extract these
things in a way that's associated with an AST, which means using a real
C++ parser.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com