Written by Claude (Claude Opus 5, via Claude Code), not by @d-torrance, whose account posted it -- please weigh it accordingly.
M2 --help lists 30 command-line options. Macaulay2/man/M2.1.in documents 21 of them. Missing from the man page:
--check --no-preload --no-randomize --no-time --no-tty
--read-only-files --restarted --srcdir --webapp
The man page also has no ENVIRONMENT section, while --help documents EDITOR and six GC_* variables (startup.m2.in:414-421).
Why it drifts
The two lists are maintained by hand, in different files, with nothing checking one against the other. The --help text is a chain of << in usage := at m2/startup.m2.in:373-421; the man page is a hand-written list of .TP entries at man/M2.1.in:14-84. The man page's Options section was last changed by b3590eabff (2020-12-17), which renamed --no-setup to --no-core. Everything added since has gone into startup.m2.in alone.
That drift is visible in the record: #1552 corrected the --srcdir description in M2 --help and did not touch the man page, which does not mention --srcdir at all.
Suggested closing condition
Either bring M2.1.in up to date and give it an ENVIRONMENT section, or -- better, since then it cannot drift again -- generate its Options section from the same source as the --help text at build time.
Noticed while triaging bugs/dan/2-doc-command-line-options for #36. That file's own ask, "document the command line options", is satisfied: #3745 made the manual node "invoking the Macaulay2 program" embed live M2 --help output, so the manual cannot go stale. Only the man page did. This finding is not that file's ask and has no row in the catalog.
M2 --helplists 30 command-line options.Macaulay2/man/M2.1.indocuments 21 of them. Missing from the man page:The man page also has no
ENVIRONMENTsection, while--helpdocumentsEDITORand sixGC_*variables (startup.m2.in:414-421).Why it drifts
The two lists are maintained by hand, in different files, with nothing checking one against the other. The
--helptext is a chain of<<inusage :=atm2/startup.m2.in:373-421; the man page is a hand-written list of.TPentries atman/M2.1.in:14-84. The man page's Options section was last changed byb3590eabff(2020-12-17), which renamed--no-setupto--no-core. Everything added since has gone intostartup.m2.inalone.That drift is visible in the record: #1552 corrected the
--srcdirdescription inM2 --helpand did not touch the man page, which does not mention--srcdirat all.Suggested closing condition
Either bring
M2.1.inup to date and give it anENVIRONMENTsection, or -- better, since then it cannot drift again -- generate its Options section from the same source as the--helptext at build time.Noticed while triaging
bugs/dan/2-doc-command-line-optionsfor #36. That file's own ask, "document the command line options", is satisfied: #3745 made the manual node "invoking the Macaulay2 program" embed liveM2 --helpoutput, so the manual cannot go stale. Only the man page did. This finding is not that file's ask and has no row in the catalog.