search

Ravenbrook / mps

The Memory Pool System
http://www.ravenbrook.com/project/mps
Other
560 stars 75 forks source link

Design cross-references are not robust #199

Open rptb1 opened 1 year ago

rptb1 commented 1 year ago
  1. m. The link to guide.hex.trans doesn't work on GitHub. rule.generic.achieve

Originally posted by @rptb1 in https://github.com/Ravenbrook/mps/pull/193#pullrequestreview-1336968567

MPS design documents are text documents marked up using basic reStructuredText. Cross-references in those documents are marked up with URLs designed to work with Charlotte, Ravenbrook's simple internal web server, as can be seen at https://www.ravenbrook.com/project/mps/master/design

Charlotte supported extensionless URLs intended to match the semantic design promoted by Tim Berners-Lee, e.g. "design/sig" would reference a page generated from the underlying file "sig.txt" or "sig.rst" or "sig.html" or whatever was appropriate.

GitHub provides a "preview" of a marked-up text document that is not as flexible. To refer to "sig" you must specify the actual file "design/sig.txt". This is understandable as GitHub is just a thin layer on the contents of Git.

However, many of our design documents contain semantic URLs, and are broken as presented by GitHub.

On the other hand, if you specify the full path as in https://github.com/Ravenbrook/mps/pull/193/commits/2697bc1891527902c5f4cb17d6928fc1f57b6e14 so that the links work in GitHub, they break in the manual. They also cause Charlotte to display the raw text of the referent because Charlotte interprets a request for a file as a request for a file.

rptb1 commented 1 year ago

This kind of thing has happened before. The MPS his migrated through at least two previous SCM systems. Tags are robust against this, and are the main method of cross-referencing, but if we're going to make them clickable (and we should) then the clicks ought to work!

rptb1 commented 1 year ago

To make the links clickable in GitHub (which we don't control) then the URLs are going to have to refer to the destination file, e.g. "design/sig.txt", even though that's fragile. That's an update to all the design document text files.

It's essential that manual build recognizes and rewrites those links. It's also optional that we update Charlotte to do something similar. They're both in Python so we can likely share some work.

Relevant code in the current MPS Sphinx extension https://github.com/Ravenbrook/mps/blob/3104ab67ae1334f5996a465d881bd713a4427922/manual/source/extensions/mps/designs.py#L82-L88

We should work towards #172 when updating it.

rptb1 commented 1 year ago

Sorry Tim. We tried. But worse is better.