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

Subject: Re: [boost] [BoostBook] how to automatically test code examples?
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-10-19 18:09:52

On 10/19/2017 11:49 AM, Robert Ramey via Boost wrote:
> 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.

XML may be decent as a way of creating and passing around data in a 
structured way, but having to write documentation in XML is a hopeless 
task AFAICS. Quickbook is hugely superior and is a no-brainer to use. If 
others prefer Asciidoc that's fine also. The point is that nobody need 
write docs in XML if they do not want to and I do not think that most 
people want to. I certainly don't.

> 
>> 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