I think this fix is actually not too hard, but will require some short-term pain. But no more pain than is already present.

1. Add a new field, perhaps Dist to each function's entry in the pdldoc.db.
2. Make everything that comes in the PDL distribution have Dist=>PDL.
3. Change add_module so that external modules get an appropriate value for the Dist. This could just be the module name.
4. (Perhaps prepend a short token, such as a PDL version, to the beginning of pdldoc.db, to enable checks on pdldoc.db version skew.)
5. Instead of the install script just dropping the new pdldoc.db into the install location, it should read in the old pdldoc.db in, copy the entries that don't have Dist=>PDL to the new pdldoc.db, and write out the resulting merged new db to the install location. This will be easier once the old pdldoc.db is the same format as the new db.

I think an even better approach would be to destroy the existing db on PDL-install, but to scan for, and make entries for, all PDL modules (including ones already installed), probably using Module::Find. This has the virtue of not being as much work to implement, and means not needing to make code that can read older db formats.

What do you think?

I don't think we would have needed to make code that reads older DB formats: the next install of PDL would wipe on non-core docs, leaving the user in the same position they are now. No better, no worse. Future installs of PDL would be able to do the merging.

However, I do like your approach, too. Non-core PDL-namespace modules installed after PDL can still use the add_module hook in PDL::Doc. Non-core PDL-namespace modules already present when a new PDL gets installed will be automatically picked up. No fancy database shenanigans.

I have just checked locally, and after an uninstall of PDL and re-install (proved by the fact that PDL::LinearAlgebra gets segfaults now due to the Core structure changing), help cgtsv (a P:LA function) is still in the database. I assume this was fixed by the superb work in #234 (thanks again Derek!), but regardless it is now fixed, so I can now close this.