On Mon, Aug 18, 2008 at 4:17 PM, John Maddock <john@johnmaddock.co.uk> wrote:
Robert Ramey wrote:
LOL - of course it does. If regression testing were setup for boost tools, they would be demonstrated to be functioning as expected before they were used in the actual release process. Had this been procedure been in place, the issue raised above would not have occurred.
This is a good point, in fact is there any reason why the doc build shouldn't be part of the regression tests?
Ah.... but it requires external tools that might not be available (especially now that accumulators has introduced a dependency on Latex and Ghostscript) :-(
I think this may be something that should be solved by policy rather than technical solutions. For instance, libraries follow a certain set of guidelines regarding how the code is organized (namespaces, macro names, type names, directory structure, directory naming, etc.). Why shouldn't there be guidelines regarding the documentation of these libraries? I know the guidelines are minimal by design (for example should be in HTML and/or PDF) but right now it's getting quite unwieldy -- and arguably, the documentation is becoming as important as the actual code is. I understand that documentation is largely an author/maintainer domain, and that currently the choice of documentation tools used is left to the author/maintainer. If we can somehow standardize on a tool set and help authors/maintainers convert their documentation from their current format to another then maybe we can make some progress regarding fixing the documentation-building/generation process and "improvement" of the library documentation. This also allows interested contributors to (more easily) learn the tools required and help out in the "improvement" of the documentation effort. Traditionally, Wiki's have worked well for other projects. Should Boost start doing this too, and just export documentation from the Wiki into properly cross-linked HTML pages in release builds? I understand Trac has the Wiki functionality already available -- should we start using it for documentation? Another option (that I think Dave Abrahams has been doing) is to use RST [0] to make writing/reading the source documentation easier than having to rely on Boostbook+XSLT (which I personally think is a brittle tool-chain). Quickbook is also a nice documentation language to use, but the reliance on Boostbook+XSLT makes it harder to pull-off. I don't know though if Quickbook can be made to generate HTML directly instead of XML. Joel? I understand there's also a Boost Documentation project. Anything happening in that front? [0] - http://docutils.sourceforge.net/rst.html -- Dean Michael C. Berris Software Engineer, Friendster, Inc.