boostorg / boostorg/website-v2
Support legacy URLs for libs transitioning from monolithic to modular docs
- Dominant language
- HTML
- Stars
- 18
- Forks
- 28
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 77
Description
In his post ["Proposal: Abandoning monolithic Boost documentation"](https://lists.boost.org/Archives/boost/2025/04/259346.php), 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//doc/html/.html` (homepage)
* `doc/libs//doc/html//`
where `` 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//doc/html/` will move to `doc/libs//libs//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//doc/html/poly_collection.html` --> `doc/libs//libs/poly_collection/doc/html/index.html`
* `doc/libs//doc/html/poly_collection/*` --> `doc/libs//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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.