Support legacy URLs for libs transitioning from monolithic to modular docs

[joaquintides]

In his post "Proposal: Abandoning monolithic Boost documentation", René Rivera (@grafikrobot) proposes that the project abandon so-called monolithic docs in favor of modular docs (already more prevalent overall) .

What are monolithic docs

A subset of Boost libraries (around 1/3 of them all) place their generated docs in a common doc/html folder outside their own directory, which allows for the construction of a global document encompassing them all called the BoostBook Subset:

https://www.boost.org/doc/libs/1_88_0/doc/html/libraries.html

Consider a library with monolithic docs, Boost.PolyCollection, and one with modular docs, Boost.MultiIndex: their doc homepages for Boost 1.88 are located at

• https://www.boost.org/doc/libs/1_88_0/doc/html/poly_collection.html
• https://www.boost.org/doc/libs/1_88_0/libs/multi_index/doc/index.html

respectively, and further sections within docs look like:

• https://www.boost.org/doc/libs/1_88_0/doc/html/poly_collection/tutorial.html
• https://www.boost.org/doc/libs/1_88_0/libs/multi_index/doc/tutorial/index.html

So, a monolithic doc for library X lives at

• doc/libs/<version>/doc/html/<lib_x>.html (homepage)
• doc/libs/<version>/doc/html/<lib_x>/

where <lib_x> is chosen by the library itself, typically being the library short name (e.g. variant) or that with boost_ preprended (e.g. boost_units). There are three monolithic-doc libraries that break this convention:

• MultiArray: their non-homepage sections are placed directly under doc/html
• STLInterfaces: homepage stl_interfaces.html, subdirectory boost_stlinterfaces
• YAP: homepage yap.html, subdirectory boost_yap

Request: support legacy URLs for transitioned libraries

If René's proposal gets traction, monolithic-doc libs living at doc/libs/<version>/doc/html/ will move to doc/libs/<version>/libs/<lib_x>/doc/html/ (other transition schemes are possibles, but this is the most likely). I propose that we support legacy URLs (as plently of those will be archived throughout the Internet) by redirecting them to the new location.

For maximum flexibility, these redirects will probably need be done on a per-library basis, because, as we have seen, the structure of BoostBook is not exactly fixed. Considering again the case of Boost.PolyCollection, the required redirects would be:

• doc/libs/<version>/doc/html/poly_collection.html --> doc/libs/<version>/libs/poly_collection/doc/html/index.html
• doc/libs/<version>/doc/html/poly_collection/* --> doc/libs/<version>/libs/poly_collection/doc/html/*

Case study: Boost.PolyCollection

If we decide to proceed with this issue, I can modularize Boost.PolyCollection right away so that we have an initial set of redirects to work on. If René decides to post a set of PRs for modularization of all/some libraries, it would be perfect if he could also synchronize here.

[sdarwin]

A partial solution alternative could be to keep static index html files in the boost archive wherever previous docs used to be. Files such as https://github.com/boostorg/url/blob/develop/index.html That would redirect top-level index.html pages to their new location. And in fact, that somewhat already exists in the boost/doc/html folder. However not for all libraries and all files. (So this is just a comment, not a full solution.)

There are dozens of redirects already in the nginx config configmap-nginx.yaml, and that supports regex and wildcards. So it can be the place to install redirects.

[joaquintides]

That would work for the top-level html, but not the rest --unless you mean having such proxy files for every file under doc/libs/<version>/doc/html/<lib_x>/.

[Lastique]

Old Boost releases (which use the "monolithic" docs layout), presumably, will be left unchanged and only the future releases (that switched to the "modular" layout) will change. So for old releases and existing links in the wild (except those referencing develop, master and the latest release, but these links are explicitly not stable), nothing will change and the links will remain working. For new releases, I'm not sure there is a point in keeping links into the "monolithic" layout working. Any unstable links that pointed to the "monolithic" layout will need to be updated, and it is better if they break so that people notice and update them. We also don't want new links into the "monolithic" layout to appear in the wild.