speced / speced/respec

Add back references to dfns panels

Open
#5,435 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Feature request
Dominant language
JavaScript
Stars
806
Forks
434
Avg merge
1d 21h
Merged PRs (30d)
32

Description

Is your feature request related to a problem? Please describe.
Specs define terms that other specs may reference. When I click on a definition, a panel pops up and lists all references to the term from within the spec itself. I'd like it to also list references from other specs so that:

  1. Someone reading the spec can hop to other places that make use of a concept.
  2. A spec editor can more easily analyze what might break when they're about to change the meaning of a term or to change the term.
  3. A spec editor can more easily detect cases when other specs link to a non-exported term under their control.

Describe the solution you'd like
On top of dfns extracts, Webref now also produces backrefs extracts as part of curation (in other words in its curated branch). See more details in the README. These extracts follow the same structure as the dfns extracts. This makes the data more readily available for ReSpec, which could ingest it to populate the panels.

One problem though is that the data is more dynamic in essence than the list of references to a term within the spec itself: the list of external specs that reference a term typically evolves over time, regardless of whether the defining spec actually changes.

A similar view already exists in Webdex. For example, see the list of specs that reference the HTMLElement interface. An alternative could be to link to Webdex. There's a similar discussion and request in Bikeshed, see https://github.com/speced/bikeshed/issues/3155

Note: The backrefs extracts could actually be merged with the dfns extracts if that makes things easier to ingest, we kept them separated for now to keep extracts reasonable in size.

Additional context
It may be argued that references to a non-exported term shouldn't be listed, as a way to discourage the practice. The data has back references for both exported and non-exported terms.

Describe any alternatives you've considered
As mentioned above, linking to Webdex could perhaps be a good middle-ground to avoid having to manage a more dynamic list in ReSpec.

Regardless of integration within spec authoring tools, it would be useful to also consider running checks at CI time when a term gets deleted to list specs that are likely affected and need to be updated as well. That's orthogonal to this request :)

Can you or your organization fund the work or help with development?
I may be able to look into developing it.

Contributor guide

Open the contributing guide

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 by tracing how ReSpec currently uses dfns extracts to populate definition panels. Read the Webref backrefs README and compare its extract structure with dfns, then evaluate whether panels should ingest backrefs or link to Webdex. Done means the chosen approach exposes references from other specs without losing the existing in-spec references.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
47/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.