tc39 / tc39/ecmarkup

Make it easy to add Bikeshed metadata

Open
#104 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
245
Forks
80
Avg merge
10h 46m
Merged PRs (30d)
2

Description

For the purposes of allowing web specs (written in Bikeshed, or written in something that obeys the Bikeshed definition contract) to more easily reference Ecmarkup specs, it would be good if Ecmarkup could help with annotating ES-style specs correctly. This would allow people to avoid definition blocks that manually and inconsistently import the terms in each spec, e.g.:

Here are some easy initial ideas:

  • (Blocked on https://github.com/tabatkins/bikeshed/issues/801) Any clause with an aoid should automatically get data-dfn-type="abstract-op" and data-lt="${aoid}".
  • Any <dfn> in the source file should automatically get an (empty) data-export attribute, unless it is written as <dfn noexport> in the source file. ES uses <dfn> sparingly and generally only for things that are externally useful.

I am not sure how to handle class/constructor/method definitions. In general other specs don't reference most ES methods, so I think we can leave solving that out for now. But we want some way of markup up all the "sections" (e.g. Promise Objects) as "interfaces" (data-dfn-type="interface", data-lt="${className}"). Maybe we want to mark up the intrinsic constructors as well (so e.g. the Promise constructor gets data-dfn-type="constructor", data-lt="%${className}% (not barename class name, as other specs should always reference the % version!), and data-dfn-for="${className}".

TypedArray classes and constructors are their own problem, where we want multiple terms to go to the same sections. Probably that will need manual markup.

/cc @tabatkins

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 reading the Bikeshed definition contract and comparing the cited Streams, Custom Paint, and Web Bluetooth definition blocks with the proposed Ecmarkup behavior. Trace how Ecmarkup represents aoid clauses and dfn elements, then determine how metadata should be generated. Done means the aoid and dfn cases have an agreed implementation and the unresolved interface, constructor, and TypedArray cases are explicitly scoped.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.