Joel de Guzman <[EMAIL PROTECTED]> writes: > David Abrahams wrote: >> Joel de Guzman <[EMAIL PROTECTED]> writes: >> The main objective was to get some automated testing for the code >> examples in our book. Really, that's all! ;-) > > And my point all along was that this is the domain of bjam. > Now, I realize (below) that you need a facility not only for > testing, but also for gathering the outputs back into your docs.
That would be really great, but my system hasn't been configured to to do that, so I wouldn't characterize that as a requirement. I've been writing the expected output in the document and just using litre to confirm that the actual output of the snippet, when run, corresponds to what the doc says. Gathering the output and embedding it in the document could be slightly dangerous, because there's no human in the chain to make sure the output is what we really expected. >>>and how it addresses that. Oh sure, it's a literate programming >>>system, but I do not see the connection with that and having the >>> ability to preprocess >> >> Well, we have code examples that show the Boost PP lib. We need to >> be able to test that they do what we thought. > > Ok, this is a different matter then, and well within the > borders of the documentation tool. I agree that this is a > good requirement. The spirit docs has some candidates for this. > >>>or check for specific strings in the output, >> We have examples whose correctness can only be tested well by >> verifying that they produce a particular output on stdio. Standard >> code testing stuff. Only this time, most of the code and all the >> instructions about what to do with it are embedded in the source text >> of the book. > > Shouldn't this be delegated to another tool like Boost.Test > driven by bjam? Only maybe. It depends how you're going to do it. The person writing the documentation knows how each example needs to be tested, and in what context, with what textual preprocessing, etc. If you make that person write an external tool or even write in another document to handle those jobs, the system will only be convenient to use for the most trivial jobs. So if you supply some way for them to control the generation of Jamfiles, and the launching of external programs as preprocessors, and to describe all that in the document next to the examples, then you could "delegate testing to bjam." But that sounds much more complicated than giving the user an expressive way to describe what needs to be done. -- Dave Abrahams Boost Consulting www.boost-consulting.com ------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
