Re: [Boost-docs] Query regarding boostbook and documentation

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-01-09 18:19:03

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Robert Ramey
> Sent: 09 January 2016 16:52
> To: raffi.enficiaud_at_[hidden]; Discussion of Boost Documentation
> Subject: Re: [Boost-docs] [boost-docs] Query regarding boostbook and documentation
> On 1/9/16 6:27 AM, Raffi Enficiaud wrote:
> > I may add this:
> >
> >
> >
> > that I wrote for inciting ppl to contribute to documentation. This is
> > quickbook oriented, but it is a simple enough complete example of
> > quickbook+doxygen documentation.
> >
> > Hope this helps,
> I just took a quick look at it but it looks interesting to me.
> In the incubator is basically discourage people from using the boost tool chain as I think there
is a
> simpler more expedient approach which get's library authors on the right track faster but leaves
> with something that the could easily transition to boost tools if they get their library accepted.
> I've also discourages the usage of DOxygen because I don't believe that, as delivered, it doesn't
> support documentation of type requirements which I believe is essential.
> Having said the above, I have to concede that I've failed to gain acceptance of my ideas to the
extent I
> would have hoped. So I'm interested in the following
> a) better support/explanation for those who want/need to use boost. There is some documentation
> at but it needs to be more idiot proof. Looks like this is what your aiming at here.
> b) DOxygen is here to stay. I would like to see someone take up the challenge of making an
> which supports type requirements (aka concepts).
> From the users point of view, this would look like the following:
> 1) Show how to create concept checking classes be it via boost concept checking and/or concepts
> Users would write these as C++ header files.
> 2) Add DOxygen markup using the cited DOxygen extended markup
> 3) Follow procedures (presumably described in a) above, to integrate DOxygen output into
> documentation.
> At this point we'd have support for type requirements in both the code and documentation. This
> would improve both code and documentation and make the documentation much more likely to be
> correct and complete and also make documentation easier to write.
> One final step would be consolidate all this information (along with any existing information) in
to a
> coherent whole and place it on the website.
> Getting the website more useful for projects of this nature is another of my current holy quest.
> I've not made progress here. I just have to keep harping on the subject.

Sounds good to me.

I'll see if the Clang-assisted Doxygen now works (was flakey) and try to suggest what we need to
meet the concepts needs. I suspect that the developer Dimitri will be helpful as we can't be the
only people wanting this.


Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 (0) 1539 561830

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC