[serialization] installed documentation bug and suggestions.

Bugs: I've had bad internet connection so I had to resort to using the installed boost docs and noticed some bugs. 1) /share/doc/boost/libs/serialization/doc/index.html has broken links in the left frame. 2) /share/doc/boost/libs/serialization/doc/archive_reference.html has broken links in the following paragraph: //Start As a convenience, small header files have been included which contain typedef for polymorphic implementation for each corresponding templated one. For example, the headers polymorphic_text_iarchive.hpp and polymorphic_text_oarchive.hpp. contain the typedef for the polymorphic implementation of the standard text archive classes text_iarchive.hpp and text_oarchive.hpp respectively. All included polymorphic archives use the same naming scheme. //End Suggestion: 1) It's not readily apparent that there's a polymorphic implementation of the serialization classes, may be this should be mentioned in the tutorial? 2) Or have a section in the Overview page categorizing the available categories of serializors as intrusive, non-intrusive, polymorphic, giving a short definition of each type, and their pros/cons. Basically what is missing is an eye-ball summary of the available serializors that this library offers, and why one would choose one over the other and vice versa. The information is there, but it is scattered and it took some digging to get to it. For example, from the overview page one cannot deduce that there exists an intrusive, or polymorphic version. It is only from Tutorials page can one immediately deduce that there is an intrusive version, and to figure out there is a polymorphic version one has to navigate the following path: Reference link in left frame -> Archive Class Reference. Also, best practices/potential pitfalls like the following suggestion: //Start // /share/doc/boost/libs/serialization/doc/tutorial.html#nonintrusiveversion Note the serialization of the base classes from the derived class. Do NOT directly call the base class serialize functions. Doing so might seem to work but will bypass the code that tracks instances written to storage to eliminate redundancies. It will also bypass the writing of class version information into the archive. For this reason, it is advisable to always make member serialize functions private. //End should be made more eye grabbing. It's very easy to accidentally skip over such information. Thanks, - Mostafa

AMDG Mostafa wrote:
I've had bad internet connection so I had to resort to using the installed boost docs and noticed some bugs.
1) /share/doc/boost/libs/serialization/doc/index.html has broken links in the left frame.
Which links specifically?
2) /share/doc/boost/libs/serialization/doc/archive_reference.html has broken links in the following paragraph:
This is a packaging problem. The links are correct in the Boost distribution. In Christ, Steven Watanabe

I should have been more clear. This is for boost version 1.42
Mostafa wrote:
I've had bad internet connection so I had to resort to using the installed boost docs and noticed some bugs.
1) /share/doc/boost/libs/serialization/doc/index.html has broken links in the left frame.
Which links specifically?
Case Studies Other Classes By broken, I mean that they're not identified as links in the browser. I guess that's because they're missing the anchor tag. Now that I have internet connection back, I see that on the website they're expandable tree nodes, not links. That's not how they're rendered offline, that is the whole left pane is not renedered as a tree structure, it's rendered flat with the descendant nodes missing, is that expected? BTW, the browser I'm using is: Firefox 3.5.7 -Mostafa

Mostafa wrote:
I should have been more clear. This is for boost version 1.42
Mostafa wrote:
I've had bad internet connection so I had to resort to using the installed boost docs and noticed some bugs.
1) /share/doc/boost/libs/serialization/doc/index.html has broken links in the left frame.
Which links specifically?
Case Studies Other Classes
By broken, I mean that they're not identified as links in the browser. I guess that's because they're missing the anchor tag. Now that I have internet connection back, I see that on the website they're expandable tree nodes, not links. That's not how they're rendered offline, that is the whole left pane is not renedered as a tree structure, it's rendered flat with the descendant nodes missing, is that expected? BTW, the browser I'm using is: Firefox 3.5.7
Hmmm - I'm not seeing this on my local version. BTW - I've recently checked in improvements in the documentation. They don't touch on the points you mention, but they do include more correct information and also two more case studies. This has been a work in progress for 8 years. Robert Ramey
-Mostafa

On Sat, 13 Mar 2010 21:47:31 -0800, Robert Ramey
Mostafa wrote:
I should have been more clear. This is for boost version 1.42
Mostafa wrote:
I've had bad internet connection so I had to resort to using the installed boost docs and noticed some bugs.
1) /share/doc/boost/libs/serialization/doc/index.html has broken links in the left frame.
Which links specifically?
Case Studies Other Classes
By broken, I mean that they're not identified as links in the browser. I guess that's because they're missing the anchor tag. Now that I have internet connection back, I see that on the website they're expandable tree nodes, not links. That's not how they're rendered offline, that is the whole left pane is not renedered as a tree structure, it's rendered flat with the descendant nodes missing, is that expected? BTW, the browser I'm using is: Firefox 3.5.7
Hmmm - I'm not seeing this on my local version.
BTW - I've recently checked in improvements in the documentation. They don't touch on the points you mention, but they do include more correct information and also two more case studies. This has been a work in progress for 8 years.
Robert Ramey
It must be a packaging issue also. I just checked the downloaded boost source and it doesn't have this issue. Sorry for the false alarm.
participants (3)
-
Mostafa
-
Robert Ramey
-
Steven Watanabe