On 23/12/10 14:42, Denis Arnaud wrote: > 2010/12/23 Mateusz Loskot <[email protected] <mailto:[email protected]>> >> I've updated installation part (see in the repo). > > I guess you are referring to > https://github.com/denisarnaud/soci/blob/master/doc/installation.html , > aren't you?
Yes, this is the new bit I've started >> I would definitely appreciate if you (or anyone) could review and >> spot missing or incorrect bits. > > Ok, I'll have a look at it (do you prefer me waiting for you to have a > version to be reviewed?) I'll let you know when it's more or less ready. In the meantime, you may take a look at TODO comment in this HTML page. I'm still not sure how to arrange it to make it clear but not bloated. >> In Boost.Geometry project, we parse Doxygen XML output with our own >> tools and I would say... I think it would be easier to write >> documentation manually in Boost Quickbook files and have >> complete control on it :-) > > I am not sure to understand why you need to do that (maybe because you > need documentation in a Boost-compatible format, i.e., Boost Quickbook > as I understand?), but you have certainly a good reason for it. Yes, Quickbook is the target format. The library is already documented using Doxygen comments, so we have to find a way how to not to loose this content. So, we wrote custom tools. > Nevertheless, having the documentation handled/generated by Boost tools > makes a lot of sense to me. As I understand, it would allow to generate > tutorials easily from (at least) some of the test cases (without to have > to right the corresponding pieces of code twice, once for the test and > another one for the tutorial/documentation). > > So, it makes a good reason for me to learn how to do that :) I'd say this way, once you know how to marry the Doxygen with your needs, like Quickbook, and have tools for that, then it's powerful. You can generate nice output, various formats, Quickbook is a very nice format, plain text, simple, lightweith, etc. The challenge is to wrap C++ specific things nicely. Likely, documenting concepts and automatically link them with models and the other way around, etc. to make full use of the idea of hypertext. I find it annoying if I have to juggle 2-3 pages. Why not to make things (parameter names, types passed as template parameters, etc.) clickable. Cheers, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org Member of ACCU, http://accu.org ------------------------------------------------------------------------------ Learn how Oracle Real Application Clusters (RAC) One Node allows customers to consolidate database storage, standardize their database environment, and, should the need arise, upgrade to a full multi-node Oracle RAC database without downtime or disruption http://p.sf.net/sfu/oracle-sfdevnl _______________________________________________ Soci-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/soci-users
