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:
> >
> > https://github.com/boostorg/test/tree/master/doc
> >
> > 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
them
> 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 Boost.org 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
extension
> 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
lite.
> 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

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