Boost logo

Boost :

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
>


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