Make it easy to add Bikeshed metadata
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
aoidshould automatically getdata-dfn-type="abstract-op"anddata-lt="${aoid}". - Any
<dfn>in the source file should automatically get an (empty)data-exportattribute, 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
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 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