Re: [boost] CMake and Boost Build tests

Subject: Re: [boost] CMake and Boost Build tests
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2017-07-27 10:24:58

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of John Maddock via Boost
> Sent: 27 July 2017 10:10
> To: boost_at_[hidden]
> Cc: John Maddock
> Subject: Re: [boost] CMake and Boost Build tests
> 
<snip>

> >> optionally, Boost Build is used to build the documentation using a
> >> quickbook, boostbook, doxygen toolset to generate html and pdf files.
> >
> > Personally, I could never make this tool chain work despite a large
> > investment of effort.  I gave up on doxygen and quickbook after
> > concluding them to be essentially non-functional.  I did manage to use
> > the xml tools loaded with boost tools along with some downloaded FOP,
> > a version of XMLMind to create toolchain which is about 100 times
> > better and 1/100 as complex as the boost one for creating documents.
> > So you're life will be better when you're forced to leave these behind.

Works for me.
 
> I'm sorry you found them that way, Doxygen I hate 

I also don't like the *look* of its readable output.

But 

*Doxygen comment syntax for annotating classes, functions, macros etc works OK, and is the nearest thing to a Standard for
annotating code, and not just C++.*

These comments are readable in the code without cluttering and obscuring  too much.

Some examples of the *syntax*:

File information:

\brief This file is a partial reference implementation for the proposed
 "C++ binary fixed-point arithmetic" as specified in N3352.\n

\details
   There is optional support for certain variations of fixed_point
   using preprocessor definitions. Not all of these are supported
   at the moment. The potential options include:

   Is supported now  : \#define BOOST_FIXED_POINT_DISABLE_IOSTREAM\n
   Is supported now  : \#define BOOST_FIXED_POINT_DISABLE_MULTIPRECISION\n

Information above a class, here the constructor

/*!
        Constructor for a data series to plot
        \tparam T an STL container: for example: @c multimap.
        \param begin Starting iterator into container of data series begin() to start at the beginning.
        \param end Ending iterator into container of data series, end() to finish with the last item.
        \param title Title for the plot.
       */

function

  svg_2d_plot_series& svg_2d_plot_series::line_on(bool on_)
  { //! Set @c true to draw line linking data points.
    line_style_.line_on_ = on_;
    return *this; //! \return Reference to svg_2d_plot_series to make chainable.

Doxygen can now use the Clang compiler to extract all this into a form that other programs can then use to lay out in a
human-readable (or other machine readable form). (Doxygen makes a good stab at template-heavy C++, but isn't a compiler).

I believe that this is the way forward to producing documentation in the style we prefer (or in the style that others that others
prefer).

> (to be fair it's  mostly the way folks use it rather than the tool itself), 

+1

but Quickbook works extremely well for me

+ more than 1

> As for the toolchain.... I find it amusing
> that this is the one thing folks most often complain about... even
> citing it as an example of why we shouldn't invent stuff ourselves...
> when it's actually the one thing that was *not* invented here!

It works for me - most of the trouble is with bjam syntax and dealing with MS file naming.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]