Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-21 11:02:57

> -----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?

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?

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  

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.

Could Quickbook extract this from the header files?  
And how can this by tied up with the C++ info like class, function name ...?

And finally output in the Lovely LaTex!

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]