With legible-names: true, a page is named after the symbol's unqualified name, and siblings colliding case-insensitively are disambiguated with the shortest prefix of the SymbolID that makes them unique in that scope (LegibleNameTable / disambig_chars in AnchorFinalizer.cpp). Both the prefix length and the SymbolID itself move when the code moves.
In mp-units the class mp_units::quantity and the concept mp_units::Quantity collide case-insensitively, so neither gets a clean URL: they become quantity-01.html and Quantity-0c.html. The central type of the library has no stable, readable address.
The suffix also changes under configuration changes that have nothing to do with the symbol's identity as users understand it. Two builds of the same sources, both -std=c++26, differing only in the MP_UNITS_API_NO_CRTP macro (which changes the base class's template argument list):
MP_UNITS_API_NO_CRTP=0 |
MP_UNITS_API_NO_CRTP=1 |
quantity_spec-0a8.html |
quantity_spec-09.html |
quantity_spec-0a9.html |
quantity_spec-0a0.html |
quantity_spec-0f.html |
quantity_spec-0a6.html |
All three URLs change. Because the suffix length depends on which siblings exist, adding an unrelated overload can likewise rename a page that had nothing to do with the change.
The consequence is that permalinks rot. We cannot link a paper, a blog post or a conference slide at a page and expect it to survive the next release, and inbound search results decay silently.
What we would like: an opt-in naming scheme that does not depend on the SymbolID. Disambiguating by symbol kind would cover our case (quantity-class, quantity-concept); a per-symbol name override in the configuration would cover everyone else's.
Reproduced with MrDocs 2026.9.4 (LLVM 23.0.0git).
With
legible-names: true, a page is named after the symbol's unqualified name, and siblings colliding case-insensitively are disambiguated with the shortest prefix of the SymbolID that makes them unique in that scope (LegibleNameTable/disambig_charsinAnchorFinalizer.cpp). Both the prefix length and the SymbolID itself move when the code moves.In mp-units the class
mp_units::quantityand the conceptmp_units::Quantitycollide case-insensitively, so neither gets a clean URL: they becomequantity-01.htmlandQuantity-0c.html. The central type of the library has no stable, readable address.The suffix also changes under configuration changes that have nothing to do with the symbol's identity as users understand it. Two builds of the same sources, both
-std=c++26, differing only in theMP_UNITS_API_NO_CRTPmacro (which changes the base class's template argument list):MP_UNITS_API_NO_CRTP=0MP_UNITS_API_NO_CRTP=1quantity_spec-0a8.htmlquantity_spec-09.htmlquantity_spec-0a9.htmlquantity_spec-0a0.htmlquantity_spec-0f.htmlquantity_spec-0a6.htmlAll three URLs change. Because the suffix length depends on which siblings exist, adding an unrelated overload can likewise rename a page that had nothing to do with the change.
The consequence is that permalinks rot. We cannot link a paper, a blog post or a conference slide at a page and expect it to survive the next release, and inbound search results decay silently.
What we would like: an opt-in naming scheme that does not depend on the SymbolID. Disambiguating by symbol kind would cover our case (
quantity-class,quantity-concept); a per-symbol name override in the configuration would cover everyone else's.Reproduced with MrDocs 2026.9.4 (LLVM 23.0.0git).