Daniel James wrote On Wednesday, June 03, 2009 7:06 PM
2009/6/1 Stewart, Robert <Robert.Stewart@sig.com>:
The introduction is not a good place to document content requirements. I suggest something like the following:
[snip]
I thought that your second paragraph seemed to mainly apply to the first section of the document, so I moved it into that section, and tried to give a slightly better idea of how it relates to the next section. I also put back in the section of the standard that it's taken from as I think that's important.
https://svn.boost.org/trac/boost/changeset/53612
Does that seem sensible?
At first, I didn't think it was appropriate to move that paragraph because I intended it to be part of the introduction to frame what was to come. However, seeing the result, I agree with you, especially as it is similar to the first paragraph of the Web Reference Documentation section. I have a few wording changes to suggest to that moved paragraph: The documentation structure required for the C++ Standard is an effective way to describe the technical specifications for a library. Although terse, that format is familiar to many Boost users and is far more precise than most ad hoc formats. The following description is based upon §17.3 of the Standard. (Note that while final Standard proposals must include full standardese wording, which the committee will not do for you, that level of detail is not expected of Boost library documentation.) Note that I've eliminated your #more anchor because I think much more than the targeted section fits that description and that we shouldn't encourage the reader to skip the rest of the material. I wonder if that section number will continue to apply in the C++0x Standard, when finished. If not, I guess we'll have to clarify it with the version of the Standard. _____ Rob Stewart robert.stewart@sig.com Software Engineer, Core Software using std::disclaimer; Susquehanna International Group, LLP http://www.sig.com IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.