-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Raffi Enficiaud Sent: 06 January 2015 01:53 To: boost@lists.boost.org 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 +44 (0) 1539 561830