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: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-01-06 05:27:00

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Raffi
Enficiaud
> Sent: 06 January 2015 01:53
> To: boost_at_[hidden]
> Subject: Re: [boost] [test] boost.test owner unresponsive to persistent
problems for
> multiple years
> 
> 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.

I'm not understanding why you can't use a separate Quickbook section called
"Advanced"
and provide the execution monitor stuff there.

What is it that is so different about this that the Quickbook structure etc
cannot provide?

The document size is irrelevant - what counts is finding what you want to know. 

The TOC is the first weapon, and the (auto-)index second, and the C++ reference
third.

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

>> > I have yet to understand if/how you are using Quickbook code...

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

There are some conditional tools in Quickbook - see the manual 

"
Conditional Generation

Like C++ #ifdef, you can generate phrases depending on the presence of a macro.
Example:
...
"

that may make this possible?  With some work and yet more complexity :-(

But IMO having the output to the right just isn't helpful anyway.  I really
don't see the benefit (and lots of non-benefits ;-).

However, you two obviously like it - so why not put the built html somewhere and
let the users comment on whether they like it?

Ship the whole built /doc  and subfolder like/html  and /doxygen section to your
Dropbox or somewhere and provide a link to it?

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

Ah - I see why you have done this now.  (Not sure I would have done but ...)

> Ok. What I see is that the \internal pieces appear in the final XML, without
any
> mention of the internal itself.

\code ...  \endcond works for me.

> I also noticed that the operator overload is not properly rendered.

Others have noted difficulties with this - and recently.  Not sure if and how it
can be fixed.

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

Daniel James is your man to ask.

Paul

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