Missing Documentation on Building and Installing Documentation.
I'm currently working with boost 1.46 which I downloaded from the main boost site and installed a few weeks ago, without a hitch. Just now I went to check in /usr/local/share/doc for the boost documentation, and discovered it wasn't installed when I asked bjam to install. So, how do I ask bjam to make the documentation, and to install it? I would like to have a local copy as I'm not always going to have internet access when working. -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
AMDG On 03/17/2011 01:15 PM, Stirling Westrup wrote:
I'm currently working with boost 1.46 which I downloaded from the main boost site and installed a few weeks ago, without a hitch. Just now I went to check in /usr/local/share/doc for the boost documentation, and discovered it wasn't installed when I asked bjam to install.
So, how do I ask bjam to make the documentation, and to install it? I would like to have a local copy as I'm not always going to have internet access when working.
The documentation should be pre-built. You can access it at libs/libraries.htm or libs/<library name>/index.html. Unfortunately, there's no way to install the documentation. It's set up to live in the source tree and moving would break a lot of links. In Christ, Steven Watanabe
On Thu, Mar 17, 2011 at 4:30 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
On 03/17/2011 01:15 PM, Stirling Westrup wrote:
I'm currently working with boost 1.46 which I downloaded from the main boost site and installed a few weeks ago, without a hitch. Just now I went to check in /usr/local/share/doc for the boost documentation, and discovered it wasn't installed when I asked bjam to install.
So, how do I ask bjam to make the documentation, and to install it? I would like to have a local copy as I'm not always going to have internet access when working.
The documentation should be pre-built. You can access it at libs/libraries.htm or libs/<library name>/index.html. Unfortunately, there's no way to install the documentation. It's set up to live in the source tree and moving would break a lot of links.
It should not be that impossible as several distributions, such as Debian, place the documentation in /usr/share/doc and the links all work. Besides, isn't the documentation generated by docbook or doxygen or some similar system? If it is, it should be simple enough to generate it for any desired target location. -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
Stirling Westrup wrote:
On Thu, Mar 17, 2011 at 4:30 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
The documentation should be pre-built. You can access it at libs/libraries.htm or libs/<library name>/index.html. Unfortunately, there's no way to install the documentation. It's set up to live in the source tree and moving would break a lot of links.
It should not be that impossible as several distributions, such as Debian, place the documentation in /usr/share/doc and the links all work. Besides, isn't the documentation generated by docbook or doxygen or some similar system? If it is, it should be simple enough to generate it for any desired target location.
Distributions like Debian's have been manually modified to suit the needs of the distributor. They might also have changed other aspects of the directory tree. Such adaptations are not provided by the Boost developers. Besides, not all documentation is generated with BoostBook. Also I think it shouldn't have to, because in some cases such documentation systems can be too rigid. -Julian
On Fri, Mar 18, 2011 at 5:41 AM, Julian Gonggrijp <j.gonggrijp@gmail.com> wrote:
Stirling Westrup wrote:
On Thu, Mar 17, 2011 at 4:30 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
The documentation should be pre-built. You can access it at libs/libraries.htm or libs/<library name>/index.html. Unfortunately, there's no way to install the documentation. It's set up to live in the source tree and moving would break a lot of links.
It should not be that impossible as several distributions, such as Debian, place the documentation in /usr/share/doc and the links all work. Besides, isn't the documentation generated by docbook or doxygen or some similar system? If it is, it should be simple enough to generate it for any desired target location.
Distributions like Debian's have been manually modified to suit the needs of the distributor. They might also have changed other aspects of the directory tree. Such adaptations are not provided by the Boost developers.
My point was that if Debian is doing it then there is obviously a viable method, and one could simply decide to adopt it. Proper documentations SHOULD be provided by Boost. Simply saying that it resides in the build tree is no more acceptable than telling folks that the headers all reside in the build tree and need to be manually modified to be installed.
Besides, not all documentation is generated with BoostBook. Also I think it shouldn't have to, because in some cases such documentation systems can be too rigid.
If the documentation cannot be automatically installed in a standard documentation repository, then the current documentation system is too rigid and needs to be fixed. -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
AMDG On 03/18/2011 08:10 AM, Stirling Westrup wrote:
On Fri, Mar 18, 2011 at 5:41 AM, Julian Gonggrijp<j.gonggrijp@gmail.com> wrote:
Besides, not all documentation is generated with BoostBook. Also I think it shouldn't have to, because in some cases such documentation systems can be too rigid. If the documentation cannot be automatically installed in a standard documentation repository, then the current documentation system is too rigid and needs to be fixed.
There is no "documentation system." The actual rule is simple. A library must provide HTML documentation. What makes it difficult to relocate is that the documentation has links to headers and source files. By the time you copy everything referenced by the documentation, you might as well just copy the whole tree. In Christ, Steven Watanabe
On Fri, Mar 18, 2011 at 11:43 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
On 03/18/2011 08:10 AM, Stirling Westrup wrote:
On Fri, Mar 18, 2011 at 5:41 AM, Julian Gonggrijp<j.gonggrijp@gmail.com> wrote:
Besides, not all documentation is generated with BoostBook. Also I think it shouldn't have to, because in some cases such documentation systems can be too rigid.
If the documentation cannot be automatically installed in a standard documentation repository, then the current documentation system is too rigid and needs to be fixed.
There is no "documentation system." The actual rule is simple. A library must provide HTML documentation. What makes it difficult to relocate is that the documentation has links to headers and source files. By the time you copy everything referenced by the documentation, you might as well just copy the whole tree.
You may wish to revise your procedures on this then. Boost has a reputation of rigorously testing its libraries. One might reasonably assume this extended to the documentation. After all, without correct documentation, most of these libraries are not very useful. So far, my most common problem with using Boost libraries has been documentation that is unclear, outdated, incomplete and/or simply wrong. Its hard to be a world class library when you fail in the documentation. -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
Stirling Westrup wrote:
On Fri, Mar 18, 2011 at 11:43 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
On 03/18/2011 08:10 AM, Stirling Westrup wrote:
If the documentation cannot be automatically installed in a standard documentation repository, then the current documentation system is too rigid and needs to be fixed.
There is no "documentation system." The actual rule is simple. A library must provide HTML documentation. What makes it difficult to relocate is that the documentation has links to headers and source files. By the time you copy everything referenced by the documentation, you might as well just copy the whole tree.
You may wish to revise your procedures on this then. Boost has a reputation of rigorously testing its libraries. One might reasonably assume this extended to the documentation. After all, without correct documentation, most of these libraries are not very useful.
So far, my most common problem with using Boost libraries has been documentation that is unclear, outdated, incomplete and/or simply wrong. Its hard to be a world class library when you fail in the documentation.
You are confusing two issues that are completely orthogonal to each other. 1) The way the Boost documentation is structured. It's simple: the C++ code is part of the documentation. Hence, installing the documentation == extracting the Boost distribution tree. There is nothing wrong with this approach; it reduces "documentation duplication" which, exactly like reducing code duplication, is a good thing. 2) The quality of the part of the documentation that is not C++ code. Of course there may be errors in the documentation. In that case you're free to file a bug, just like with the C++ code. To conclude, changing the approach in 1) would not solve the issues in 2). -Julian
On Sun, Mar 20, 2011 at 5:44 PM, Julian Gonggrijp <j.gonggrijp@gmail.com> wrote:
You are confusing two issues that are completely orthogonal to each other.
The point I was trying to make is that documentation seems to be a neglected side of the boost project, BOTH in quality and structure. There are formal reviews of new libraries. Is the documentation subject to the same reviews? If so, I can only say the reviewers have been falling down on the job.
1) The way the Boost documentation is structured.
It's simple: the C++ code is part of the documentation. Hence, installing the documentation == extracting the Boost distribution tree. There is nothing wrong with this approach; it reduces "documentation duplication" which, exactly like reducing code duplication, is a good thing.
What exactly does "installing the documenation == extracting the Boost distribution tree" mean? Does installing the header files == extracting the Boost distribution tree? Does installing built libraries in all their various (threading/non-threading, shared/static) forms == extracting the Boost distribution tree"? If I download a tar ball, extract and build according to the rules given, install everything and then delete the tarball and its associated temporary files, I have my headers, I have my libraries, but I DO NOT have any documentation. Since this is the standard way of installing things on Linux and since the installation documentation gives nothing to dissuade someone from this methodology, it appears (to me) to be a major problem.
2) The quality of the part of the documentation that is not C++ code.
Of course there may be errors in the documentation. In that case you're free to file a bug, just like with the C++ code.
Oh sure, but I've come across programming bugs in Boost once or twice, ever. I come across documentation bugs on the order of 3 or 4 times every day. If someone were to judge the quality of Boost based on its documentation quality, they would get a very incorrect view.
To conclude, changing the approach in 1) would not solve the issues in 2).
Changing the Boost procedures stop treating documentation as an afterthought would fix both problems. -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
On 3/21/2011 3:44 PM, Stirling Westrup wrote:
On Sun, Mar 20, 2011 at 5:44 PM, Julian Gonggrijp<j.gonggrijp@gmail.com> wrote:
You are confusing two issues that are completely orthogonal to each other.
The point I was trying to make is that documentation seems to be a neglected side of the boost project, BOTH in quality and structure.
Given the body of library documentation I've seen, I'd have to disagree. The Boost documentation is overwhelmingly better than most others.
There are formal reviews of new libraries. Is the documentation subject to the same reviews? If so, I can only say the reviewers have been falling down on the job.
Yes, they are reviewed as part of the library acceptance review. But as you must know documentation is hard to ever get right. And even harder to make it right and good. So we expect documentation to meet a minimal set of usability requirements. But like all things programming, we don't expect perfection. There will always be bugs in code and documentation.
1) The way the Boost documentation is structured.
It's simple: the C++ code is part of the documentation. Hence, installing the documentation == extracting the Boost distribution tree. There is nothing wrong with this approach; it reduces "documentation duplication" which, exactly like reducing code duplication, is a good thing.
What exactly does "installing the documenation == extracting the Boost distribution tree" mean?
It means, that if you want to read the documentation locally you untar the package locally and keep it around.
Does installing the header files == extracting the Boost distribution tree?
For some people it does. But less so on Unix variants, than say Windows. Some people, like myself who wrote the initial install scripts, never actually use the install procedure. I.e. I just use the sources directly and likely never build the usual set of installed libraries. Opting to "embed" the libraries within the project that happens to be using them.
Does installing built libraries in all their various (threading/non-threading, shared/static) forms == extracting the Boost distribution tree"?
No. But sometimes building them, and using them *without* installing them is done. People are fond of building and checking them into their VCS system for their team to use directly.
If I download a tar ball, extract and build according to the rules given, install everything and then delete the tarball and its associated temporary files, I have my headers, I have my libraries, but I DO NOT have any documentation. Since this is the standard way of installing things on Linux and since the installation documentation gives nothing to dissuade someone from this methodology, it appears (to me) to be a major problem.
It's also common for packages with large amounts of documentation to never install documentation locally. Instead opting to provide separate platform independent downloads. Many times in form of PDF or HTML books.
2) The quality of the part of the documentation that is not C++ code.
Of course there may be errors in the documentation. In that case you're free to file a bug, just like with the C++ code.
Oh sure, but I've come across programming bugs in Boost once or twice, ever. I come across documentation bugs on the order of 3 or 4 times every day. If someone were to judge the quality of Boost based on its documentation quality, they would get a very incorrect view.
Of course.. But if others don't point out the documentation bugs how can one expect them to get fixed promptly. You must be familiar with the problem of authors correcting their own writing. And hence why there are book editors, reviewers, and errata.
To conclude, changing the approach in 1) would not solve the issues in 2).
Changing the Boost procedures stop treating documentation as an afterthought would fix both problems.
Very unlikely. Note, I'm not discouraging improving the handling of documentation. Just trying to put some pragmatic reality into the picture ;-) And having a way to "install" documentation might be good. But given the varied documentation content it's not as easy as one might think. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org (msn) - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail
On Mon, Mar 21, 2011 at 5:22 PM, Rene Rivera <grafikrobot@gmail.com> wrote:
On 3/21/2011 3:44 PM, Stirling Westrup wrote:
On Sun, Mar 20, 2011 at 5:44 PM, Julian Gonggrijp<j.gonggrijp@gmail.com> wrote:
You are confusing two issues that are completely orthogonal to each other.
The point I was trying to make is that documentation seems to be a neglected side of the boost project, BOTH in quality and structure.
Given the body of library documentation I've seen, I'd have to disagree. The Boost documentation is overwhelmingly better than most others.
I suppose that depends on what you are comparing it to. Compared to, for instance, most open source software, yes the documentation is good. But most open source software has execrable documentation, so that doesn't put the bar very high. Compared to, for instance, most commercial software documentation, or even just public documentation about the STL, the Boost docs leave much to be desired.
There are formal reviews of new libraries. Is the documentation subject to the same reviews? If so, I can only say the reviewers have been falling down on the job.
Yes, they are reviewed as part of the library acceptance review. But as you must know documentation is hard to ever get right. And even harder to make it right and good. So we expect documentation to meet a minimal set of usability requirements. But like all things programming, we don't expect perfection. There will always be bugs in code and documentation.
I accept this. What surprised me was when I posted about the documentation not being installed, I expected responses of the form "Yeah, that's a known problem and we have a road map of how we'll overcome it going forward." I didn't expect what appeared to me to be apathy and denial about the problem.
1) The way the Boost documentation is structured.
It's simple: the C++ code is part of the documentation. Hence, installing the documentation == extracting the Boost distribution tree. There is nothing wrong with this approach; it reduces "documentation duplication" which, exactly like reducing code duplication, is a good thing.
What exactly does "installing the documenation == extracting the Boost distribution tree" mean?
It means, that if you want to read the documentation locally you untar the package locally and keep it around.
Does installing the header files == extracting the Boost distribution tree?
For some people it does. But less so on Unix variants, than say Windows. Some people, like myself who wrote the initial install scripts, never actually use the install procedure. I.e. I just use the sources directly and likely never build the usual set of installed libraries. Opting to "embed" the libraries within the project that happens to be using them.
Does installing built libraries in all their various (threading/non-threading, shared/static) forms == extracting the Boost distribution tree"?
No. But sometimes building them, and using them *without* installing them is done. People are fond of building and checking them into their VCS system for their team to use directly.
If I download a tar ball, extract and build according to the rules given, install everything and then delete the tarball and its associated temporary files, I have my headers, I have my libraries, but I DO NOT have any documentation. Since this is the standard way of installing things on Linux and since the installation documentation gives nothing to dissuade someone from this methodology, it appears (to me) to be a major problem.
It's also common for packages with large amounts of documentation to never install documentation locally. Instead opting to provide separate platform independent downloads. Many times in form of PDF or HTML books.
Yes, and while I may think the documentation should be part of the main package, I can understand folks who differ. If there was somewhere I could download a PDF of the entire Boost library documentation, or download an installable tarball of the html documentation for the library, that would be acceptable (although not optimal in my view). As far as I know, Boost does not offer either option.
Of course.. But if others don't point out the documentation bugs how can one expect them to get fixed promptly. You must be familiar with the problem of authors correcting their own writing. And hence why there are book editors, reviewers, and errata.
Yes. I'm wondering if one of Boost's problems is that it hasn't managed to attract any freelance editors or technical writers to contribute, but only programmers. If so, it would be good if some way to address that could be found.
Changing the Boost procedures stop treating documentation as an afterthought would fix both problems.
Very unlikely.
I disagree, but it may be that I am thinking of larger and more sweeping changes than you are.
Note, I'm not discouraging improving the handling of documentation. Just trying to put some pragmatic reality into the picture ;-) And having a way to "install" documentation might be good. But given the varied documentation content it's not as easy as one might think.
And I'm not trying to come across as a radical who wants to throw out the baby with the bathwater. What I would love to see though, is the adoption of some sort of resolution or policy decision to improve the state of the documentation. I have to admit I'm quite fuzzy on how one goes about making global changes for how Boost does things. In any case, what I would love to see is a multi-step plan along the lines of: 1) Attempt to explicitly attract technical writers and editors to be Boost contributors, and try to ensure that their work is welcomed. 2) Create some preliminary bjam methods to relocate the Boost documentation to standard install directories for those OSes that have them. 3) Consider documentation that fails to work after relocation to be buggy. I should point out that most documentation should install fine, as it already doesn't know where the tarball is being extracted and so should already be using relative links. 4) Move towards a set of uniform style and documentation guidelines so that the various libraries agree on how to present information, what needs to link to what, and what formats it should appear in. 5) Ideally it should be eventually be possible to automatically create a PDF book of "The Boost Libraries V#.##" which one could download and/or print out. Heck, at that point Boost could even sell dead-tree copies of it to help cover whatever operating costs the Boost organization might have (assuming this is compatible with Boost's goals). -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
5) Ideally it should be eventually be possible to automatically create a PDF book of "The Boost Libraries V#.##" which one could download and/or print out. Heck, at that point Boost could even sell dead-tree copies of it to help cover whatever operating costs the Boost organization might have (assuming this is compatible with Boost's goals).
There are PDF's downloadable from here: http://sourceforge.net/projects/boost/files/boost-docs/ but note that these downloads don't cover all of Boost (just those libraries that use Quickbook/Boostbook/Docbook for their documentation). A complete "all of Boost" PDF would be a monumentally large document and a non starter IMO, as for a print version, well it would probably require a whole tree per copy ;-) HTH, John.
Stirling Westrup wrote:
1) Attempt to explicitly attract technical writers and editors to be Boost contributors, and try to ensure that their work is welcomed.
That would work if there were some "Boost management" that actively posts "job listings" for "Boost technical writer" position. Unforturnately, I believe that most folks currently involved with Boost at pretty much at their capacity, and mechanisms for setting global direction pretty much don't exist. What this means is if you want to improve documentation, you should either fix it yourself, or somehow attact technical writers ;-)
2) Create some preliminary bjam methods to relocate the Boost documentation to standard install directories for those OSes that have them.
It's the first time I hear that documentation refers to headers in a way that breaks when documentation is moved. That seems kinda strange approach. - Volodya -- Vladimir Prus Mentor Graphics +7 (812) 677-68-40
AMDG On 03/23/2011 03:12 AM, Vladimir Prus wrote:
2) Create some preliminary bjam methods to relocate the Boost documentation to standard install directories for those OSes that have them. It's the first time I hear that documentation refers to headers in a way
Stirling Westrup wrote: that breaks when documentation is moved. That seems kinda strange approach.
I assume that whoever wrote that part of BoostBook figured that, since the headers were there, we might as well link to them from the reference section... Of course, if the html is moved, the relative path to the headers is different. In Christ, Steven Watanabe
On 23/03/11 15:43, Steven Watanabe wrote:
AMDG
On 03/23/2011 03:12 AM, Vladimir Prus wrote:
2) Create some preliminary bjam methods to relocate the Boost documentation to standard install directories for those OSes that have them. It's the first time I hear that documentation refers to headers in a way
Stirling Westrup wrote: that breaks when documentation is moved. That seems kinda strange approach.
I assume that whoever wrote that part of BoostBook figured that, since the headers were there, we might as well link to them from the reference section... Of course, if the html is moved, the relative path to the headers is different.
FWIW, on my various systems with Boost installed via package managers putting docs in /usr/share/doc I'm used to those links not working. I still click them occasionally by accident, but it's not a big deal. John Bytheway
participants (7)
-
John Bytheway -
John Maddock -
Julian Gonggrijp -
Rene Rivera -
Steven Watanabe -
Stirling Westrup -
Vladimir Prus