RE: [boost] Documentation
David B. Held wrote:
Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median?
Have you looked at the BoostBook generated docs :). Let me know what you think of the current L&F: I have updated this a while ago to try and bridge the gap between the two looks (the docs now have Spirit-style navigation). See http://boost.sourceforge.net/regression-logs/cs-win32_metacomm/doc/html/inde... for the new-stle docs.
If we're going to demand uniformity in licensing, should we also demand more uniformity in documentation?
I agree on this. At the moment, we have the docs written in HTML, those in BoostBook format (like Boost.Any and the BBv2 docs) and the Spirit docs which have their own format. As far as I understand it, the BoostBook tool is relatively new and has a learning curve, so it will take some time to migrate the docs to this format. As for the Spirit docs, they have their own sourceforge area as well as being a part of Boost, so forcing them to change doc format wouldn't be fair. However, since the Spirit docs are in a special text format that is "compiled" into HTML using Spirit, it should be easy to create a BoostBook back-end and have the docs in boost in this format and the ones on the sourceforge area in the existing format. With this in mind, it might be beneficial to create a HTML to BoostBook converter (possibly using Spirit) to allow easier migration to the BoostBook format.
I think a single documentation style across Boost would make it even easier to learn new libraries. I recently found it very difficult to find the information I wanted about the Boost.Test library, as well as Boost.Preprocessor. What can be done about these issues?
I think the BoostBook format would go a long way to resolving these issues, once the docs are all in this uniform format. Regards, Reece _________________________________________________________________ Express yourself with cool new emoticons http://www.msn.co.uk/specials/myemo
"Reece Dunn" <msclrhd@hotmail.com> writes:
David B. Held wrote:
Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median?
Have you looked at the BoostBook generated docs :). Let me know what you think of the current L&F: I have updated this a while ago to try and bridge the gap between the two looks (the docs now have Spirit-style navigation). See http://boost.sourceforge.net/regression-logs/cs-win32_metacomm/doc/html/inde... for the new-stle docs.
FWIW, I'm not entirely opposed to frames (as long doc pages have a "link to this page" somewhere. I really like the general format that Aleksey is generating for the next revision of the MPL docs, which use frames.
If we're going to demand uniformity in licensing, should we also demand more uniformity in documentation?
I agree on this. At the moment, we have the docs written in HTML, those in BoostBook format (like Boost.Any and the BBv2 docs) and the Spirit docs which have their own format.
And others; we used ReST for the iterator library.
As far as I understand it, the BoostBook tool is relatively new and has a learning curve, so it will take some time to migrate the docs to this format.
And it requires writing in XML :-( or translating to it :-|.
As for the Spirit docs, they have their own sourceforge area as well as being a part of Boost, so forcing them to change doc format wouldn't be fair.
Spirit doesn't have reference docs, though. It only has a long tutorial. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:un03a19v3.fsf@boost-consulting.com...
[...] FWIW, I'm not entirely opposed to frames (as long doc pages have a "link to this page" somewhere. I really like the general format that Aleksey is generating for the next revision of the MPL docs, which use frames.
Can we see that somewhere?
[...] Spirit doesn't have reference docs, though. It only has a long tutorial.
So perhaps we need to insist that libraries have both a tutorial section and a reference section? Dave --- Outgoing mail is certified Virus Free. Checked by AVG anti-virus system (http://www.grisoft.com). Version: 6.0.701 / Virus Database: 458 - Release Date: 6/7/2004
"David B. Held" <dheld@codelogicconsulting.com> writes:
So perhaps we need to insist that libraries have both a tutorial section and a reference section?
I think that's a good idea. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David B. Held wrote:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:un03a19v3.fsf@boost-consulting.com...
Spirit doesn't have reference docs, though. It only has a long tutorial.
So perhaps we need to insist that libraries have both a tutorial section and a reference section?
The next major Spirit release will definitely have a "User's Guide" and "Reference" with tons of cross links between the two in the form of linked annotations. I really like the ARM. I learned C++ from that book more than in anything else. It's my model of how a reference should be written. And yes, Spirit does not have a reference yet. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On Fri, 11 Jun 2004 12:35:41 +0100 "Reece Dunn" <msclrhd@hotmail.com> wrote:
David B. Held wrote:
Ok, if the Boost style documentation is too simple, and docs like Spirit are too cute, what is a nice, happy median?
Have you looked at the BoostBook generated docs :). Let me know what you think of the current L&F: I have updated this a while ago to try and bridge the gap between the two looks (the docs now have Spirit-style navigation). See http://boost.sourceforge.net/regression-logs/cs-win32_metacomm/doc/html/inde...
for the new-stle docs.
I may be one of the last remaining tree-killers, but I really wish there was an easy way to print out the documentation. I find hard copy documents much easier to use during the initial learning phase and online reference easier afterward. I have yet to find any boost documentation that is easy to print.
On Sun, 13 Jun 2004 20:12:26 -0400, Jody Hagins wrote
I may be one of the last remaining tree-killers, but I really wish there was an easy way to print out the documentation.
Documentation in boost-book can be translated to pdf and then printed. Of course, if you just print everything, you are going to kill alot of trees. We have been doing some work to convert date-time to boost book and the pdf docs (including the full generated reference section) weighs in at ~250 pages. Nonetheless, I believe it would be highly valueable to be able to print boost docs. Jeff
participants (2)
-
David Abrahams -
David B. Held -
Jeff Garland -
Jody Hagins -
Joel de Guzman -
Reece Dunn