Macaulay2 / Macaulay2/M2

info documentation has no Index node, and Macaulay2Doc's Top node has no menu

Open
#4,587 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bugs directory Documentation
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.