Macaulay2 / Macaulay2/M2

Documentation pages carry no link for reporting a problem with them

Open
#4,549 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/0.8-documentation-suggestion-link, one of the 857 files removed from the pre-GitHub bugs/ tree by d2c8d27826 and catalogued in #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
Put a mailto link at the bottom of each html doc page so suggestions can be mailed easily.

<a href="mailto:abbeyvet@outfront.net?CC=spooky@outfront.net
&BCC=thomasbrunt@outfront.net&Subject=Please%2C%20I%20insist
%21&Body=Hi%0DI%20would%20like%20to%20send%20you%20
%241000000%20to%20divide%20as%20you%20see%20fit%20among
%20yourselves%20and%20all%20the%20moderators.%0DPlease%
20let%20me%20know%20to%20whom%20I%20should%20send
%20the%20check.">this link</a>


We could have another button for automatically starting a post on the google group about this doc page.

And one that goes to a bug tracking system.
Where it stands today

Never added: no mailto, feedback or issue link is emitted onto documentation pages. The mailto hits in
the tree are author addresses in ov_preface.m2 and package metadata, not per-page feedback links.

The ask, in modern terms

The file proposes a mailto: link (and elsewhere a Google Group), both of which are dated. What it is
actually asking for is a route from a documentation page to a place to report a problem with it
which today means the GitHub tracker.

Why it is worth having

Documentation errors are found by readers, at the moment of reading, and the cost of reporting one is
currently: leave the page, find the repository, work out which node you were on, and describe it. A
per-page link that carries the node name would collapse that to one click — and the node name is
already known at generation time, since it is in the page title.

Notes for whoever picks this up

defaultHEAD (html.m2:62-68) is where the per-page LINK elements are emitted (the favicon went in
there), so there is an existing hook for adding something to every page. Whether the link belongs in the
header or the footer is a design question; the footer is where readers look for it.

open · disposition issue · source of truth: 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 in html.m2 at defaultHEAD around lines 62-68, where per-page LINK elements are emitted. Determine where a feedback link fits best, then verify that every generated documentation page offers a route to the GitHub tracker carrying the page’s node name.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.