Re: [Boost-users] Documentation for Boost Range

Subject: Re: [Boost-users] Documentation for Boost Range
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-05-18 05:23:31

> -----Original Message-----
> From: Boost-users [mailto:boost-users-bounces_at_[hidden]] On Behalf Of Christian Aichinger
> Sent: 17 May 2016 22:48
> To: boost-users_at_[hidden]
> Subject: Re: [Boost-users] Documentation for Boost Range
> 
> On 17.05.2016 21:08, Neil Groves wrote:
> > Missing specification of headers or return types would be defects in
> > the reference documentation. I've fixed a few. I did some spot checks
> > and found the expected information. If you have specifics that would
> > be very helpful as they should all be corrected.
> >
> > I have spent a few minutes looking through the examples and they look
> > fabulous. Adding examples can only be a good thing. I'd like to ensure
> > that the reference documentation is not deficient as one effort, and
> > to incorporate your examples as another. I have noted on the thread
> > that there was concern the work might be rejected. This is not the
> > case. So long as the work is correct we'll get it in. My preference is
> > to have a git fork that I can simply merge in.
> >
> > I already have a number of examples included in the bjam that are
> > tested with the regression tests. My examples look nowhere near as
> > beautiful. It would be ideal if I also migrated these onto the tooling
> > you have built. I'd like to have all of the output looking as
> > beautiful.
> >
> > Thank you very much for your hard work. I'll try and assist where I
> > can, but at the very least keep out of the way so that I'm not
> > becoming a problem.
> 
> Thank you very much for your kind words, Neil!
> 
> The way the documentation is built is "Examples to Markdown to HTML".
> The first step is done by a Make/Shell/Python abomination, the second
> step is done by my homepage publishing system (Pelican).
> 
> To integrate it with the Boost Range doc system, I would suggest
> changing that to "Examples -> QuickBook -> *". But that would still
> impose a Python dependency on the documentation build. Is that OK for you?
> 
> Essentially, what I'm doing here can't really be done inside Bjam or
> QuickBook alone TTBOMK, so I'm wondering what external requirements are
> OK for you (e.g. Python, common UNIX tooling such such as diff or md5sum
> to compare expected and found output).

I'm surprised that you think it can't be done with the current Boost docs and examples system,
but I haven't looked at it in detail.  

However, to the great mass of Microsofties, Python, diff and md5sum jump out as non-standard (but that doesn't necessarily rule them
out).

Paul

PS I really didn't like the colors-on-black display.  Syntax coloring is wonderful - but intensely personal.

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