A missing documentation database is not rebuilt automatically
Nobody has claimed this yet.
- Dominant language
- Macaulay2
- Stars
- 435
- Forks
- 297
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 11
Description
This issue was triaged from [`bugs/dan/1-building-doc-databases`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/dan/1-building-doc-databases), one of the 857 files removed from the pre-GitHub `bugs/` tree by [`d2c8d27826`](https://github.com/Macaulay2/M2/commit/d2c8d27826) and catalogued in [#36](https://github.com/Macaulay2/M2/issues/36). **The commentary below was written by Claude (Claude Opus 5, via Claude Code)**, not by @d-torrance, whose account posted it -- please weigh it accordingly.
### The original file, verbatim
```text
The doc databases for packages may not be getting built if we start fresh with
just the CommonStagingArea files, because *.installed is there. (FIXED)
It would be nice also if a missing database could be rebuilt automatically, provided
the directory is writable.
```
### Where it stands today
The file settles its own first half — it says `(FIXED)` for the `.installed` problem. The second half is
unmet.
### What is missing
`installPackage` touches `.installed` when a run completes (`installPackage.m2:846-849`), but nothing
detects a **missing documentation database** and rebuilds it, writable directory or not. So a prefix
whose `.installed` stamp survives while its `rawdocumentation` database does not is a state M2 cannot
recover from on its own, even though everything needed to rebuild is present.
### Why that state arises
Exactly as the file describes: starting from a partial tree — the staging area, a copied prefix, an
interrupted install — leaves the stamp and loses the database. `tallyInstalledPackages` then skips the
package entirely ("maybe installation was interrupted, so ignore this package"), so the documentation is
silently absent rather than rebuilt.
### Nearby but not the same
**#1643** wants one documentation database per prefix instead of per package, for speed; **#776** wants
the open database files bounded by an LRU cache. Neither rebuilds a missing one.
`open` · disposition `issue` · source of truth: [`bug-triage/catalog.tsv`](https://github.com/d-torrance/M2/blob/bug-triage/bug-triage/catalog.tsv)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in installPackage.m2 around lines 846-849, then trace tallyInstalledPackages and the handling of the rawdocumentation database. Reproduce the state where .installed remains but the documentation database is missing, and verify that a writable installation can recover it automatically without skipping the package.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100