On Mon, Aug 18, 2008 at 10:49 PM, Beman Dawes <bdawes@acm.org> wrote:
Daniel James wrote:
2008/8/18 Dean Michael Berris <mikhailberis@gmail.com>:
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).
We haven't a single problem with boostbook or xslt. It's actually quite stable. The problems have been with boost build, quickbook (possibly due to Spirit), doxygen and latex. Basically everything but boostbook. Most of the problems seem to involve poor support for windows.
And even on Windows the doc build process has been mostly trouble-free. The only reason the doc build was such an upset 1.36.0 was that a breakage was detected very late in the release process. So I really don't think we should be talking about major changes. It should be sufficient (1) quickly fixing the current bug (which the docs folks are already working on), and (2) tweaking the process to make sure doc build failures are detected much earlier in a release cycle.
Just a thought: If building docs in windows for the release is a pain (like most of the time I try it with the Boost.Build+Boostbook+XSLT toolchain), shouldn't we just generate the documentation in Linux and offer that as a separate download (or packaged with every new release)? And would it hurt to have a documentation-only, source/header-only, and combined package available from sourceforge?
The "big bang" major change we need is to get CMake based building, testing, and reporting working well enough to use in production work. IIUC, that project is making lots of progress with building and testing, but hasn't really gotten into reporting yet. So rather than spend a lot of energy in a long discussion here, it would be better IMO if the Boost brainpower dusted off their SQL skills, and started working on report generation and query for the CMake based testing system. Meanwhile those of us working on release management will keep churning out quarterly releases!
The discussion I was actually looking for is more on policy (but apparently the technology part of my post got more attention) regarding library documentation. The technology is the easy part to address -- we can always get better tools -- but one recurring theme in discussions about documentation problems (in generating the docs) is the lack of consistency/coherence/singularity with regards to not only the look/feel of the documentation, but also with the presentation both aesthetically (admonitions, images, indentation, etc.) and structurally (w/ or w/o quickstart, reference documentation format, etc.). Right now each library has its own structure as far as documentation goes -- and people can use whatever tools they want/need (like LaTeX recently) to generate them. We can standardize on the tools fine, but I guess the bigger question really is having guidelines (or templates, if it's more appropriate) as to what each document contains, how certain presentations have to be made (like mention the header in which a function/class/template can be found, etc.), and what the structure of every library documentation package should look like (Introduction, Tutorial, Reference, Rationale, Design, etc.). So one part of me says I agree with you Beman about getting to the work that actually needs to be done regarding testing and reporting, while another part of me says I'd like to be part of a solution to make library documentation more coherent and more consistent across the board. Part of that other conversation I'm looking forward to is what tools we may have to standardize on to actually pull it off, but if people feel that's a conversation that should happen later than sooner (if ever) then that's fine by me. :) Thanks for the attention, and I look forward to your thoughts. :) -- Dean Michael C. Berris Software Engineer, Friendster, Inc.