Boost logo

Boost :

Subject: Re: [boost] [BoostBook] how to automatically test code examples?
From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2017-10-19 15:40:33


Dear Robert,

> On 19. Oct 2017, at 16:24, Robert Ramey via Boost <boost_at_[hidden]> wrote:
>
> I make up my examples in the "example" directory. This includes a Jamfile to build and run the examples.
>
> I create the BoostBook xml using and XMLmind - an xml editor. Within that environment I just use an "Include" directive to include the source code of the example in the correct place - easy as pie. If you download the slides associated with my recent CPPCon presentation, you can see how it's done.
>
> https://www.youtube.com/watch?v=YxmdCxX9dMk <https://www.youtube.com/watch?v=YxmdCxX9dMk>
>
> you can download the slides and example here:
>
> http://www.rrsd.com <http://www.rrsd.com/>

thank you for these pointers. :) Sorry again, I mixed up BoostBook with Quickbook. Since I already wrote 90 % of the documentation in QuickBook, so I am going to stick to that for now.

I watched your talk on Youtube a few days ago and I think it was a nice talk. I think we need more talks about code documentation.

I believe that writing good documentation is not solvable by a tool, although it certainly helps if the tool is easy to use and not in the way. So far, I liked the Markdown variants best of all markup languages. Since Asciidoc is similar, I am glad that it was discussed on the list recently.

For me the conclusion is this: the recipe for good documentation is just like the recipe for good code. It requires reviews and iteration.

Best regards,
Hans

 


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk