Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years

Subject: Re: [boost] [test] boost.test owner unresponsive to persistent problems for multiple years
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2015-01-05 20:53:26

Paul A. Bristow <pbristow <at> hetp.u-net.com> writes:

> First, I can confirm that I can build the Quickbook docs and the standalone
> Doxygen docs.
> 
> Second, I think you have done a *great job* here - looks nice and I could find
> my way around easily.
> 
> Third This should definitely go into master ready for the next release.  Even
> with some wrinkles noted above, it will help users a great deal.

Thanks! We are defining the scope of the next release, we definitely want
some "must have"
features to be properly documented. 

> 
> Fourth  The Standalone Doxygen shows the structure and how it works
internally.
> It makes the code maintainable at last, but should not be necessary for the
> users.  So just providing the doxyfile in the /doc folder seems fine to me.
> Anyone wanting to do maintenance (or ferret in the innards) can build it
easily
> using the Doxywizard.  (For Windows users, I favour renaming it to a unique
> name and file type, say test_doxyfile.txt). This makes up for any
limitations in
> the Quickbook C++ Reference section.
> 

You have a point. Our current concern is that the documentation is huge and
it is hard to find a good way of presenting all the features in boost.test.
Parts such as execution monitor are very advanced, and have enough content
to have their own section. This thing is that, from a user perspective, it
is hard to understand what such parts have to do with boost.test. So we
think it is better to have a separate document for these parts.

One option is to have these parts documented in doxygen only, with \sections
and everything doxygen is able to provide. The other option is to have
several quickbook documents (users guide, users reference, advanced topics,
full reference), but I do not know if it would address the issue. 

> My only immediate criticism is that I think placing the Output in a second box
> to the right of the Code makes assumptions about page width that are probably
> unjustified, especially on tablets and phones (which are often used as a
second
> screen to display manuals etc).
> 
> The output box is certain to overflow many screens and will definitely
mess up a
> PDF version making it useless. I can see that it makes sure that the output is
> close to the source, but vertical space is unlimited, whereas width is
precious.

We use a template, and those changes are straightforward. I was wondering
if, with quickbook, it would be
possible to have:
- either an output that is "folded" by default and "unfolded" dynamically
when the user clicks it
- or an output created on another page, without creating a section under the
current one
- and finally if all these can be easily disabled for the PDF output

Finally, for the arrangement of the table columns, would some "fluid
container" provided by bootstrap address this issue?

> 
> I have yet to understand if/how you are using Quickbook code snippets -
all the
> examples seem to have the same name "example_code" ? 
> And this example at least doesn't use a code snippet.
> 
> [...]

We use code snippet almost everywhere. The example you mention has also its
.cpp and has been checked, although not in an automated manner.
We reproduced the code in this very example because we wanted the macros
expansion. 
All snippets have the same markup "example_code" (looks like a trick to
quickbook) and allows us to use the same template for all snippets/examples.
This is also the case for the outputs. 
I was not able to disable the default rendering for the output also (using
[teletype] instead). 

> 
> Code snippets are valuable because the ensure that the code in the docs is the
> code in the example and actually runs.  Similarly the output can make ensuring
> this much easier.
> 
> As to the problems above, I have yet to find time to study in detail, but
> getting free of warnings may not be practical (at least until Doxygen is
> modified to use the Clang compiler, when it will *really* understand C++
code).
> Its current parsing is impressive considering the labyrinthineness of C++
> language, but imperfect. 
> 
> One thing I am fairly sure is that the  <at> internal command was not
found to work
> right by Steven Watanabe (our expert on Quickbook internals whose has
fixed some
> previous bugs, but currently busy on other things).  I have, at his
suggestion,
> used the \cond ... \endcond command instead to remove implementation details
> from Doxygen's sight.  So this is method to use for this (and using a name
> \cond DETAILS  ... ) allows the maintainer to show everything, including
things
> brackets by DETAILS, or not).

Ok. What I see is that the \internal pieces appear in the final XML, without
any mention of the internal itself.
I also noticed that the operator overload is not properly rendered.

> Some of the bug reports suggest that  <at>  as a trip character may
produce different
> (wrong?) results compared to backslash \ as trip.  This may be 'cured' now.
> I've built with the hot-off-the-press bug-fix release 1.8.9.1.
> 
> I'll see if I can deal with any of the other wrinkles above later.
> 
> HTH
> 
> Paul

Thanks for your support. 

One last question: I just noticed the existence of the develop doc website
http://www.boost.org/doc/libs/develop/libs/libraries.htm

How often is it updated?

Best,
Raffi