Documentation html filenames still contain raw UTF-8
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/0-utf-8-in-doc-filenames`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/dan/0-utf-8-in-doc-filenames), 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
-*- coding: utf-8 -*-
oops, we allowed utf-8 to creep into a file name:
~/to/Macaulay2/doc/Macaulay2-1.2/share/doc/Macaulay2/Macaulay2Doc/html/___Gröbner_spbases.html
```
### Where it stands today
Still generated. `toFilename` maps the ASCII specials through its `tt` table but passes multi-byte
UTF-8 through unchanged, so the installed documentation holds **9 such names**, including the exact one
this file names:
```
share/doc/Macaulay2/Macaulay2Doc/html/___Gröbner_spbases.html
```
### Two closed issues are the same cause, not the same ask
Worth spelling out, because a search turns them up and they look like duplicates:
- **#47** covered this and closed in 2014 on the broken *links*, not on the filename question.
- **#211** is a second symptom of the same cause — the file appearing under two different UTF-8
normalizations (`303 266` vs `314 210`) — closed on *"just remember how I do it and check that one
file"*.
So neither settled the ask, which is why the file was still worth filing.
### Why it matters beyond tidiness
A non-ASCII filename is a portability and normalization hazard rather than an aesthetic one: it is what
produced #211's two spellings of the same page, and it constrains any filesystem or archive format in
the distribution chain that is not UTF-8 clean.
`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 by locating the toFilename entry point and inspecting its tt table, then examine the generated names under share/doc/Macaulay2/Macaulay2Doc/html/. Compare the nine names containing raw UTF-8, including ___Gröbner_spbases.html, and trace where those names are produced. Done means generated documentation filenames no longer contain raw UTF-8 while their links remain usable.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100