Re: [boost] [BoostBook] how to automatically test code examples?

Subject: Re: [boost] [BoostBook] how to automatically test code examples?
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-19 15:49:42

On 10/19/17 8:40 AM, Hans Dembinski via Boost wrote:

> 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 don't think there's a conflict. Quickbook is just a way of producing 
boostbook.  I'm thinking that you can just include code file from 
quickbook just as you can from another boostbook editor. I don't know 
this for a fact though.  My real point is that you can let the 
documentation depend on your coded examples so that they are always in 
sync and that it is generally very easy to do.

> I believe that writing good documentation is not solvable by a tool,
+1
  although it certainly helps if the tool is easy to use and not in the 
way.
+1
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.

I see the appeal of Quickbook and other markdowns.  But all such 
attempts suffer from all attempts to make a "new" language.  It's much 
more work than it first appears.  So if it's helpful, the demands for 
maintenance and extension eventually overwhelm the original design, 
which then generates the next attempt.  It's a never ending quest.

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

> 
> Best regards,
> Hans
> 
> 
>   
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
>