Boost logo

Boost :

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

Boost list run by bdawes at, gregod at, cpdaniel at, john at