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" <> 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" <> 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.

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

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC