info documentation has no Index node, and Macaulay2Doc's Top node has no menu
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-info-doc`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/dan/1-info-doc), 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
figure out how info doc can make the toc and index accessible to readers
```
### Where it stands today
Half met, half never attempted — and the check that would have caught the gap has been switched off
since 2009.
### The machinery is there
A full Next/Prev/Up spine over all **2010** nodes of `Macaulay2Doc.info`, a valid tag table
(`installPackage.m2:411-414`), and **236** `* Menu:` blocks from `format.m2:315-331`, whose code comments
explain why Up links and unwrapped menu items matter for the emacs reader.
### But the flagship manual's Top node has no menu at all
The next node begins at line 169 and the first menu anywhere is at line **442**. So at the manual's entry
point, `m`, the digit keys and standalone info's table of contents do nothing — only follow-reference
works.
It is package-dependent: `Varieties.info` *has* a Top menu. Only `Subnodes` feeds the menu generator, and
`Macaulay2Doc`'s `ov_top.m2` uses hand-rolled `UL` lists instead.
### The index half is simply absent
**Zero** `Index` nodes in any M2 info file — while `makeSortedIndex` (`installPackage.m2:421-441`) builds
exactly that for html over the same node list. The data is computed and never rendered into info.
### Why this went unnoticed for seventeen years
`packages/Makefile.in:121-122` disables `check::check-info` with the comment that `Info-validate`
*"doesn't work well enough to be useful"* — commented out by `f766cd4dfa8` on 2009-01-06.
`Info-validate` is the tool that flags nodes reachable only by cross-reference.
### Related
`2-toc-index-info-doc` is the same ask with a proposed mechanism, still untriaged; **#4554** is the
sibling about the `dir` file *beside* the `.info` rather than navigation inside it.
`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 with packages/Makefile.in around check-info, then read installPackage.m2:411-441, format.m2:315-331, and Macaulay2Doc's ov_top.m2 to understand the existing node, menu, and index generation. Compare the generated Macaulay2Doc.info with Varieties.info; done means the flagship manual has a usable Top menu and rendered Index nodes, with validation addressing the missing navigation.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100