Re: [boost] [circular_buffer] New version of documentation
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Marshall Clow Sent: Thursday, May 23, 2013 8:01 PM To: boost@lists.boost.org Subject: Re: [boost] [circular_buffer] Volunteer(s) needed
After more work than I bargained for (see below for excuses) I have produced a Quickbook, Doxygen, Autoindex version from the existing documentation for Boost.Circular_Buffer at https://svn.boost.org/svn/boost/trunk/libs/circular_buffer/doc/circular_buff... I have made few substantive changes to the text, mainly adding more hyperlinks, (and correcting some that were wrong of missing - using the inspect tool is a really, really good idea!) So that users can comment on this new version, I have put html and pdf versions in my Dropbox. The pdf version is at https://dl.dropboxusercontent.com/u/43940943/circular_buffer.pdf which can of course be viewed by any PDF reader (I have recently moved to using Foxit instead of Adobe Reader). The html Quickbook version is from folder (libs/circular_buffer/doc/html) the at https://dl.dropboxusercontent.com/u/43940943/html/index.html (Sadly some of the icon .png files are inaccessible from the Dropbox version, which mars its beauty but you'll get the idea). This library uses the full automatic indexing of C++ names and hyperlinking to and from the text. The header files have the classes and functions fully documented in Doxygen format, and this is used to create the C++ reference sections: https://dl.dropboxusercontent.com/u/43940943/html/boost_circular_buffer_c___... to that you can see what the classes do and the parameters, template parameters, returns etc for the functions. I believe that these details are essential for Really Useful documentation. The original Doxygen standalone (whose format some users prefer) is at https://dl.dropboxusercontent.com/u/43940943/doxygen/html/index.html So you can see the pros and cons of the same information displayed side by side. The PDF and HTML versions also has an index at the end (this could be improved as it only gives C++ functions etc at present). Enjoy! (?) Comments welcome - praise preferred ;-) Paul PS Implementation notes: To get all the links correct proved *very* tiresome. Much of the trouble was inconsistent layout of existing documentation and files. IMO we need to use the GITMOD project to impose much more order on the file structure. I fear that the modularization changes will invalidate many links in documentation, so much revision will be needed :-( We must be able to predict where index.html etc will be to be able to write links without the current hassle. The Boost inspect tool proved invaluable, and all links are now reported correct. (Lots were wrong - in Doxygen comments in the header files, and in the Quickbook stuff :-( ) Despite this, there are still some sections in red where the html layout is wrong :-( I hope to find all of these in a later revision. --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
AMDG On 05/29/2013 09:11 AM, Paul A. Bristow wrote:
We must be able to predict where index.html etc will be to be able to write links without the current hassle.
I thought the canonical location is libs/libraryname/index.html? This should be a redirect to wherever the documentation actually lives. In Christ, Steven Watanabe
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Steven Watanabe Sent: Wednesday, May 29, 2013 6:58 PM To: boost@lists.boost.org Subject: Re: [boost] [circular_buffer] New version of documentation
AMDG
On 05/29/2013 09:11 AM, Paul A. Bristow wrote:
We must be able to predict where index.html etc will be to be able to write links without the current hassle.
I thought the canonical location is libs/libraryname/index.html? This should be a redirect to wherever the documentation actually lives.
It should be - and usually is - but some in utility etc are not, and also I have links to source and headers and the now-standard layout isn't always used. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Paul A. Bristow Sent: Wednesday, May 29, 2013 5:11 PM To: boost@lists.boost.org Subject: Re: [boost] [circular_buffer] New version of documentation
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Marshall Clow Sent: Thursday, May 23, 2013 8:01 PM To: boost@lists.boost.org Subject: Re: [boost] [circular_buffer] Volunteer(s) needed
I have updated my new Quickbook, Doxygen, Autoindex version from the existing documentation for Boost.Circular_Buffer at
https://svn.boost.org/svn/boost/trunk/libs/circular_buffer/doc/circular_buff...
I have made few substantive changes to the text, mainly adding more hyperlinks, (and correcting some that were wrong of missing - using the inspect tool is a really, really good idea!)
So that users can comment on this new version, I have put html and pdf versions in my Dropbox.
I have now corrected some mistakes.
The latest pdf version is at
https://dl.dropboxusercontent.com/u/43940943/doc/circular_buffer.pdf
which can of course be viewed by any PDF reader
(I have recently moved to using Foxit instead of Adobe Reader).
The html Quickbook version is from folder (libs/circular_buffer/doc/html) is at
https://dl.dropboxusercontent.com/u/43940943/doc/html/index.html
This library uses the full automatic indexing of C++ names and hyperlinking to and from the text.
The header files have the classes and functions fully documented in Doxygen format, and this is used to create the C++ reference sections:
so that you can see what the classes do and the parameters, template parameters, returns etc for
https://dl.dropboxusercontent.com/u/43940943/doc/html/boost_circular_buffer_... the
functions. I believe that these details are essential for Really Useful documentation.
The original Doxygen standalone (whose format some users prefer) is at
So you can see the pros and cons of the same information displayed side by side in different
https://dl.dropboxusercontent.com/u/43940943/doc/doxygen/html/index.html formats.
The PDF and HTML versions also has an index at the end (this could be improved as it only gives C++ functions etc at present).
Unless someone squeaks, I proposed to commit the existing docs with this new version in a week or so. At this time, I will need to update the header files which have new comments (but, unless my fat finger strike again, no changes to the actual code). The tests run OK with these files locally. I will leave the existing docs in place, but change the doc/index.html to redirect to the new version. This will mean that the new version will become 'standard' for the next release. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
participants (2)
-
Paul A. Bristow -
Steven Watanabe