Support resilient anchor linking to symbols/identifiers rather than line numbers
Categories
(Webtools :: Searchfox, enhancement)
Tracking
(Not tracked)
People
(Reporter: asuth, Unassigned)
References
Details
Although in theory you can persistently link to a specific definition/declaration by providing a search link and depending on the auto-follow logic, in general people provide durable links by using "permalink" (hotkey "y") to provide a link to a specific revision so that the line-number can't be out-of-date. This can result in a little dance where the user has to click on "go to latest version" and then manually find the line they were looking for.
At the cost of making the anchor super-ugly, we could potentially:
- When displaying the current analysis revision, have clicks on line numbers that include a symbol definition or declaration opt to produce a resilient encoding. If you click a second time it would go back to just the line number. A third try would toggle it off again. Direct "rev" links produced by Permalink could strip the resilient encoding or leave it around but ignore it until the user clicks "go to latest version".
- The resilient encoding would encode all of the following in the following order with the rationales:
- current line number: If someone hates the resilient link or it's not what they wanted, they can truncate it. Also, this can be used directly when the git revision in the link matches the latest indexed revision.
- pretty identifier of the the symbol we snapped to: This is the most human readable explanation of what we've anchored on, so is good to present next. However, we'd defer to the explicit symbol for identifying the right line unless we can't find that symbol, in which case we'd fall back to locating it using this identifier.
- the "kind" of the thing we snapped to; definitions and declarations are different and may exist in the same file.
- the raw symbol of the thing we snapped to. Together with the "kind" this should let us exactly seek to the right line.
- the revision when this link was authored.
- Each page would have, synchronously available, the information required to end up in one of the following states:
- exact-revision-match: The git rev is the current rev, just use the line-number.
- exact-symbol-match-confirmed-by-number: The git rev is old, but the symbol tells us the current line number.
- exact-symbol-match-but-line-number-drift: We found the symbol but the line number changed.
- symbol-gone-but-unambiguous-id-match: The symbol isn't there but there's a single identifier with the given kind in the current document.
- symbol-gone-ambiguous-id-match: The symbol isn't there, but there are multiple places where we have "kind" for the identifier because of overloads.
- bitrot-file-exists: Can't find the symbol or the identifier, but there's still a file here at least.
- bitrot-file-gone: This means we're displaying our 404 error page because the file doesn't even exist at all, but we can handle that.
- From a UI perspective, we can then do a mixture of:
- Show the current location we arrived at.
- Show the old revision and what the location was in an annoying iframe popped-up from the bottom of the screen that says "hey, you linked to the below, but what you see above me is what we found. Click HERE to make this iframe replace the outer frame or just close this iframe."
Our anchor logic already involves dynamic JS to make this work (and as bug 1561900 documents, some combination of me regressing things and maybe pre-existing breakage that we're now just more aware of because of regressions), so this wouldn't constitute a major change.
Note that I'm only proposing to do this and all the complexity on the "fancy" dev-branch which will have other UX changes as well and be iterated on for quite some time before it would potentially replace our existing UI. So I'd like to focus discussion on the bug to whether resilient linking like this would be useful and whether we can stomach long/ugly anchor references rather than focusing too much on the potential UX dystopia of iframes and clippy-like helpfulness. (I will be seeking a lot of feedback about that in the new year. Because UX dystopia does frequently describe my initial UI forays! ;)
cc'ing :bz and :smaug because of prior anchor-related discussions and general use of searchfox.
|
||
Comment 1•2 years ago
|
||
I'd like this for linking to Python text. In particular, it'd be super-nice to be able to write a robust link to this line:
|
Reporter | |
Comment 2•2 years ago
|
||
One interesting new wrinkle to mention here is that https://wicg.github.io/scroll-to-text-fragment/ has come into existence, and while Firefox doesn't yet support it, our position is "positive" and it's an option that should be considered as a potential incremental mechanism to use or a mechanism we might favor if we think users could end up with fluency with the mechanism. That said, it's potentially better to use our own encoding that wouldn't end up fighting browsers. A link like this seems to work in a blink-based browser, albeit only on initial load?
(In reply to Jim Blandy :jimb from comment #1)
I'd like this for linking to Python text. In particular, it'd be super-nice to be able to write a robust link to this line:
This might be a bit simpler because that's a definition and if we implement bug 1426456 using scip-python we can just model that as "I want a permalink to the file-level symbol definition MINIMUM_RUST_VERSION in python/mozboot/mozboot/util.py" or maybe even more generically identifying we just want any definition for that in "the package rooted at python/mozboot".
MINIMUM_RUST_VERSION = "1.63.0"
Aside: path:.py MINIMUM_RUST_VERSION shows the symbol is also unique in the tree right now, for python at least, so a global definition would work too but I think we need to assume that python packages could exist in a monorepo more than once.
Description
•