Docs in release tarballs
Hi all, For someone that hasn't been that long involved in Boost, it feels strange to distribute the documentation in the same release tarball as the code, specially considering the usual complains about "Boost size". I'm sure there are reasons behind it, and I'd like to learn about them. This is a candid question, out of being a newbie here. Thanks, Ruben
Ruben Perez wrote:
Hi all,
For someone that hasn't been that long involved in Boost, it feels strange to distribute the documentation in the same release tarball as the code, specially considering the usual complains about "Boost size".
I'm sure there are reasons behind it, and I'd like to learn about them. This is a candid question, out of being a newbie here.
In the beginning, when dinosaurs roamed the Earth, documentation consisted of each library having a heap of .html files in its directory, following no convention in either naming or placement. So there was no way to have a separate tarball with the docs, but there wasn't any need either, because Boost was much smaller.
In the beginning, when dinosaurs roamed the Earth, documentation consisted of each library having a heap of .html files in its directory, following no convention in either naming or placement. So there was no way to have a separate tarball with the docs, but there wasn't any need either, because Boost was much smaller.
Does that mean that dinosaurs still roam around here? :) Is there any reason as of today to keep doing it? (other than no-one volunteering to make the change). I guess there must be, since we have separate no-docs GitHub releases. Regards, Ruben.
Ruben Perez wrote:
In the beginning, when dinosaurs roamed the Earth, documentation consisted of each library having a heap of .html files in its directory, following no convention in either naming or placement. So there was no way to have a separate tarball with the docs, but there wasn't any need either, because Boost was much smaller.
Does that mean that dinosaurs still roam around here? :)
In some cases yes. :-)
Is there any reason as of today to keep doing it? (other than no-one volunteering to make the change). I guess there must be, since we have separate no-docs GitHub releases.
Our documentation build infrastructure is not set up to produce separate documentation tarballs, and it's not clear what needs to change, and how, in order for this to happen. (Apart from the obvious - do something for the libraries that still have their docs in .html form and don't participate in the doc build at all.)
can use an archive that is smaller (because it contains no documentation)
There is an idea that we have started experimenting with, going even further than skipping html docs compilation. - delete the entire doc/ folder, from every library. - remove the test/ folder from each library. - remove the example/ folder from each library. In other words, only important C++ "source" code such as include/ and src/ would remain. Technical feedback is welcome. Do you believe this is untenable or would cause problems for users? Deleting the above mentioned directories breaks compilation in certain cases. It must be investigated further.
Sam Darwin wrote:
can use an archive that is smaller (because it contains no documentation)
There is an idea that we have started experimenting with, going even further than skipping html docs compilation.
- delete the entire doc/ folder, from every library. - remove the test/ folder from each library. - remove the example/ folder from each library.
How much does this gain? And same question, but only with doc/ deleted. I suspect that most of the gains can be realized by deleting three or four carefully chosen libs/X/doc folders.
On 5/24/24 22:24, Sam Darwin via Boost wrote:
How much does this gain?
Tested a few months ago. Don't have the exact numbers, but I think the archives were 50% smaller. You are right, focusing on doc/ might be enough. Still, if other folders can be removed, and not lose functionality...
It depends on what you're willing to lose. Removing docs is mostly acceptable since they are available online, and going online is usually not a problem. Though going online might still be a problem. For example, one of my past employers limited Internet access on the work place, so employees could only visit whitelisted websites. Tests and examples don't have an online equivalent, so if a user wants to test a library in his particular environment, he can't do that if tests are not distributed. Similarly, if he's reading a library docs that refer to an example, he can't view the example and may not be able to continue reading the docs.
participants (4)
-
Andrey Semashev -
Peter Dimov -
Ruben Perez -
Sam Darwin