2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
2 | title: test title! 3 | toc: false 4 | date: 2018-04-02 5 | assets: none 6 | stage: 0 7 | status: draft 8 | contributors: Rick Waldron, Mid-World 9 | copyright: true 10 | boilerplate: 11 | address: test/boilerplate-address.fixture 12 |13 | 14 | -------------------------------------------------------------------------------- /test/baselines/sources/boilerplate-license.html: -------------------------------------------------------------------------------- 1 |
2 | title: test title! 3 | toc: false 4 | date: 2018-04-02 5 | assets: none 6 | stage: 0 7 | status: draft 8 | contributors: Rick Waldron, Mid-World 9 | copyright: true 10 | boilerplate: 11 | license: test/boilerplate-license.fixture 12 |13 | 14 | -------------------------------------------------------------------------------- /test/baselines/sources/boilerplate-copyright.html: -------------------------------------------------------------------------------- 1 |
2 | title: test title! 3 | toc: false 4 | date: 2018-04-02 5 | assets: none 6 | stage: 0 7 | status: draft 8 | contributors: Rick Waldron, Mid-World 9 | copyright: true 10 | boilerplate: 11 | copyright: test/boilerplate-copyright.fixture 12 |13 | 14 | -------------------------------------------------------------------------------- /boilerplate/address.html: -------------------------------------------------------------------------------- 1 |
Ecma International
2 |Rue du Rhone 114
3 |CH-1204 Geneva
4 |Tel: +41 22 849 6000
5 |Fax: +41 22 849 6001
6 |Web: https://ecma-international.org/
7 | -------------------------------------------------------------------------------- /test/boilerplate-address.fixture: -------------------------------------------------------------------------------- 1 |Tet Corporation
2 |2 Hammarskjöld Plaza
3 |New York City, New York
4 |Tel: 123-456-7890
5 |Fax: 123-456-7890
6 |Web: http://www.tet-corporation.com/
7 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "include": ["src/**/*"], 3 | "compilerOptions": { 4 | "target": "es2019", 5 | "module": "commonjs", 6 | "moduleResolution": "node", 7 | "strict": true, 8 | "declaration": true, 9 | "stripInternal": true, 10 | "outDir": "lib", 11 | "lib": ["es2020", "dom", "dom.iterable"], 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /test/baselines/sources/duplicate-productions.html: -------------------------------------------------------------------------------- 1 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Clause Foo(_a_, _b_)
8 | 9 |Clause Foo( _a_, _b_ )
9 | 10 |2 | title: test title! 3 | toc: false 4 | date: 2018-04-02 5 | assets: none 6 | stage: 0 7 | status: draft 8 | contributors: Rick Waldron, Mid-World 9 | copyright: true 10 | boilerplate: 11 | address: test/boilerplate-address.fixture 12 | copyright: test/boilerplate-copyright.fixture 13 | license: test/boilerplate-license.fixture 14 |15 | 16 | -------------------------------------------------------------------------------- /test/baselines/sources/escaping.html: -------------------------------------------------------------------------------- 1 |
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
blah
8 |U+200C (ZERO WIDTH NON-JOINER) is abbreviated "<ZWNJ>"
9 |<b>also doesn't escape when *emd* and autolinks to ReturnIfAbrupt are present.
10 |Escpaing inside xref is preserved:
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
c1
8 |This is some content and such.
9 |c1.1
11 |This is a note!
18 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Example SDO
8 |Example Grammar
18 |Syntax
19 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 | 7 |
Title
9 | 10 |You can refer to a step before it occurs in text, like step
You can refer to it after as well, like step
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
This
10 | 11 |That
15 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 | 7 |
Example
9 |Static Semantics: AbstractOperation
18 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Intro
8 |C
19 |6 | copyright: false 7 | assets: none 8 | multipage: true 9 |10 | 11 |
Intro
13 |Some text.
14 |Second Clause
18 |A cross-section reference: Alg.
19 |A relative image: 
.
Third Clause
24 |Some text.
25 |Algorithm
27 |Pretend there's an algorithm here.
28 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/charset-present.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
-
5 |
- Toggle shortcuts help
?
6 | - Toggle "can call user code" annotations
u
7 |
8 | - Jump to search box
/
9 | - Toggle pinning of the current clause
p
10 | - Jump to the nth pin
1-9
11 | - Jump to the 10th pin
0
12 | - Jump to the most recent link target
`
13 |
14 |
15 |
--------------------------------------------------------------------------------
/test/baselines/sources/example.html:
--------------------------------------------------------------------------------
1 | 2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Examples outside of clauses aren't processed specially.
7 |Example Section
13 |Example Subclause
19 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 | Content
14 |
15 |
--------------------------------------------------------------------------------
/src/GrammarAnnotation.ts:
--------------------------------------------------------------------------------
1 | import type Spec from './Spec';
2 | import type Production from './Production';
3 |
4 | import Builder from './Builder';
5 |
6 | export default class GrammarAnnotation extends Builder {
7 | /** @internal */ production: Production;
8 |
9 | constructor(spec: Spec, prod: Production, node: HTMLElement) {
10 | super(spec, node);
11 | this.production = prod;
12 | }
13 |
14 | build() {
15 | if (!this.node.firstChild) return;
16 |
17 | if (this.node.firstChild.nodeType === 3) {
18 | this.node.firstChild.textContent = '[' + this.node.firstChild.textContent;
19 | } else {
20 | const pre = this.spec.doc.createTextNode('[');
21 | this.node.insertBefore(pre, this.node.children[0]);
22 | }
23 |
24 | const post = this.spec.doc.createTextNode(']');
25 | this.node.appendChild(post);
26 | }
27 | }
28 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/date.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
test title!
13 | 14 |Some body content
15 | 16 |toc: false\ncopyright: false\nassets: none
hi
`));
29 | });
30 | });
31 |
--------------------------------------------------------------------------------
/src/.eslintrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "parser": "@typescript-eslint/parser",
3 | "parserOptions": {
4 | "sourceType": "module",
5 | "ecmaVersion": 2020,
6 | "//": "NB project is relative to the directory you run eslint from, see https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser#parseroptionsproject",
7 | "project": "./tsconfig.json"
8 | },
9 | "extends": [
10 | "../.eslintrc.json",
11 | "plugin:@typescript-eslint/eslint-recommended"
12 | ],
13 | "plugins": [
14 | "@typescript-eslint"
15 | ],
16 | "rules": {
17 | "@typescript-eslint/no-use-before-define": [
18 | "error",
19 | {
20 | "functions": false,
21 | "typedefs": false
22 | }
23 | ],
24 | "@typescript-eslint/no-unnecessary-type-assertion": "error",
25 | "@typescript-eslint/no-unused-vars": "error",
26 | "no-unused-vars": "off"
27 | }
28 | }
29 |
--------------------------------------------------------------------------------
/src/lint/rules/algorithm-step-labels.ts:
--------------------------------------------------------------------------------
1 | import type { OrderedListItemNode } from 'ecmarkdown';
2 | import type { Reporter } from '../algorithm-error-reporter-type';
3 |
4 | const ruleId = 'algorithm-step-labels';
5 |
6 | /*
7 | Checks that step labels all start with `step-`.
8 | */
9 | export default function (report: Reporter, node: OrderedListItemNode, algorithmSource: string) {
10 | const idAttr = node.attrs.find(({ key }) => key === 'id');
11 | if (idAttr != null && !/^step-/.test(idAttr.value)) {
12 | const itemSource = algorithmSource.slice(
13 | idAttr.location.start.offset,
14 | idAttr.location.end.offset,
15 | );
16 | const offset = itemSource.match(/^id *= *"/)![0].length;
17 | report({
18 | ruleId,
19 | line: idAttr.location.start.line,
20 | column: idAttr.location.start.column + offset,
21 | message: `step labels should start with "step-"`,
22 | });
23 | }
24 | }
25 |
--------------------------------------------------------------------------------
/src/lint/rules/enum-casing.ts:
--------------------------------------------------------------------------------
1 | import type { Reporter } from '../algorithm-error-reporter-type';
2 | import type { OrderedListItemNode } from 'ecmarkdown';
3 | import { offsetToLineAndColumn } from '../../utils';
4 |
5 | const ruleId = 'enum-casing';
6 |
7 | /*
8 | Checks that ~enum-values~ are kebab-cased.
9 | */
10 | export default function (report: Reporter, step: OrderedListItemNode, algorithmSource: string) {
11 | for (const item of step.contents) {
12 | if (item.name !== 'tilde' || item.contents.length !== 1 || item.contents[0].name !== 'text') {
13 | continue;
14 | }
15 | const text = item.contents[0];
16 | if (/[\p{Uppercase_Letter}\s]/u.test(text.contents)) {
17 | const location = offsetToLineAndColumn(algorithmSource, text.location.start.offset);
18 | report({
19 | ruleId,
20 | message: 'enum values should be lowercase and kebab-cased',
21 | ...location,
22 | });
23 | }
24 | }
25 | }
26 |
--------------------------------------------------------------------------------
/filter-entities.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | // entities.json is from https://html.spec.whatwg.org/entities.json
4 | // which is built by https://github.com/whatwg/html-build/tree/main/entities
5 | // this processes it into a form more useful for us
6 | // no new entities will be added, so the output of this file is committed
7 | // rather than running it every time
8 |
9 | let fs = require('fs');
10 | let entities = require('./entities.json');
11 |
12 | let transformed = Object.fromEntries(
13 | Object.entries(entities).map(([k, v]) => {
14 | // whitespace, default-ignorable, combining characters, control characters
15 | if (
16 | v.characters === '&' ||
17 | v.characters === '<' ||
18 | /\p{White_Space}|\p{DI}|\p{gc=M}|\p{gc=C}/u.test(v.characters)
19 | ) {
20 | return [k, null];
21 | }
22 | return [k, v.characters];
23 | }),
24 | );
25 | fs.writeFileSync('./entities-processed.json', JSON.stringify(transformed), 'utf8');
26 |
--------------------------------------------------------------------------------
/test/baselines/sources/max-clause-depth.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
12 |
14 |
17 |
19 |
21 |
22 |
23 |
25 |
27 |
28 |
29 |
30 |
32 |
33 |
34 |
36 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/ecmarkdown.html:
--------------------------------------------------------------------------------
1 |
2 |
8 |
11 | 1. Return Value(_val_);
12 |
13 |
14 |
15 | Value2(_t_)
16 | = DateValue(_t_) if Type(_t_) is string
17 | = _t_
18 |
19 |
20 |
21 | DateValue(t)
22 | = 0 if _t_ = 0
23 | = 1 if _t_ = 1
24 | = 2
25 |
26 |
27 |
28 | Value(_t_)
29 | = DateValue(_t_) if Type(_t_) is string
30 | = _t_
31 |
32 |
33 |
34 | 1. Return Value(_val_);
35 |
36 |
37 |
39 |
--------------------------------------------------------------------------------
/test/baselines/sources/code.html:
--------------------------------------------------------------------------------
1 |
8 |
21 |
--------------------------------------------------------------------------------
/src/H1.ts:
--------------------------------------------------------------------------------
1 | import Builder from './Builder';
2 | import type { Context } from './Context';
3 |
4 | export default class H1 extends Builder {
5 | static elements = ['H1'];
6 |
7 | static async enter() {
8 | // do nothing
9 | }
10 |
11 | static async exit({ node, clauseStack }: Context) {
12 | const parent = clauseStack[clauseStack.length - 1] || null;
13 | if (parent === null || parent.header !== node) {
14 | return;
15 | }
16 | const headerClone = node.cloneNode(true) as Element;
17 | for (const a of headerClone.querySelectorAll('a')) {
18 | a.replaceWith(...a.childNodes);
19 | }
20 | parent.titleHTML = headerClone.innerHTML;
21 | parent.title = headerClone.textContent;
22 | if (parent.number) {
23 | // we want to prepend some HTML but setting `innerHTML` on the node will blow away the existing children,
24 | // which messes up other stuff which expects those to keep their identity
25 | node.insertAdjacentHTML('afterbegin', parent.getSecnumHTML());
26 | }
27 | }
28 | }
29 |
--------------------------------------------------------------------------------
/src/lint/rules/for-each-element.ts:
--------------------------------------------------------------------------------
1 | import type { Reporter } from '../algorithm-error-reporter-type';
2 | import type { Seq } from '../../expr-parser';
3 | import type { OrderedListItemNode } from 'ecmarkdown';
4 |
5 | const ruleId = 'for-each-element';
6 |
7 | /*
8 | Checks that "For each" loops name a type or say "element" before the variable.
9 | */
10 | export default function (
11 | report: Reporter,
12 | step: OrderedListItemNode,
13 | algorithmSource: string,
14 | parsedSteps: Map,
15 | ) {
16 | const stepSeq = parsedSteps.get(step);
17 | if (stepSeq == null || stepSeq.items.length < 2) {
18 | return;
19 | }
20 | const [first, second] = stepSeq.items;
21 | if (first.name === 'text' && first.contents === 'For each ' && second.name === 'underscore') {
22 | report({
23 | ruleId,
24 | line: second.location.start.line,
25 | column: second.location.start.column,
26 | message: 'expected "for each" to have a type name or "element" before the loop variable',
27 | });
28 | }
29 | }
30 |
--------------------------------------------------------------------------------
/test/boilerplate-license.fixture:
--------------------------------------------------------------------------------
1 | test title!
--------------------------------------------------------------------------------
/test/baselines/generated-reference/shortname.html:
--------------------------------------------------------------------------------
1 |
2 | test title!
--------------------------------------------------------------------------------
/test/baselines/sources/grammar.html:
--------------------------------------------------------------------------------
1 |
2 |
9 | FooTerminal :
10 | Inserting `anRHS`
11 | Deleting `anRHS`
12 | Modifying Existing Old Production
13 |
14 |
15 | NewTerminal :
16 | `t`
17 |
18 |
19 | LookaheadExample ::
20 | `&&` `n` [lookahead <! {`1`, `3`, `5`, `7`, `9`}] DecimalDigits
21 | DecimalDigit [lookahead <! DecimalDigit]
22 |
23 | HTMLEntitiesExample ::
24 | > This is technically a “production”
25 |
26 | ButOnlyExample ::
27 | DecimalEscape [> but only if the CapturingGroupNumber of |DecimalEscape| is <= _NcapturingParens_]
28 |
29 |
30 |
33 | 1. Can also have productions in steps.
34 | 1. Example is Atom :: `(` Disjunction `)` .
35 |
36 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/ins-nonterminal.html:
--------------------------------------------------------------------------------
1 |
2 |
8 | 1. Can call abstract operations in this spec: Internal();
9 | 1. Can call abstract operations in ES6: ReturnIfAbrupt(_completion_);
10 | 1. Can call abstract operations in a biblio file: Biblio();
11 | 1. Unfound abstract operations just don't link: Unfound();
12 | 1. Can prefix with ! and ?.
13 | 1. Let _foo_ be ? Internal();
14 | 1. Set _foo_ to ! Internal();
15 | 1. Set _foo_ to ! SDO of _operation_.
16 | 1. Set _foo_ to ! _operation_.[[MOP]]().
17 | 1. A Record looks like this: Record { [[Key]]: 0 }.
18 | 1. A List looks like this: « 0, 1 ».
19 |
20 |
21 |
22 |
24 |
25 |
32 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/escaping.html:
--------------------------------------------------------------------------------
1 |
2 | This is a note. Since it is outside a clause it is unstyled.
7 |
8 |
9 |
12 |
13 |
14 |
17 |
18 |
19 |
22 |
23 |
24 |
26 | 1. This step is required.
27 | 1. [normative-optional=""] This step is optional.
28 | 1. [normative-optional="", legacy=""] This step is legacy.
29 | 1. [legacy=""] This step is only legacy, but has substeps.
30 | 1. This is a substep.
31 | 1. [deprecated=""] This step is optional.
32 | 1. This step is required.
33 |
34 |
--------------------------------------------------------------------------------
/src/Builder.ts:
--------------------------------------------------------------------------------
1 | import type Spec from './Spec';
2 | import type { Context } from './Context';
3 |
4 | // We use this instead of `typeof Builder` because using the class as the type also requires derived constructors to be subtypes of the base constructor, which is irritating.
5 | export type BuilderInterface = Omit;
6 |
7 | export default class Builder {
8 | public spec: Spec;
9 | public node: HTMLElement;
10 |
11 | constructor(spec: Spec, node: HTMLElement) {
12 | this.spec = spec;
13 | this.node = node;
14 |
15 | const nodeId = node.getAttribute('id')!;
16 |
17 | if (nodeId !== null) {
18 | if (spec.nodeIds.has(nodeId)) {
19 | spec.warn({
20 | type: 'attr-value',
21 | attr: 'id',
22 | ruleId: 'duplicate-id',
23 | message: `<${node.tagName.toLowerCase()}> has duplicate id ${JSON.stringify(nodeId)}`,
24 | node,
25 | });
26 | }
27 | spec.nodeIds.add(nodeId);
28 | }
29 | }
30 |
31 | // eslint-disable-next-line @typescript-eslint/no-unused-vars
32 | static async enter(context: Context) {
33 | throw new Error('Builder not implemented');
34 | }
35 | // eslint-disable-next-line @typescript-eslint/no-unused-vars
36 | static exit(context: Context): void {}
37 | static readonly elements: readonly string[] = [];
38 | }
39 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/notes.html:
--------------------------------------------------------------------------------
1 |
2 |
7 |
19 |
20 |
31 | 1. Non-word-chars AOs still link when invoked, like 𝔽(_x_).
32 |
33 |
34 |
7 |
11 |
12 |
20 |
25 |
26 |
30 | 1. Call the dfn algorithm.
31 | 2. Do something great with dfn.
32 | 3. dfn is now awesome.
33 |
34 |
35 |
36 |
40 | 1. Call the dfn algorithm.
41 | 2. Do something great with dfn.
42 | 3. dfn is now awesome.
43 |
44 |
45 |
46 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/step-xrefs.html:
--------------------------------------------------------------------------------
1 |
2 |
8 |
17 | 1. Two a:
18 | 1. Two a i:
19 | 1. Two a i one.
20 | 1. [id="example"] Two a i two.
21 |
22 |
23 |
25 | 1. One.
26 | 1. Two:
27 | 1. [id="to-be-replaced"] Two a.
28 |
29 |
30 |
33 | 1. Two a:
34 | 1. Two a i:
35 | 1. Two a i one.
36 | 1. [id="example"] Two a i two.
37 |
38 |
39 |
42 | 1. Two a i two:
43 | 1. Two a i two a.
44 | 1. Two a i two b.
45 | 1. [id="nested-example"] Two a i two c:
46 | 1. Two a i two c i:
47 | 1. Two a i two c i i:
48 | 1. Two a i two c i i i.
49 | 1. Two a i two c i i ii.
50 |
51 |
52 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/imports.html:
--------------------------------------------------------------------------------
1 |
2 | Foo
10 | `,
11 | {
12 | ruleId: 'valid-tags',
13 | nodeType: 'emu-not-a-thing',
14 | message: 'unknown "emu-" tag "emu-not-a-thing"',
15 | },
16 | );
17 | });
18 |
19 | it('oldid', async () => {
20 | await assertLint(
21 | positioned`
22 |
23 |
25 | `,
26 | {
27 | ruleId: 'valid-tags',
28 | nodeType: 'emu-clause',
29 | message: '"oldid" isn\'t a thing; did you mean "oldids"?',
30 | },
31 | );
32 | });
33 |
34 | it('missing closing tag', async () => {
35 | await assertLint(
36 | positioned`
37 |
38 |
42 | `,
43 | {
44 | ruleId: 'missing-closing-tag',
45 | nodeType: 'p',
46 | message: 'element
7 |
10 |
13 | Multiple examples are numbered similar to notes
14 |
15 |
16 |
17 |
18 |
19 |
21 |
22 |
25 |
26 |
27 |
28 |
29 |
32 |
33 |
36 |
37 |
38 |
39 | Multiple examples are numbered similar to notes
40 |
41 |
42 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/example.html:
--------------------------------------------------------------------------------
1 |
2 | ,
58 | opts?: Options,
59 | token = CancellationToken.none,
60 | ): Promise {
61 | const html = await fetch(path, token);
62 | const dom = utils.htmlToDom(html);
63 | const spec = new Spec(path, fetch, dom, opts ?? {}, /*sourceText*/ html, token);
64 | await spec.build();
65 | return spec;
66 | }
67 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/toc.html:
--------------------------------------------------------------------------------
1 |
2 |
9 |
11 |
13 |
14 |
15 |
16 |
17 |
20 |
23 |
24 |
25 |
26 |
29 |
31 |
32 |
33 |
35 |
36 |
37 |
39 |
40 |
41 |
43 |
45 |
46 |
47 |
49 |
51 |
52 |
53 |
54 |
56 |
57 |
58 |
59 |
60 |
63 |
66 |
67 |
--------------------------------------------------------------------------------
/src/Toc.ts:
--------------------------------------------------------------------------------
1 | import type Spec from './Spec';
2 | import type Clause from './Clause';
3 |
4 | export default class Toc {
5 | /** @internal */ spec: Spec;
6 | constructor(spec: Spec) {
7 | this.spec = spec;
8 | }
9 |
10 | /** @internal */
11 | build(maxDepth: number = Infinity) {
12 | if (this.spec.subclauses.length === 0) {
13 | return;
14 | }
15 |
16 | const html = Toc.build(this.spec, { maxDepth });
17 | const tocContainer = this.spec.doc.createElement('div');
18 | tocContainer.setAttribute('id', 'toc');
19 | tocContainer.innerHTML = ' tags that aren't removed during effect
38 | // propagation on invocations into s so they are rendered.
39 | if (node.hasAttribute('effects') && spec.opts.markEffects) {
40 | const classNames = node
41 | .getAttribute('effects')!
42 | .split(',')
43 | .map(e => e.trim())
44 | .map(e => `e-${e}`)
45 | .join(' ');
46 | const span = spec.doc.createElement('span');
47 | span.setAttribute('class', classNames);
48 | while (node.firstChild) {
49 | span.appendChild(node.firstChild);
50 | }
51 | node.replaceWith(span);
52 | } else {
53 | // Nothing to render, strip it.
54 | node.replaceWith(...node.childNodes);
55 | }
56 | }
57 | }
58 |
--------------------------------------------------------------------------------
/src/lint/rules/if-else-consistency.ts:
--------------------------------------------------------------------------------
1 | import type { Reporter } from '../algorithm-error-reporter-type';
2 | import type { Seq } from '../../expr-parser';
3 | import type { OrderedListItemNode, OrderedListNode } from 'ecmarkdown';
4 | import { offsetToLineAndColumn } from '../../utils';
5 |
6 | const ruleId = 'if-else-consistency';
7 |
8 | /*
9 | Checks that `if`/`else` statements are both single-line or both multi-line.
10 | */
11 | export default function (
12 | report: Reporter,
13 | step: OrderedListItemNode,
14 | algorithmSource: string,
15 | parsedSteps: Map,
16 | parent: OrderedListNode,
17 | ) {
18 | const stepSeq = parsedSteps.get(step);
19 | if (stepSeq == null) {
20 | return;
21 | }
22 | const firstSeqItem = stepSeq.items[0];
23 | if (firstSeqItem?.name !== 'text' || !/^(?:If|Else if)\b/.test(firstSeqItem.contents)) {
24 | return;
25 | }
26 | const idx = parent.contents.indexOf(step);
27 | if (idx >= parent.contents.length - 1) {
28 | return;
29 | }
30 | const nextStep = parent.contents[idx + 1];
31 | const nextSeq = parsedSteps.get(nextStep);
32 | if (nextSeq == null) {
33 | return;
34 | }
35 | const nextFirstSeqitem = nextSeq.items[0];
36 | if (
37 | nextFirstSeqitem?.name !== 'text' ||
38 | !/^(?:Else|Otherwise)\b/.test(nextFirstSeqitem.contents)
39 | ) {
40 | return;
41 | }
42 | if (step.sublist != null && nextStep.sublist == null) {
43 | const location = offsetToLineAndColumn(algorithmSource, nextFirstSeqitem.location.start.offset);
44 | report({
45 | ruleId,
46 | ...location,
47 | message: '"Else" steps should be multiline whenever their corresponding "If" is',
48 | });
49 | } else if (step.sublist == null && nextStep.sublist != null) {
50 | const location = offsetToLineAndColumn(algorithmSource, firstSeqItem.location.start.offset);
51 | report({
52 | ruleId,
53 | ...location,
54 | message: '"If" steps should be multiline whenever their corresponding "Else" is',
55 | });
56 | }
57 | }
58 |
--------------------------------------------------------------------------------
/src/Figure.ts:
--------------------------------------------------------------------------------
1 | import type Spec from './Spec';
2 | import type { Context } from './Context';
3 |
4 | import Builder from './Builder';
5 |
6 | export default class Figure extends Builder {
7 | type: string;
8 | number: number;
9 | id: string | null;
10 | isInformative: boolean;
11 | captionElem: HTMLElement | null;
12 | caption: string;
13 |
14 | static elements = ['EMU-FIGURE', 'EMU-TABLE'];
15 |
16 | constructor(spec: Spec, node: HTMLElement) {
17 | super(spec, node);
18 | this.type = node.nodeName.split('-')[1].toLowerCase();
19 | this.number = ++spec._figureCounts[this.type];
20 | this.id = node.getAttribute('id');
21 |
22 | this.isInformative = node.hasAttribute('informative');
23 | this.captionElem = node.querySelector('emu-caption');
24 | this.caption = this.type.charAt(0).toUpperCase() + this.type.slice(1) + ' ' + this.number;
25 |
26 | if (this.isInformative) {
27 | this.caption += ' (Informative)';
28 | }
29 |
30 | if (this.captionElem) {
31 | this.caption += ': ' + this.captionElem.innerHTML;
32 | } else if (node.getAttribute('caption')) {
33 | this.caption += ': ' + node.getAttribute('caption');
34 | }
35 |
36 | if (this.id) {
37 | spec.biblio.add({
38 | type: this.type as 'table' | 'figure' | 'example' | 'note',
39 | id: this.id,
40 | number: this.number,
41 | caption: this.caption,
42 | });
43 | }
44 | }
45 |
46 | static async enter({ spec, node }: Context) {
47 | const figure = new Figure(spec, node);
48 | if (figure.captionElem && figure.captionElem.parentNode) {
49 | figure.captionElem.parentNode.removeChild(figure.captionElem);
50 | }
51 |
52 | const ele = spec.doc.createElement('figure');
53 |
54 | ele.append(...node.childNodes);
55 | node.append(ele);
56 |
57 | const captionElem = spec.doc.createElement('figcaption');
58 | captionElem.innerHTML = figure.caption;
59 | node.childNodes[0].insertBefore(captionElem, node.childNodes[0].firstChild);
60 | }
61 | }
62 |
--------------------------------------------------------------------------------
/test/baselines/sources/figure.html:
--------------------------------------------------------------------------------
1 |
8 | this is a figure!
9 |
10 |
11 |
12 |
13 | this is a figure!
14 |
15 |
16 |
17 |
18 |
19 |
26 |
27 |
28 |
29 |
30 |
36 |
37 |
38 |
39 | This is the caption
40 | this is a figure!
41 |
42 |
43 |
44 | This is a table
45 |
46 |
47 |
54 |
55 |
56 |
57 | This is a second table
58 |
59 |
65 |
66 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/emd-in-grammar.html:
--------------------------------------------------------------------------------
1 |
2 | [' + this.params + '] ';
56 | }
57 |
58 | if (this.optional) {
59 | modifiers += 'opt ';
60 | }
61 |
62 | if (modifiers.length > 0) {
63 | const el = this.spec.doc.createElement('emu-mods');
64 | el.innerHTML = modifiers;
65 | this.node.appendChild(el);
66 | }
67 | }
68 | }
69 |
--------------------------------------------------------------------------------
/boilerplate/standard-copyright.html:
--------------------------------------------------------------------------------
1 |
22 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/code.html:
--------------------------------------------------------------------------------
1 |
2 |
22 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/multipage.html/multipage/third.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
11 |
22 |
25 |
28 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/boilerplate-all.html:
--------------------------------------------------------------------------------
1 |
2 | test title!
15 |
26 |
--------------------------------------------------------------------------------
/src/lint/collect-tag-diagnostics.ts:
--------------------------------------------------------------------------------
1 | import type { default as Spec, Warning } from '../Spec';
2 |
3 | const knownEmuTags = new Set([
4 | 'emu-meta',
5 | 'emu-import',
6 | 'emu-example',
7 | 'emu-intro',
8 | 'emu-clause',
9 | 'emu-annex',
10 | 'emu-biblio',
11 | 'emu-xref',
12 | 'emu-prodref',
13 | 'emu-not-ref',
14 | 'emu-note',
15 | 'emu-eqn',
16 | 'emu-table',
17 | 'emu-figure',
18 | 'emu-caption',
19 | 'emu-grammar',
20 | 'emu-alg',
21 | 'emu-var',
22 | 'emu-val',
23 | 'emu-production',
24 | 'emu-rhs',
25 | 'emu-nt',
26 | 'emu-t',
27 | 'emu-gann',
28 | 'emu-gprose',
29 | 'emu-gmod',
30 | ]);
31 |
32 | // https://html.spec.whatwg.org/multipage/syntax.html#void-elements
33 | const voidElements = new Set([
34 | 'area',
35 | 'base',
36 | 'br',
37 | 'col',
38 | 'embed',
39 | 'hr',
40 | 'img',
41 | 'input',
42 | 'link',
43 | 'meta',
44 | 'param',
45 | 'source',
46 | 'track',
47 | 'wbr',
48 | ]);
49 |
50 | export function collectTagDiagnostics(
51 | report: (e: Warning) => void,
52 | spec: Spec,
53 | document: Document,
54 | ) {
55 | const lintWalker = document.createTreeWalker(document.body, 1 /* elements */);
56 | function visit() {
57 | const node: Element = lintWalker.currentNode as Element;
58 | const name = node.tagName.toLowerCase();
59 |
60 | if (name.startsWith('emu-') && !knownEmuTags.has(name)) {
61 | report({
62 | type: 'node',
63 | ruleId: 'valid-tags',
64 | message: `unknown "emu-" tag "${name}"`,
65 | node,
66 | });
67 | }
68 |
69 | if (node.hasAttribute('oldid')) {
70 | report({
71 | type: 'attr',
72 | attr: 'oldid',
73 | ruleId: 'valid-tags',
74 | message: `"oldid" isn't a thing; did you mean "oldids"?`,
75 | node,
76 | });
77 | }
78 |
79 | if (!voidElements.has(name)) {
80 | const location = spec.locate(node);
81 | if (location != null && location.endTag == null) {
82 | report({
83 | type: 'node',
84 | ruleId: 'missing-closing-tag',
85 | message: `element <${name}> is missing its closing tag`,
86 | node,
87 | });
88 | }
89 | }
90 |
91 | const firstChild = lintWalker.firstChild();
92 | if (firstChild) {
93 | while (true) {
94 | visit();
95 | const next = lintWalker.nextSibling();
96 | if (!next) break;
97 | }
98 | lintWalker.parentNode();
99 | }
100 | }
101 | visit();
102 | }
103 |
--------------------------------------------------------------------------------
/test/baselines/sources/namespaces.html:
--------------------------------------------------------------------------------
1 |
7 |
9 | Foo ::
10 | `bar` MainProd `baz`
11 |
12 |
13 |
14 |
16 | Foo ::
17 | `bar` MainProd `baz`
18 |
19 | MainProd ::
20 | Foo
21 |
22 |
23 |
26 | Foo ::
27 | `bar` MainProd `baz`
28 |
29 |
30 |
31 |
32 |
33 |
35 |
36 |
40 |
41 |
42 |
44 | Foo ::
45 | `bar` MainProd `baz`
46 |
47 |
48 |
49 |
50 |
52 |
53 |
54 |
55 |
56 |
59 |
60 |
62 | 1. Let _x_ be the result of SomeAlg.
63 |
64 |
65 |
66 |
67 |
70 |
72 |
73 | MainProd ::
74 | Foo
75 |
76 |
78 |
--------------------------------------------------------------------------------
/src/formatter/header.ts:
--------------------------------------------------------------------------------
1 | import { printSimpleParamList } from '../header-parser';
2 | import type { Param, ParsedHeaderOrFailure } from '../header-parser';
3 | import { LineBuilder } from './line-builder';
4 |
5 | function printTypedParam(param: Param, optional: boolean) {
6 | let p = (optional ? 'optional ' : '') + param.name + ': ' + (param.type ?? 'unknown') + ',';
7 | if (param.wrappingTag) {
8 | p = `<${param.wrappingTag}>${p}`;
9 | }
10 | return p;
11 | }
12 |
13 | function ensureUnderscores(param: Param) {
14 | if (!/^[a-zA-Z0-9]+$/.test(param.name)) {
15 | return param;
16 | }
17 | return {
18 | ...param,
19 | name: '_' + param.name + '_',
20 | };
21 | }
22 |
23 | export function printHeader(
24 | parseResult: ParsedHeaderOrFailure & { type: 'single-line' | 'multi-line' },
25 | clauseType: string | null,
26 | indent: number,
27 | ): LineBuilder {
28 | /* eslint-disable prefer-const */
29 | let {
30 | type,
31 | wrappingTag,
32 | prefix,
33 | name,
34 | params,
35 | optionalParams,
36 | returnType,
37 | // errors is already handled
38 | } = parseResult;
39 | /* eslint-enable prefer-const */
40 |
41 | const multiline = type === 'multi-line' && (params.length > 0 || optionalParams.length > 0);
42 |
43 | const result = new LineBuilder(indent);
44 | if (multiline) {
45 | result.firstLineIsPartial = false;
46 | }
47 | if (wrappingTag !== null) {
48 | result.appendText(`<${wrappingTag}>`);
49 | }
50 | if (prefix !== null) {
51 | result.appendText(prefix + ' ');
52 | }
53 | result.appendText(name);
54 |
55 | params = params.map(ensureUnderscores);
56 | optionalParams = optionalParams.map(ensureUnderscores);
57 |
58 | if (
59 | clauseType === 'sdo' &&
60 | params.length === 0 &&
61 | optionalParams.length === 0 &&
62 | returnType === null
63 | ) {
64 | // do not print a parameter list
65 | } else if (!multiline) {
66 | result.appendText(' ' + printSimpleParamList(params, optionalParams));
67 | } else {
68 | result.appendText(' (');
69 | ++result.indent;
70 | for (const param of params) {
71 | result.appendLine(printTypedParam(param, false));
72 | }
73 | for (const param of optionalParams) {
74 | result.appendLine(printTypedParam(param, true));
75 | }
76 | --result.indent;
77 | result.appendText(')');
78 | }
79 | if (returnType !== null && returnType !== '') {
80 | result.appendText(': ' + returnType);
81 | }
82 | if (wrappingTag !== null) {
83 | result.appendText(``);
84 | }
85 | if (multiline) {
86 | result.linebreak();
87 | }
88 |
89 | return result;
90 | }
91 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/duplicate-ids.html:
--------------------------------------------------------------------------------
1 |
2 | ℝ (_y_)`)
20 | const isText = [...sup.childNodes].every(node => node.nodeType === 3);
21 | const text = sup.textContent;
22 | if (isText) {
23 | if (!/^[0-9. 𝔽ℝℤ()=*×/÷±+\u2212-]+$/u.test(text)) {
24 | return;
25 | }
26 | } else {
27 | if (sup.querySelector('*:not(var, emu-xref, :scope emu-xref a)')) {
28 | return;
29 | }
30 | }
31 |
32 | let prefix = '**';
33 | let suffix = '';
34 |
35 | // Add wrapping parentheses unless they are already present
36 | // or this is a simple (possibly signed) integer or single-variable exponent.
37 | const skipParens =
38 | /^[±+\u2212-]?(?:[0-9]+|\p{ID_Start}\p{ID_Continue}*)$/u.test(text) ||
39 | // Split on parentheses and remember them; the resulting parts must
40 | // start and end empty (i.e., with open/close parentheses)
41 | // and increase depth to 1 only at the first parenthesis
42 | // to e.g. wrap `(a+1)*(b+1)` but not `((a+1)*(b+1))`.
43 | text
44 | .trim()
45 | .split(/([()])/g)
46 | .reduce((depth, s, i, parts) => {
47 | if (s === '(') {
48 | return depth > 0 || i === 1 ? depth + 1 : NaN;
49 | } else if (s === ')') {
50 | return depth > 0 ? depth - 1 : NaN;
51 | } else if (s === '' || (i > 0 && i < parts.length - 1)) {
52 | return depth;
53 | }
54 | return NaN;
55 | }, 0) === 0;
56 | if (!skipParens) {
57 | prefix += '(';
58 | suffix += ')';
59 | }
60 |
61 | sup.insertAdjacentHTML('beforebegin', ``);
62 | if (suffix) {
63 | sup.insertAdjacentHTML('afterend', ``);
64 | }
65 | }
66 |
67 | document.addEventListener('DOMContentLoaded', () => {
68 | document.querySelectorAll('sup:not(.text)').forEach(sup => {
69 | makeExponentPlainTextSafe(sup);
70 | });
71 | });
72 |
--------------------------------------------------------------------------------
/src/Note.ts:
--------------------------------------------------------------------------------
1 | import type Spec from './Spec';
2 | import type Clause from './Clause';
3 | import type { Context } from './Context';
4 |
5 | import Builder from './Builder';
6 |
7 | export default class Note extends Builder {
8 | /** @internal */ clause: Clause;
9 | /** @internal */ id?: string;
10 | /** @internal */ type: string; // normal, editor
11 | static readonly elements = ['EMU-NOTE'] as const;
12 |
13 | constructor(spec: Spec, node: HTMLElement, clause: Clause) {
14 | super(spec, node);
15 | this.clause = clause;
16 | if (this.node.hasAttribute('type')) {
17 | this.type = this.node.getAttribute('type') as string;
18 | } else {
19 | this.type = 'normal';
20 | }
21 |
22 | if (this.node.hasAttribute('id')) {
23 | this.id = node.getAttribute('id')!;
24 | }
25 | }
26 |
27 | static async enter({ spec, node, clauseStack }: Context) {
28 | const clause = clauseStack[clauseStack.length - 1];
29 |
30 | // TODO reconsider
31 | if (!clause) return; // do nothing with top-level note
32 |
33 | const note = new Note(spec, node, clause);
34 | if (note.type === 'editor') {
35 | clause.editorNotes.push(note);
36 | } else {
37 | clause.notes.push(note);
38 | }
39 | }
40 |
41 | build(number?: number) {
42 | if (this.id) {
43 | // biblio is added during the build step as we don't know
44 | // the number at build time. Could probably be fixed.
45 | this.spec.biblio.add({
46 | type: 'note',
47 | id: this.id,
48 | number: number || 1,
49 | clauseId: this.clause.id,
50 | });
51 | }
52 |
53 | const noteContentContainer = this.spec.doc.createElement('div');
54 | noteContentContainer.setAttribute('class', 'note-contents');
55 |
56 | while (this.node.childNodes.length > 0) {
57 | noteContentContainer.appendChild(this.node.childNodes[0]);
58 | }
59 |
60 | this.node.appendChild(noteContentContainer);
61 |
62 | const noteSpan = this.spec.doc.createElement('span');
63 | noteSpan.setAttribute('class', 'note');
64 | let label = '';
65 |
66 | if (this.type === 'normal') {
67 | label = 'Note';
68 | } else if (this.type === 'editor') {
69 | label = "Editor's Note";
70 | } else {
71 | this.spec.warn({
72 | type: 'attr-value',
73 | attr: 'type',
74 | ruleId: 'invalid-note',
75 | message: `unknown note type ${JSON.stringify(this.type)}`,
76 | node: this.node,
77 | });
78 | }
79 |
80 | if (number !== undefined) {
81 | label += ' ' + number;
82 | }
83 |
84 | if (this.id) {
85 | // create link to note
86 | noteSpan.innerHTML = `${label}`;
87 | } else {
88 | // just text
89 | noteSpan.textContent = label;
90 | }
91 |
92 | this.node.insertBefore(noteSpan, noteContentContainer);
93 | }
94 | }
95 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/optional-parts.html:
--------------------------------------------------------------------------------
1 |
2 | test title!
15 |
20 |
--------------------------------------------------------------------------------
/src/args.ts:
--------------------------------------------------------------------------------
1 | export const options = [
2 | {
3 | name: 'help',
4 | alias: 'h',
5 | type: Boolean,
6 | description: 'Display this help message',
7 | },
8 | {
9 | name: 'watch',
10 | alias: 'w',
11 | type: Boolean,
12 | description: 'Rebuild when files change',
13 | },
14 | {
15 | name: 'load-biblio',
16 | type: String,
17 | lazyMultiple: true,
18 | typeLabel: '{underline path}',
19 | description:
20 | 'An external biblio.json to load; either a path prefixed with "." or "./", or a package name of an installed package that exports a biblio',
21 | },
22 | {
23 | name: 'write-biblio',
24 | type: String,
25 | typeLabel: '{underline file}',
26 | description: 'Path to where the biblio.json should be written',
27 | },
28 | {
29 | name: 'assets',
30 | type: String,
31 | typeLabel: 'none|inline|external',
32 | description:
33 | 'Omit assets, inline them, or add them as external. Default: inline, unless --multipage or --assets-dir are specified, in which case external.',
34 | },
35 | {
36 | name: 'assets-dir',
37 | type: String,
38 | typeLabel: '{underline dir}',
39 | description:
40 | 'The directory in which to place generated assets when using --assets=external. Implies --assets=external. Defaults to [outfile]/assets.',
41 | },
42 | {
43 | name: 'no-toc',
44 | type: Boolean,
45 | description: "Don't include the table of contents",
46 | },
47 | {
48 | name: 'printable',
49 | type: Boolean,
50 | description: 'Make the output suitable for printing',
51 | },
52 | {
53 | name: 'mark-effects',
54 | type: Boolean,
55 | description: 'Render markers for effects like "user code" [UC]',
56 | },
57 | {
58 | name: 'lint-spec',
59 | type: Boolean,
60 | description: 'Enforce some style and correctness checks',
61 | },
62 | {
63 | name: 'error-formatter',
64 | type: String,
65 | typeLabel: '{underline formatter}',
66 | defaultValue: 'eslint-formatter-codeframe',
67 | description:
68 | 'The formatter for warnings and errors; either a path prefixed with "." or "./", or package name, of an installed eslint compatible formatter (default: eslint-formatter-codeframe)',
69 | },
70 | {
71 | name: 'max-clause-depth',
72 | type: Number,
73 | description:
74 | 'The maximum nesting depth for clauses; exceeding this will cause a warning. Defaults to no limit.',
75 | },
76 | {
77 | name: 'multipage',
78 | type: Boolean,
79 | description: 'Generate a multipage version of the spec. Implies --assets=external.',
80 | },
81 | {
82 | name: 'strict',
83 | type: Boolean,
84 | description: 'Exit with an error if there are warnings. Cannot be used with --watch.',
85 | },
86 | {
87 | name: 'verbose',
88 | type: Boolean,
89 | description: 'Display document build progress',
90 | },
91 | {
92 | name: 'version',
93 | alias: 'v',
94 | type: Boolean,
95 | description: 'Display version info',
96 | },
97 | {
98 | name: 'files',
99 | type: String,
100 | multiple: true,
101 | defaultOption: true,
102 | },
103 |
104 | // removed; still defined here so we can give better errors
105 | {
106 | name: 'css-out',
107 | type: String,
108 | },
109 | {
110 | name: 'js-out',
111 | type: String,
112 | },
113 | {
114 | name: 'old-toc',
115 | type: Boolean,
116 | },
117 | ] as const;
118 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/max-clause-depth.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | test title!
15 |
26 |
--------------------------------------------------------------------------------
/src/arg-parser.ts:
--------------------------------------------------------------------------------
1 | import type { OptionDefinition } from 'command-line-usage';
2 | import * as commandLineArgs from 'command-line-args';
3 |
4 | function fail(msg: string): never {
5 | console.error(msg);
6 | process.exit(1);
7 | }
8 |
9 | export function parse(
10 | options: T,
11 | printHelp: () => void,
12 | ): ArgsFromOptions {
13 | const def = options.find(o => o.defaultOption);
14 | if (!def?.multiple) {
15 | // this is just so I don't have to think about how to handle `--` in other cases
16 | // not an inherent limitation
17 | throw new Error('ecmarkup arg-parser requires a default option for now');
18 | }
19 |
20 | const argv = process.argv.slice(2);
21 |
22 | let notParsed: string[] = [];
23 | const dashDashIndex = argv.indexOf('--');
24 | if (dashDashIndex !== -1) {
25 | notParsed = argv.splice(dashDashIndex + 1);
26 | argv.pop();
27 | }
28 |
29 | let args: ArgsFromOptions;
30 | try {
31 | // @ts-ignore the types are wrong about mutability
32 | args = commandLineArgs(options, { argv });
33 | } catch (e: any) {
34 | if (e?.name === 'UNKNOWN_OPTION') {
35 | fail(`Unknown option ${e.optionName}`);
36 | }
37 | throw e;
38 | }
39 |
40 | // @ts-ignore it's fine
41 | args[def.name] = (args[def.name] || []).concat(notParsed);
42 |
43 | if (
44 | (args as unknown as { help?: boolean }).help ||
45 | (argv.length === 0 && notParsed.length === 0)
46 | ) {
47 | printHelp();
48 | process.exit(0);
49 | }
50 |
51 | return args;
52 | }
53 |
54 | // here follows some typescript shenanigans for inferring the type of of the parsed arguments from the argument specification
55 |
56 | type Multiples = T extends unknown
57 | ? Extract
58 | : never;
59 | type Defaulted = T extends unknown ? Extract : never;
60 | type Optional = T extends unknown ? Exclude | Defaulted> : never;
61 |
62 | type ReturnTypeOrNull = T extends (...args: unknown[]) => unknown ? ReturnType : null;
63 | // prettier-ignore
64 | type ArgTypeForKey =
65 | ReturnTypeOrNull['type']>;
66 |
67 | // spread is from https://stackoverflow.com/a/49683575
68 | type OptionalPropertyNames = {
69 | [K in keyof T]-?: {} extends { [P in K]: T[K] } ? K : never;
70 | }[keyof T];
71 |
72 | type SpreadProperties = {
73 | [P in K]: L[P] | Exclude;
74 | };
75 |
76 | type Id = T extends infer U ? { [K in keyof U]: U[K] } : never;
77 |
78 | type SpreadTwo = Id<
79 | Pick> &
80 | Pick>> &
81 | Pick, keyof L>> &
82 | SpreadProperties & keyof L>
83 | >;
84 |
85 | type Spread = A extends [infer L, ...infer R]
86 | ? SpreadTwo>
87 | : unknown;
88 |
89 | // this type is wrong: if you specify the flag but omit the argument you get `null`, not the default value
90 | // you should check those manually
91 | type ArgsFromOptions = Spread<
92 | [
93 | {
94 | [key in Multiples['name']]: ArgTypeForKey[];
95 | },
96 | {
97 | [key in Defaulted['name']]: ArgTypeForKey;
98 | },
99 | {
100 | [key in Optional['name']]?: ArgTypeForKey;
101 | },
102 | ]
103 | >;
104 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/algorithms.html:
--------------------------------------------------------------------------------
1 |
2 |
6 | copyright: false 7 | assets: none 8 | maxClauseDepth: 2 9 |10 | 11 |
One
13 |Two
15 | 16 |Three
18 |four
20 |Three Again
24 |Four Again
26 |Two Again
31 |One Again
35 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
17 |
18 |
--------------------------------------------------------------------------------
/test/baselines/sources/eqn.html:
--------------------------------------------------------------------------------
1 |
2 | 1 ecmarkdown basics
15 |ecmarkdown like v works before and after comments v.
16 |3 | toc: false 4 | copyright: false 5 | assets: none 6 |7 |
Header
9 |Can refer to eqns inside paragraph text via autolinking: DateValue.
10 |Inline eqns are a thing, for example
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 | 7 |
Test Clause
9 |Increases indentaion level.
10 |
11 | global1.Zone.current; // succeeds
12 | global2.Zone.current; // throws: currentRealm = realm1; thisRealm = functionRealm = realm2
13 |
14 | const getter1 = Object.getOwnPropertyDescriptor(global1.Zone, "current").get;
15 | const getter2 = Object.getOwnPropertyDescriptor(global2.Zone, "current").get;
16 |
17 | getter1.call(global2.Zone); // throws: currentRealm = functionRealm = realm1; thisRealm = realm2
18 | getter2.call(global1.Zone); // throws: currentRealm = thisRealm = realm1; functionRealm = realm2
19 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
2 | 3 |The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
4 | 5 |THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
6 | -------------------------------------------------------------------------------- /test/clauseIds.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const assert = require('assert'); 4 | const sectionNums = require('../lib/clauseNums').default; 5 | 6 | describe('clause id generation', () => { 7 | let iter; 8 | 9 | beforeEach(() => { 10 | iter = sectionNums({ opts: {} }); 11 | }); 12 | 13 | specify('generating clause ids', () => { 14 | const CLAUSE = { nodeName: 'EMU-CLAUSE', hasAttribute: () => false }; 15 | const ANNEX = { nodeName: 'EMU-ANNEX', hasAttribute: () => false }; 16 | assert.strictEqual(iter.next([], CLAUSE), '1'); 17 | assert.strictEqual(iter.next([{}], CLAUSE), '1.1'); 18 | assert.strictEqual(iter.next([{}], CLAUSE), '1.2'); 19 | assert.strictEqual(iter.next([{}, {}], CLAUSE), '1.2.1'); 20 | assert.strictEqual(iter.next([], CLAUSE), '2'); 21 | assert.strictEqual(iter.next([], ANNEX), 'A'); 22 | assert.strictEqual(iter.next([{}], ANNEX), 'A.1'); 23 | assert.strictEqual(iter.next([{}], ANNEX), 'A.2'); 24 | assert.strictEqual(iter.next([{}, {}], ANNEX), 'A.2.1'); 25 | assert.strictEqual(iter.next([], ANNEX), 'B'); 26 | }); 27 | }); 28 | -------------------------------------------------------------------------------- /test/baselines/generated-reference/title.html: -------------------------------------------------------------------------------- 1 | 2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
Draft 1 / September 26, 2015
test title!
13 | 14 |Some body content
15 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
Draft ECMA-000
Draft 1 / September 26, 2015
test title!
13 | 14 |Some body content
15 |3 | toc: false 4 | copyright: false 5 | assets: none 6 |7 | 8 |
Can also have inline productions like
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
15 | A :: one of a b c d e f
17 |
--------------------------------------------------------------------------------
/src/lint/rules/step-attributes.ts:
--------------------------------------------------------------------------------
1 | import type { OrderedListItemNode } from 'ecmarkdown';
2 | import type { Reporter } from '../algorithm-error-reporter-type';
3 |
4 | import { SPECIAL_KINDS } from '../../Clause';
5 |
6 | const ruleId = 'step-attribute';
7 |
8 | const KNOWN_ATTRIBUTES = ['id', 'fence-effects', 'declared', ...SPECIAL_KINDS];
9 |
10 | /*
11 | Checks for unknown attributes on steps.
12 | */
13 | export default function (report: Reporter, node: OrderedListItemNode) {
14 | for (const attr of node.attrs) {
15 | if (!KNOWN_ATTRIBUTES.includes(attr.key)) {
16 | report({
17 | ruleId,
18 | message: `unknown step attribute ${JSON.stringify(attr.key)}`,
19 | line: attr.location.start.line,
20 | column: attr.location.start.column,
21 | });
22 | } else if (attr.value !== '' && SPECIAL_KINDS.includes(attr.key)) {
23 | report({
24 | ruleId,
25 | message: `step attribute ${JSON.stringify(attr.key)} should not have a value`,
26 | line: attr.location.start.line,
27 | column: attr.location.start.column + attr.key.length + 2, // ="
28 | });
29 | }
30 | }
31 | }
32 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2014 Brian Terlson and contributors
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/test/baselines/sources/algorithms.html:
--------------------------------------------------------------------------------
1 | 2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Internal Function
23 |Refs
26 |Can refer to functions in prose, eg. Internal.
27 |Internal works if Internal is in the middle of the prose.
28 |Don't autolink references inside square brackets, eg: [[Internal]]. 29 | Likewise, percent things: %%Internal%%. 30 | Likewise, mentions of Internal.foo.
31 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
19 |
--------------------------------------------------------------------------------
/test/baselines/sources/optional-parts.html:
--------------------------------------------------------------------------------
1 | 1 blah
15 |U+200C (ZERO WIDTH NON-JOINER) is abbreviated "<ZWNJ>"
16 |<b>also doesn't escape when
Escpaing inside xref is preserved:
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Definitions of Normative Optional etc
10 |Normative Optional is a defined term, as is Legacy. For comparison, "Deprecated" is not.
11 |Example Normative Optional Clause
15 |This clause is normative optional.
16 |Example Legacy Clause
20 |This clause is legacy.
21 |Example algorithm with marked steps.
25 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 | This is a note. Since it is outside a clause it is unstyled.
14 |
15 |
16 | Note
19 |
20 |
21 | Note 1
23 | Note 2
24 |
25 |
26 |
--------------------------------------------------------------------------------
/test/baselines/sources/autolinking.html:
--------------------------------------------------------------------------------
1 | 1 This
17 | 18 |This is note 1, but since it is the only note, it is not numbered.
1.1 That
22 |This is note 1, should be numbered
This is note 2, should also be numbered
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Autolinking
8 |Type, type, Type(), type()
9 |%Array% and %ArrayPrototype% from ES6 should link (but not %Arrayprototype%).
10 | 11 |Lowercase
12 |strict mode
13 |%Percent%
14 |extra spaces
15 |Await
16 |Variants
17 |Autolinking 2
21 |lowercase should not autolink. But Lowercase should. But not LowerCase.
22 |Strict mode shoud link. But Strict Mode should not. Also, strict 23 | mode can be wrapped across lines and contain extra whitespace.
24 |extra spaces in a dfn should be narrowed to one space.
25 |%Percent% should autolink.
26 |Vars to dfns should be vars not dfns: _Lowercase_.
27 |Also, no autolinks in anchors: Lowercase.
28 |Similarly, no autolinks for [Await].
29 |Variants like vOne and vTwo should autolink, including when capitalized as in VOne.
30 |%Array% and %ArrayPrototype% outside of clauses is ok.
35 | -------------------------------------------------------------------------------- /test/baselines/generated-reference/oldids.html: -------------------------------------------------------------------------------- 1 | 2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
17 |
19 |
20 | Table 1
21 | Note
26 |
27 |
--------------------------------------------------------------------------------
/test/baselines/sources/dfn.html:
--------------------------------------------------------------------------------
1 | 1 c1
15 |This is some content and such.
16 |1.1 c1.1
18 |
24 |
This is a note!
25 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Intro
8 |Forward references to dfn work.
9 |Also terms from ES6 are auto-linked: Lexical Environment, Completion, etc.
10 |dfn
13 | 14 |The term dfn means the dfn tag. Other mentions of dfn in this clause should not be auto-linked.
15 | 16 |Terms with ids are called id dfns. Since this dfn has an id, other occurences 17 | of id dfns may autolink.
18 | 19 |dfn subclause
21 | 22 |Dfn should be auto-linked here as well. The linking of dfn is case insensitive. But the header shouldn't auto-link.
23 |Id dfns should link to #identifiers.
24 |Also terms are auto-linked in algorithms. But not naked abstract ops!
27 | 28 | 29 |dfn autolink
37 | 38 | 39 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
15 |
23 |
--------------------------------------------------------------------------------
/test/baselines/sources/algorithm-replacements.html:
--------------------------------------------------------------------------------
1 | 1 Title
16 | 17 |You can refer to a step before it occurs in text, like step
You can refer to it after as well, like step
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 | 7 |
Title
9 | 10 |You can refer to a step in a replacement algorithm before it occurs in text, like step
You can similarly refer to a step in a replacement algorithm which itself which replaces a step in a replacement algorithm, like step
An algorithm can come before the step it replaces.
15 | 16 |This is our sample algorithm.
24 |An algorithm can also come after the step it replaces.
31 | 32 |You can even replace steps in replacement algorithms.
40 | 41 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
19 |
22 | A : b
24 |
26 |
27 |
28 |
29 |
30 |
32 |
33 |
34 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/duplicate-productions.html:
--------------------------------------------------------------------------------
1 |
2 | 1 Header
15 |text
16 |code
1.1 Import 3
20 | wtf?? 21 |2 Import 2
31 |- Ensure we can auto-link to imported aoids:
Baz ()
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 | Prod :
15 | GMD ::
16 | Test
17 | bar
18 |
19 |
20 | Prod :
24 | GMD ::
25 | Test
26 | bar
27 |
28 |
29 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/nonterminal-used-before-definition.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
16 | Example : foo
18 |
21 |
22 |
23 |
26 | Example : foo
28 |
30 |
--------------------------------------------------------------------------------
/test/lint-tags.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | let { assertLint, assertLintFree, positioned, lintLocationMarker: M } = require('./utils.js');
4 |
5 | describe('tags', () => {
6 | it('unknown "emu-" tags', async () => {
7 | await assertLint(
8 | positioned`
9 | ${M}1 Example SDO
15 |- Return
false .
2 Example Grammar
24 |Syntax
25 |Example
24 |Example
39 | ${M}some text 40 |
some other text
41 | is missing its closing tag',
47 | },
48 | );
49 | });
50 |
51 | it('negative', async () => {
52 | await assertLintFree(`
53 | some text some other textExample
55 |
57 |
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
A
8 | 9 |Sub A
11 | 12 |Section A: Extras
20 || Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
Section A: Extras
30 | 31 || Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
15 | This is an example.
16 |
17 |
18 |
19 | Example (Informative)
21 | Examples inside clauses are numbered and have captions. Captions are optional.
22 |
25 | Example 1 (Informative): An example
27 | Multiple examples are numbered similar to notes
28 | Example 2 (Informative): A second example
31 | So this becomes example 2.
32 |
34 |
35 |
36 |
--------------------------------------------------------------------------------
/src/Dfn.ts:
--------------------------------------------------------------------------------
1 | import type { PartialBiblioEntry, TermBiblioEntry } from './Biblio';
2 | import { getKeys } from './Biblio';
3 | import type { Context } from './Context';
4 |
5 | import Builder from './Builder';
6 |
7 | export default class Dfn extends Builder {
8 | static async enter({ spec, node, clauseStack }: Context) {
9 | if (!node.hasAttribute('tabindex')) {
10 | node.setAttribute('tabindex', '-1');
11 | }
12 |
13 | const parentClause = clauseStack[clauseStack.length - 1];
14 | if (!parentClause) return;
15 |
16 | const entry: PartialBiblioEntry = {
17 | type: 'term',
18 | term: node.textContent!,
19 | refId: parentClause.id,
20 | };
21 |
22 | if (node.hasAttribute('id')) {
23 | entry.id = node.id;
24 | }
25 |
26 | if (node.hasAttribute('variants')) {
27 | entry.variants = node
28 | .getAttribute('variants')!
29 | .split(',')
30 | .map(v => v.trim());
31 | }
32 |
33 | const keys = getKeys(entry as TermBiblioEntry);
34 | const existing = spec.biblio.keysForNamespace(parentClause.namespace);
35 | for (const [index, key] of keys.entries()) {
36 | if (keys.indexOf(key) !== index) {
37 | spec.warn({
38 | type: 'node',
39 | node,
40 | ruleId: 'duplicate-definition',
41 | message: `${JSON.stringify(key)} is defined more than once in this definition`,
42 | });
43 | }
44 | if (existing.has(key)) {
45 | spec.warn({
46 | type: 'node',
47 | node,
48 | ruleId: 'duplicate-definition',
49 | message: `duplicate definition ${JSON.stringify(key)}`,
50 | });
51 | }
52 | }
53 |
54 | spec.biblio.add(entry, parentClause.namespace);
55 | }
56 |
57 | static elements = ['DFN'];
58 | }
59 |
--------------------------------------------------------------------------------
/src/ecmarkup.ts:
--------------------------------------------------------------------------------
1 | import type { BiblioEntry, ExportedBiblio } from './Biblio';
2 |
3 | import Spec from './Spec';
4 | import * as utils from './utils';
5 | import { CancellationToken } from 'prex';
6 |
7 | export type { Spec, BiblioEntry };
8 |
9 | export class Boilerplate {
10 | address?: string;
11 | copyright?: string;
12 | license?: string;
13 | }
14 |
15 | export type EcmarkupError = {
16 | ruleId: string;
17 | message: string;
18 | file?: string;
19 | source?: string;
20 | line?: number;
21 | column?: number;
22 | nodeType?: string;
23 | };
24 |
25 | export interface Options {
26 | status?: 'proposal' | 'draft' | 'standard';
27 | version?: string;
28 | title?: string;
29 | shortname?: string;
30 | description?: string;
31 | stage?: string | null;
32 | copyright?: boolean;
33 | date?: Date;
34 | location?: string;
35 | maxClauseDepth?: number;
36 | multipage?: boolean;
37 | extraBiblios?: ExportedBiblio[];
38 | contributors?: string;
39 | toc?: boolean;
40 | oldToc?: boolean;
41 | printable?: boolean;
42 | markEffects?: boolean;
43 | lintSpec?: boolean;
44 | cssOut?: never;
45 | jsOut?: never;
46 | assets?: 'none' | 'inline' | 'external';
47 | assetsDir?: string;
48 | outfile?: string;
49 | boilerplate?: Boilerplate;
50 | log?: (msg: string) => void;
51 | warn?: (err: EcmarkupError) => void;
52 | committee?: number;
53 | }
54 |
55 | export async function build(
56 | path: string,
57 | fetch: (path: string, token: CancellationToken) => PromiseLikeExamples outside of clauses aren't processed specially.
14 |1 Example Section
20 |1.1 Example Subclause
26 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
16 |
17 |
18 |
21 |
--------------------------------------------------------------------------------
/test/baselines/sources/clauses.html:
--------------------------------------------------------------------------------
1 | 1 Example Link Header
19 |Example clause contents.
20 |2 | printable: true 3 | title: Test Doc 4 | shortname: Test 5 | copyright: false 6 | assets: none 7 |8 |
Intro
10 |Sub Intro
12 |Clause Foo(_a_, _b_)
18 | 19 |Sub Clause
21 | 22 |Explicit number
27 | 28 |Automatic number inside explicit number
30 |Nested explicit number
34 |Automatic number after explicit number
38 |Multi-step explicit numbers
42 |Multi-step explicit numbers
44 |Automatic number after explicit number
48 |Nested clause after explicit multi-step number
50 |Increasing multi-step explicit numbers
55 |Annex
61 | 62 |Sub-annex
64 | 65 |Contents
' + html; 20 | const intro = this.spec.doc.querySelector('emu-intro, emu-clause, emu-annex'); 21 | if (intro && intro.parentNode) { 22 | intro.parentNode.insertBefore(tocContainer, intro); 23 | } 24 | 25 | const bodyClass = this.spec.doc.body.getAttribute('class') || ''; 26 | this.spec.doc.body.setAttribute('class', bodyClass + ' oldtoc'); 27 | } 28 | 29 | static build(level: Spec | Clause, { maxDepth = Infinity, expandy = false } = {}) { 30 | if (maxDepth <= 0) { 31 | return ''; 32 | } 33 | 34 | let html = '- ';
35 |
36 | level.subclauses.forEach(sub => {
37 | html += '
- '; 38 | 39 | if (expandy) { 40 | if (sub.subclauses.length > 0) { 41 | html += '+'; 42 | } else { 43 | html += ''; 44 | } 45 | } 46 | 47 | html += `${sub.getSecnumHTML()}${shorten(sub.titleHTML)}`; 48 | if (sub.subclauses.length > 0) html += Toc.build(sub, { maxDepth: maxDepth - 1, expandy }); 49 | html += ' '; 50 | }); 51 | 52 | html += '
2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 | 7 |
| Column 1 | Column 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Column 1 | Column 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
15 |
17 | Foo ::
18 | Bar
19 | but only if the AbstractOperation of Bar is ≤ variable
20 |
21 |
22 |
23 | Bar :: example
25 |
28 |
30 | Bar :: example
32 |
35 |
36 |
--------------------------------------------------------------------------------
/.eslintrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "root": true,
3 | "extends": [
4 | "eslint:recommended",
5 | "prettier"
6 | ],
7 | "plugins": [
8 | "prettier",
9 | "@typescript-eslint"
10 | ],
11 | "env": {
12 | "node": true,
13 | "es6": true
14 | },
15 | "parser": "@typescript-eslint/parser",
16 | "parserOptions": {
17 | "sourceType": "script",
18 | "ecmaVersion": 2020
19 | },
20 | "overrides": [
21 | {
22 | "files": ["js/**/*"],
23 | "env": {
24 | "node": false,
25 | "browser": true,
26 | "es6": true
27 | },
28 | "rules": {
29 | "no-use-before-define": "off",
30 | "no-redeclare": "off",
31 | "no-unused-vars": "error"
32 | },
33 | "globals": {
34 | "multipageMap": "readonly",
35 | "usesMultipage": "readonly",
36 | "idToSection": "readonly",
37 | "sdoMap": "readonly",
38 | "biblio": "readonly",
39 | "debounce": "writable",
40 | "menu": "writable",
41 | "referencePane": "writable",
42 | "sdoBox": "writable",
43 | "Toolbox": "writable"
44 | }
45 | },
46 | {
47 | "files": ["test/**/*"],
48 | "env": {
49 | "mocha": true
50 | }
51 | }
52 | ],
53 | "rules": {
54 | "@typescript-eslint/consistent-type-imports": "error",
55 | "prettier/prettier": "error",
56 | "arrow-body-style": "error",
57 | "prefer-arrow-callback": "error",
58 | "object-shorthand": "error",
59 | "no-inner-declarations": "off",
60 | "no-loss-of-precision": "off",
61 | "consistent-return": "off",
62 | "no-floating-decimal": "error",
63 | "no-self-compare": "error",
64 | "no-throw-literal": "error",
65 | "no-void": "error",
66 | "strict": [
67 | "error",
68 | "global"
69 | ],
70 | "no-underscore-dangle": "off",
71 | "no-constant-condition": "off",
72 | "camelcase": [
73 | "error",
74 | {
75 | "properties": "never"
76 | }
77 | ],
78 | "no-empty": "error",
79 | "curly": [
80 | "error",
81 | "multi-line"
82 | ],
83 | "no-var": "error"
84 | }
85 | }
86 |
--------------------------------------------------------------------------------
/boilerplate/software-license.html:
--------------------------------------------------------------------------------
1 | 1 Example
16 |1.1 Static Semantics: AbstractOperation
29 |- Return 0.
All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.
2 | 3 |Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
4 | 5 |-
6 |
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 7 |
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 8 |
- Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission. 9 |
THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
12 | -------------------------------------------------------------------------------- /test/cli.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const assert = require('assert'); 4 | const execSync = require('child_process').execSync; 5 | const execPath = process.execPath.includes(' ') ? `"${process.execPath}"` : process.execPath; 6 | 7 | describe('ecmarkup#cli', function () { 8 | this.timeout(4000); // Increase timeout for CLI tests as startup time can be variable. 9 | 10 | it('exits cleanly on success', () => { 11 | execSync(`${execPath} ./bin/ecmarkup.js test/baselines/sources/example.html`, { 12 | encoding: 'utf8', 13 | }); 14 | }); 15 | 16 | it('exits cleanly on warning', () => { 17 | execSync(`${execPath} ./bin/ecmarkup.js test/baselines/sources/duplicate-ids.html`, { 18 | encoding: 'utf8', 19 | stdio: 'ignore', 20 | }); 21 | }); 22 | 23 | it('exits with an error on error', () => { 24 | assert.throws(() => { 25 | execSync(`${execPath} ./bin/ecmarkup.js test/baselines/sources/malformed.bad.html`, { 26 | encoding: 'utf8', 27 | stdio: 'ignore', 28 | }); 29 | }); 30 | }); 31 | 32 | it('exits with an error on warning when using --strict', () => { 33 | assert.throws(() => { 34 | execSync(`${execPath} ./bin/ecmarkup.js --strict test/baselines/sources/duplicate-ids.html`, { 35 | encoding: 'utf8', 36 | stdio: 'ignore', 37 | }); 38 | }); 39 | }); 40 | }); 41 | 42 | describe('emu-format --check', function () { 43 | this.timeout(4000); 44 | 45 | it('exits cleanly if the file needs no formatting', () => { 46 | execSync(`${execPath} ./bin/emu-format.js --check test/format-good.html`, { 47 | encoding: 'utf8', 48 | }); 49 | }); 50 | 51 | it('exits with an error if the file needs formatting', () => { 52 | assert.throws(() => { 53 | execSync(`${execPath} ./bin/emu-format.js --check test/format-bad.html`, { 54 | encoding: 'utf8', 55 | }); 56 | }); 57 | }); 58 | 59 | it('exits with an error if any files in the list need formatting', () => { 60 | assert.throws(() => { 61 | execSync( 62 | `${execPath} ./bin/emu-format.js --check test/format-good.html test/format-bad.html`, 63 | { 64 | encoding: 'utf8', 65 | }, 66 | ); 67 | }); 68 | }); 69 | }); 70 | -------------------------------------------------------------------------------- /src/Import.ts: -------------------------------------------------------------------------------- 1 | import type Spec from './Spec'; 2 | 3 | import * as utils from './utils'; 4 | import * as path from 'path'; 5 | import type { JSDOM } from 'jsdom'; 6 | 7 | export type Import = { 8 | importLocation: string; 9 | relativeRoot: string; 10 | source: string; 11 | }; 12 | 13 | export async function buildImports(spec: Spec, importNode: EmuImportElement, root: string) { 14 | const href = importNode.getAttribute('href'); 15 | if (!href) throw new Error('Import missing href attribute.'); 16 | const importPath = path.join(root, href); 17 | const relativeRoot = path.dirname(importPath); 18 | 19 | const html = await spec.fetch(importPath); 20 | 21 | spec.imports.push({ importLocation: importPath, relativeRoot, source: html }); 22 | 23 | const importDom = utils.htmlToDom(html); 24 | importNode.dom = importDom; 25 | importNode.source = html; 26 | importNode.importPath = importPath; 27 | 28 | const importDoc = importDom.window.document; 29 | 30 | // clone this list so we can walk it after the replaceWith call 31 | const importedNodes = [...importDoc.body.childNodes]; 32 | const frag = spec.doc.createDocumentFragment(); 33 | 34 | for (let i = 0; i < importedNodes.length; i++) { 35 | const importedNode = spec.doc.adoptNode(importedNodes[i]); 36 | importedNodes[i] = importedNode; 37 | frag.appendChild(importedNode); 38 | 39 | spec.topLevelImportedNodes.set(importedNode, importNode); 40 | } 41 | 42 | importNode.replaceWith(frag); 43 | 44 | for (let i = 0; i < importedNodes.length; i++) { 45 | const importedNode = importedNodes[i]; 46 | if (importedNode.nodeType === 1 /* Node.ELEMENT_NODE */) { 47 | const importedImports = [ 48 | ...(importedNode as HTMLElement).querySelectorAll('emu-import'), 49 | // we have to do this because querySelectorAll can't return its `this` 50 | ...((importedNode as HTMLElement).tagName === 'EMU-IMPORT' ? [importedNode] : []), 51 | ]; 52 | for (const childImport of importedImports) { 53 | await buildImports(spec, childImport as EmuImportElement, relativeRoot); 54 | } 55 | } 56 | } 57 | } 58 | 59 | export interface EmuImportElement extends HTMLElement { 60 | href: string; 61 | dom: JSDOM; 62 | source?: string; 63 | importPath?: string; 64 | } 65 | -------------------------------------------------------------------------------- /src/NonTerminal.ts: -------------------------------------------------------------------------------- 1 | import type Spec from './Spec'; 2 | import type { Context } from './Context'; 3 | import type { BiblioEntry } from './Biblio'; 4 | 5 | import Builder from './Builder'; 6 | 7 | export default class NonTerminal extends Builder { 8 | /** @internal */ params: string | null; 9 | /** @internal */ optional: boolean; 10 | /** @internal */ namespace: string; 11 | /** @internal */ entry?: BiblioEntry; 12 | 13 | static readonly elements = ['EMU-NT'] as const; 14 | 15 | constructor(spec: Spec, node: HTMLElement, namespace: string) { 16 | super(spec, node); 17 | 18 | this.params = node.getAttribute('params'); 19 | this.optional = node.hasAttribute('optional'); 20 | this.namespace = namespace; 21 | } 22 | 23 | static async enter({ spec, node, clauseStack }: Context) { 24 | const clause = clauseStack[clauseStack.length - 1]; 25 | const namespace = clause ? clause.namespace : spec.namespace; 26 | const nt = new NonTerminal(spec, node, namespace); 27 | spec._ntRefs.push(nt); 28 | 29 | if (spec.opts.lintSpec && spec.locate(node) != null && !node.hasAttribute('example')) { 30 | const clause = clauseStack[clauseStack.length - 1]; 31 | const namespace = clause ? clause.namespace : spec.namespace; 32 | spec._ntStringRefs = spec._ntStringRefs.concat({ 33 | name: node.textContent!, 34 | loc: { line: 1, column: 1 }, 35 | node, 36 | namespace, 37 | }); 38 | } 39 | } 40 | 41 | build() { 42 | const name = this.node.textContent!; 43 | // const id = 'prod-' + name; 44 | const entry = this.spec.biblio.byProductionName(name, this.namespace); 45 | 46 | if (entry) { 47 | this.node.innerHTML = '' + name + ''; 48 | this.entry = entry; 49 | } else { 50 | this.node.innerHTML = name; 51 | } 52 | let modifiers = ''; 53 | 54 | if (this.params) { 55 | modifiers += 'COPYRIGHT NOTICE
2 | 3 |© !YEAR! Ecma International
4 | 5 |By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.
6 | 7 |This document may be copied, published and distributed to others, and certain derivative works of it may be prepared, copied, published, and distributed, in whole or in part, provided that the above copyright notice and this Copyright License and Disclaimer are included on all such copies and derivative works. The only derivative works that are permissible under this Copyright License and Disclaimer are:
8 | 9 |(i) works which incorporate all or portion of this document for the purpose of providing commentary or explanation (such as an annotated version of the document),
10 | 11 |(ii) works which incorporate all or portion of this document for the purpose of incorporating features that provide accessibility,
12 | 13 |(iii) translations of this document into languages other than English and into different formats and
14 | 15 |(iv) works by making use of this specification in standard conformant products by implementing (e.g. by copy and paste wholly or partly) the functionality therein.
16 | 17 |However, the content of this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as required to translate it into languages other than English or into a different format.
18 | 19 |The official version of an Ecma International document is the English language version on the Ecma International website. In the event of discrepancies between a translated version and the official version, the official version shall govern.
20 | 21 |The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or assigns.
22 | 23 |This document and the information contained herein is provided on an “AS IS” basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
24 | -------------------------------------------------------------------------------- /boilerplate/alternative-copyright.html: -------------------------------------------------------------------------------- 1 |
2 |
58 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/multipage.html/multipage/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
11 | ALTERNATIVE COPYRIGHT NOTICE AND COPYRIGHT LICENSE
3 | 4 |© !YEAR! Ecma International
5 | 6 |7 | By obtaining and/or copying this work, you (the licensee) agree that you 8 | have read, understood, and will comply with the following terms and 9 | conditions. 10 |
11 | 12 |13 | Permission under Ecma’s copyright to copy, modify, prepare derivative works 14 | of, and distribute this work, with or without modification, for any purpose 15 | and without fee or royalty is hereby granted, provided that you include the 16 | following on ALL copies of the work or portions thereof, including 17 | modifications: 18 |
19 | 20 |21 | (i) The full text of this COPYRIGHT NOTICE AND COPYRIGHT LICENSE in a location 22 | viewable to users of the redistributed or derivative work. 23 |
24 |25 | (ii) Any pre-existing intellectual property disclaimers, notices, or terms and 26 | conditions. If none exist, the Ecma alternative copyright notice should be 27 | included. 28 |
29 |
30 | (iii) Notice of any changes or modifications, through a copyright statement on
31 | the document such as “This document includes material copied from or
32 | derived from !DOCUMENT!.
33 | Copyright © Ecma International.”
34 |
Disclaimers
37 | 38 |39 | THIS WORK IS PROVIDED “AS IS,” AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS 40 | OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES 41 | OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF 42 | THE DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, 43 | TRADEMARKS OR OTHER RIGHTS. 44 |
45 | 46 |47 | COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR 48 | CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT. 49 |
50 | 51 |52 | The name and trademarks of copyright holders may NOT be used in advertising 53 | or publicity pertaining to the work without specific, written prior 54 | permission. Title to copyright in this work will at all times remain with 55 | copyright holders. 56 |
57 |
12 |
-
13 |
- Toggle shortcuts help
?
14 | - Toggle "can call user code" annotations
u
15 | - Navigate to/from multipage
m
16 | - Jump to search box
/
17 | - Toggle pinning of the current clause
p
18 | - Jump to the nth pin
1-9
19 | - Jump to the 10th pin
0
20 | - Jump to the most recent link target
`
21 |
Intro
23 |Some text.
24 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
15 |
26 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/algorithm-replacements.html:
--------------------------------------------------------------------------------
1 |
2 | 1 Test Clause
16 |Increases indentaion level.
17 |global1.Zone.current; // succeeds
18 | global2.Zone.current; // throws: currentRealm = realm1; thisRealm = functionRealm = realm2
19 |
20 | const getter1 = Object.getOwnPropertyDescriptor(global1.Zone, "current").get;
21 | const getter2 = Object.getOwnPropertyDescriptor(global2.Zone, "current").get;
22 |
23 | getter1.call(global2.Zone); // throws: currentRealm = functionRealm = realm1; thisRealm = realm2
24 | getter2.call(global1.Zone); // throws: currentRealm = thisRealm = realm1; functionRealm = realm2
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
15 |
36 |
--------------------------------------------------------------------------------
/src/Eqn.ts:
--------------------------------------------------------------------------------
1 | import type { Context } from './Context';
2 |
3 | import Builder from './Builder';
4 | import * as emd from 'ecmarkdown';
5 | import * as utils from './utils';
6 |
7 | export default class Eqn extends Builder {
8 | // @ts-ignore
9 | private constructor() {
10 | throw new Error('not actually constructible');
11 | }
12 |
13 | static async enter(context: Context) {
14 | const { spec, node, clauseStack } = context;
15 |
16 | const aoid = node.getAttribute('aoid');
17 | if (aoid) {
18 | const existing = spec.biblio.keysForNamespace(spec.namespace);
19 | if (existing.has(aoid)) {
20 | spec.warn({
21 | type: 'attr-value',
22 | attr: 'aoid',
23 | node,
24 | ruleId: 'duplicate-definition',
25 | message: `duplicate definition ${JSON.stringify(aoid)}`,
26 | });
27 | }
28 |
29 | const id = node.getAttribute('id');
30 | if (id) {
31 | spec.biblio.add({
32 | type: 'op',
33 | aoid,
34 | id,
35 | signature: null,
36 | effects: [],
37 | });
38 | } else {
39 | const clause = clauseStack[clauseStack.length - 1];
40 | const clauseId = clause ? clause.id : ''; // TODO: no eqns outside of clauses, eh?
41 | spec.biblio.add({
42 | type: 'op',
43 | aoid,
44 | refId: clauseId,
45 | signature: null,
46 | effects: [],
47 | });
48 | }
49 | }
50 |
51 | let contents;
52 | try {
53 | contents = emd.fragment(node.innerHTML);
54 | } catch (e: any) {
55 | utils.warnEmdFailure(spec.warn, node, e);
56 | node.innerHTML = utils.wrapEmdFailure(node.innerHTML);
57 | return;
58 | }
59 |
60 | if (utils.shouldInline(node)) {
61 | const classString = node.getAttribute('class');
62 | let classes: string[];
63 |
64 | if (classString) {
65 | classes = classString.split(' ');
66 | } else {
67 | classes = [];
68 | }
69 |
70 | if (classes.indexOf('inline') === -1) {
71 | node.setAttribute('class', classes.concat(['inline']).join(' '));
72 | }
73 | } else {
74 | contents =
75 | '1 Title
16 | 17 |You can refer to a step in a replacement algorithm before it occurs in text, like step
You can similarly refer to a step in a replacement algorithm which itself which replaces a step in a replacement algorithm, like step
An algorithm can come before the step it replaces.
22 | 23 |- Two a:
- Two a i:
- Two a i one.
- Two a i two.
- Two a i:
This is our sample algorithm.
26 |- One.
- Two:
- Two a.
An algorithm can also come after the step it replaces.
29 | 30 |- Two a:
- Two a i:
- Two a i one.
- Two a i two.
- Two a i:
You can even replace steps in replacement algorithms.
33 | 34 |- Two a i two:
- Two a i two a.
- Two a i two b.
- Two a i two c:
- Two a i two c i:
- Two a i two c i i:
- Two a i two c i i i.
- Two a i two c i i ii.
- Two a i two c i i:
- Two a i two c i:
' +
76 | contents
77 | .split(/\r?\n/g)
78 | .filter(s => s.trim().length > 0)
79 | .join('
') +
80 | '
';
81 | }
82 |
83 | node.innerHTML = contents;
84 | }
85 |
86 | static elements = ['EMU-EQN'];
87 | }
88 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/eqn.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
-
5 |
- Toggle shortcuts help
?
6 | - Toggle "can call user code" annotations
u
7 |
8 | - Jump to search box
/
9 | - Toggle pinning of the current clause
p
10 | - Jump to the nth pin
1-9
11 | - Jump to the 10th pin
0
12 | - Jump to the most recent link target
`
13 |
14 |
15 |
29 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/multipage.html/multipage/second.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
11 | 1 Header
16 |Can refer to eqns inside paragraph text via autolinking:
- Return
Value (val);
Value2(t)
= t
DateValue(t)
= 0 if t = 0
= 1 if t = 1
= 2
Value(t)
= t
- Return
Value (val);
Inline eqns are a thing, for example
12 |
-
13 |
- Toggle shortcuts help
?
14 | - Toggle "can call user code" annotations
u
15 | - Navigate to/from multipage
m
16 | - Jump to search box
/
17 | - Toggle pinning of the current clause
p
18 | - Jump to the nth pin
1-9
19 | - Jump to the 10th pin
0
20 | - Jump to the most recent link target
`
21 |
1 Second Clause
23 |A cross-section reference:
A relative image: 
.
12 |
-
13 |
- Toggle shortcuts help
?
14 | - Toggle "can call user code" annotations
u
15 | - Navigate to/from multipage
m
16 | - Jump to search box
/
17 | - Toggle pinning of the current clause
p
18 | - Jump to the nth pin
1-9
19 | - Jump to the 10th pin
0
20 | - Jump to the most recent link target
`
21 |
2 Third Clause
23 |Some text.
24 |2.1 Algorithm
26 |Pretend there's an algorithm here.
27 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
test title!
13 | 14 |Copyright & Software License
16 |Tet Corporation
17 |2 Hammarskjöld Plaza
18 |New York City, New York
19 |Tel: 123-456-7890
20 |Fax: 123-456-7890
21 |Web: http://www.tet-corporation.com/
22 | 23 |Copyright Notice
24 |© 2018 Rick Waldron, Mid-World
25 |Software License
27 |Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
28 | 29 |The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
30 | 31 |THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
32 | 33 |2 | toc: false 3 | copyright: false 4 | assets: none 5 |6 |
Intro
8 |Clause 1
15 |Clause 1.1
24 | 25 |SomeAlg
34 |SomeAlg does things.
37 |Can still xref clauses inside of namespaces:
Can xref prods in namespaces:
Annex
43 |SomeAlg
51 |Annex 1.2
57 |SomeAlg should link to #annex12. |Foo| should link to the production in #annex1.
58 |SomeAlg does things.
61 |Annex 2
68 | 69 |SomeAlg
71 |SomeAlg does things.
77 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
17 | Example (Informative): An example
20 | Multiple examples are numbered similar to notes
21 |
23 |
24 |
25 |
26 | Table 1 (Informative): A Table Of Stuff
28 |
29 |
32 |
34 |
35 |
36 | Table 2 (Informative): A Table Of Stuff
39 |
40 |
43 | Example (Informative): An example
46 | Multiple examples are numbered similar to notes
47 |
49 |
--------------------------------------------------------------------------------
/js/sdoMap.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 | let sdoBox = {
3 | init() {
4 | this.$alternativeId = null;
5 | this.$outer = document.createElement('div');
6 | this.$outer.classList.add('toolbox-container');
7 | this.$container = document.createElement('div');
8 | this.$container.classList.add('toolbox');
9 | this.$displayLink = document.createElement('a');
10 | this.$displayLink.setAttribute('href', '#');
11 | this.$displayLink.textContent = 'Syntax-Directed Operations';
12 | this.$displayLink.addEventListener('click', e => {
13 | e.preventDefault();
14 | e.stopPropagation();
15 | referencePane.showSDOs(sdoMap[this.$alternativeId] || {}, this.$alternativeId);
16 | });
17 | this.$container.appendChild(this.$displayLink);
18 | this.$outer.appendChild(this.$container);
19 | document.body.appendChild(this.$outer);
20 | },
21 |
22 | activate(el) {
23 | clearTimeout(this.deactiveTimeout);
24 | Toolbox.deactivate();
25 | this.$alternativeId = el.id;
26 | let numSdos = Object.keys(sdoMap[this.$alternativeId] || {}).length;
27 | this.$displayLink.textContent = 'Syntax-Directed Operations (' + numSdos + ')';
28 | this.$outer.classList.add('active');
29 | let top = el.offsetTop - this.$outer.offsetHeight;
30 | let left = el.offsetLeft + 50 - 10; // 50px = padding-left(=75px) + text-indent(=-25px)
31 | this.$outer.setAttribute('style', 'left: ' + left + 'px; top: ' + top + 'px');
32 | if (top < document.body.scrollTop) {
33 | this.$container.scrollIntoView();
34 | }
35 | },
36 |
37 | deactivate() {
38 | clearTimeout(this.deactiveTimeout);
39 | this.$outer.classList.remove('active');
40 | },
41 | };
42 |
43 | document.addEventListener('DOMContentLoaded', () => {
44 | if (typeof sdoMap == 'undefined') {
45 | console.error('could not find sdo map');
46 | return;
47 | }
48 | sdoBox.init();
49 |
50 | let insideTooltip = false;
51 | sdoBox.$outer.addEventListener('pointerenter', () => {
52 | insideTooltip = true;
53 | });
54 | sdoBox.$outer.addEventListener('pointerleave', () => {
55 | insideTooltip = false;
56 | sdoBox.deactivate();
57 | });
58 |
59 | sdoBox.deactiveTimeout = null;
60 | [].forEach.call(document.querySelectorAll('emu-grammar[type=definition] emu-rhs'), node => {
61 | node.addEventListener('pointerenter', function () {
62 | sdoBox.activate(this);
63 | });
64 |
65 | node.addEventListener('pointerleave', () => {
66 | sdoBox.deactiveTimeout = setTimeout(() => {
67 | if (!insideTooltip) {
68 | sdoBox.deactivate();
69 | }
70 | }, 500);
71 | });
72 | });
73 |
74 | document.addEventListener(
75 | 'keydown',
76 | debounce(e => {
77 | if (e.code === 'Escape') {
78 | sdoBox.deactivate();
79 | }
80 | }),
81 | );
82 | });
83 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/multipage.html/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | 1 A
15 | 16 |1.1 Sub A
18 | 19 |2 Section A: Extras
27 || Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
3 Section A: Extras
37 | 38 || Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
7 |
-
8 |
- Toggle shortcuts help
?
9 | - Toggle "can call user code" annotations
u
10 | - Navigate to/from multipage
m
11 | - Jump to search box
/
12 | - Toggle pinning of the current clause
p
13 | - Jump to the nth pin
1-9
14 | - Jump to the 10th pin
0
15 | - Jump to the most recent link target
`
16 |
20 |
21 |
22 |
25 |
26 |
27 |
31 |
32 |
33 |
36 |
39 |
40 |
--------------------------------------------------------------------------------
/js/superscripts.js:
--------------------------------------------------------------------------------
1 | 'use strict';
2 |
3 | // Update superscripts to not suffer misinterpretation when copied and pasted as plain text.
4 | // For example,
5 | // * Replace `103` with
6 | // `103`
7 | // so it gets pasted as `10**3` rather than `103`.
8 | // * Replace `10-x` with
9 | // `10-x`
10 | // so it gets pasted as `10**-x` rather than `10-x`.
11 | // * Replace `2a + 1` with
12 | // `2**(a + 1)`
13 | // so it gets pasted as `2**(a + 1)` rather than `2a + 1`.
14 |
15 | function makeExponentPlainTextSafe(sup) {
16 | // Change a only if it appears to be an exponent:
17 | // * text-only and contains only mathematical content (not e.g. `1st`)
18 | // * contains only s and internal links (e.g.
19 | // `2Intro
23 |Some text.
24 |1 Second Clause
28 |A cross-section reference:
A relative image: .
2 Third Clause
34 |Some text.
35 |2.1 Algorithm
37 |Pretend there's an algorithm here.
38 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 | This is a note. Since it is outside a clause it is unstyled.
14 |
15 |
16 |
19 |
20 |
21 |
24 |
25 |
26 |
29 |
30 |
31 |
33 |
--------------------------------------------------------------------------------
/src/ProdRef.ts:
--------------------------------------------------------------------------------
1 | import type { Context } from './Context';
2 | import type Spec from './Spec';
3 |
4 | import Builder from './Builder';
5 | import { shouldInline } from './utils';
6 |
7 | export default class ProdRef extends Builder {
8 | /** @internal */ public namespace: string;
9 | /** @internal */ public name: string;
10 |
11 | static readonly elements = ['EMU-PRODREF'] as const;
12 |
13 | constructor(spec: Spec, node: HTMLElement, namespace: string) {
14 | super(spec, node);
15 | this.spec = spec;
16 | this.node = node;
17 | this.namespace = namespace;
18 | this.name = node.getAttribute('name')!;
19 | }
20 |
21 | static async enter({ node, spec, clauseStack }: Context) {
22 | const clause = clauseStack[clauseStack.length - 1];
23 | const namespace = clause ? clause.namespace : spec.namespace;
24 | const prodref = new ProdRef(spec, node, namespace);
25 | spec._prodRefs.push(prodref);
26 | }
27 |
28 | build() {
29 | const entry = this.spec.biblio.byProductionName(this.name, this.namespace);
30 | const prod = entry ? entry._instance : null;
31 |
32 | let copy: HTMLElement;
33 |
34 | if (!prod) {
35 | console.error('Could not find production named ' + this.node.getAttribute('name'));
36 | return;
37 | }
38 |
39 | if (shouldInline(this.node)) {
40 | const cls = this.node.getAttribute('class') || '';
41 |
42 | if (cls.indexOf('inline') === -1) {
43 | this.node.setAttribute('class', cls + ' inline');
44 | }
45 | }
46 |
47 | if (this.node.hasAttribute('a')) {
48 | this.node.setAttribute('collapsed', '');
49 | if (!prod.rhsesById[this.node.getAttribute('a')!]) {
50 | console.error(
51 | 'Could not find alternative ' +
52 | this.node.getAttribute('a') +
53 | ' of production ' +
54 | prod.name,
55 | );
56 | return;
57 | }
58 |
59 | copy = prod.node.cloneNode(false) as HTMLElement;
60 |
61 | // copy nodes until the first RHS. This captures the production name and any annotations.
62 | for (let j = 0; j < prod.node.childNodes.length; j++) {
63 | if (prod.node.childNodes[j].nodeName === 'EMU-RHS') break;
64 |
65 | copy.appendChild(prod.node.childNodes[j].cloneNode(true));
66 | }
67 |
68 | copy.appendChild(prod.rhsesById[this.node.getAttribute('a')!].node.cloneNode(true));
69 | } else {
70 | copy = prod.node.cloneNode(true) as HTMLElement;
71 | }
72 |
73 | copy.removeAttribute('id');
74 |
75 | if (this.node.parentNode) {
76 | this.node.parentNode.replaceChild(copy, this.node);
77 | }
78 |
79 | // copy attributes over (especially important for 'class').
80 | for (let j = 0; j < this.node.attributes.length; j++) {
81 | const attr = this.node.attributes[j];
82 |
83 | if (!copy.hasAttribute(attr.name)) {
84 | copy.setAttribute(attr.name, attr.value);
85 | }
86 | }
87 | }
88 | }
89 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/namespaces-productions.html:
--------------------------------------------------------------------------------
1 |
2 | 1 Definitions of Normative Optional etc
17 |Normative Optional is a defined term, as is Legacy. For comparison, "Deprecated" is not.
18 |2 Example Normative Optional Clause
22 |This clause is normative optional.
23 |3 Example Legacy Clause
27 |This clause is legacy.
28 |4 Example algorithm with marked steps.
32 |- This step is required.
- This step is optional.
- This step is legacy.
- This step is only legacy, but has substeps.
- This is a substep.
- DeprecatedThis step is optional.
- This step is required.
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
16 | Foo ::
17 | bar
18 |
19 |
20 | baz
21 |
22 |
23 |
25 | Foo :: bar
27 |
29 | Foo ::
30 | bar
31 |
32 |
33 | baz
34 |
35 |
36 |
37 |
38 |
39 |
41 | Foo ::
42 | bar
43 |
44 |
45 | qux
46 |
47 |
48 |
49 | Statement ::
50 | overridden statement
51 |
52 |
53 |
55 | Foo :: bar
57 |
59 | Foo ::
60 | bar
61 |
62 |
63 | qux
64 |
65 |
66 |
67 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "ecmarkup",
3 | "version": "22.0.0",
4 | "description": "Custom element definitions and core utilities for markup that specifies ECMAScript and related technologies.",
5 | "main": "lib/ecmarkup.js",
6 | "typings": "lib/ecmarkup.d.ts",
7 | "scripts": {
8 | "build": "tsc -sourceMap -declarationMap",
9 | "build-release": "tsc",
10 | "build-spec": "mkdir -p docs && node bin/ecmarkup.js spec/index.html docs/index.html --assets-dir=docs && cp ecma-logo.png docs/",
11 | "prepack": "safe-publish-latest && npm run build-release",
12 | "format-spec": "node bin/emu-format.js --write spec/index.html",
13 | "test": "mocha",
14 | "test-baselines": "mocha --timeout 10000 test/baselines.js",
15 | "test-declarations": "tsc -p tsconfig.test.json",
16 | "update-baselines": "npm --update-baselines run test-baselines",
17 | "pretest-published-files": "rm -rf \"ecmarkup-$npm_package_version.tgz\" package",
18 | "test-published-files": "npm pack && tar zxvf \"ecmarkup-$npm_package_version.tgz\" && cp -r test package/test && cd package && npm test && cd ..",
19 | "posttest-published-files": "rm -rf \"ecmarkup-$npm_package_version.tgz\" package",
20 | "lint": "eslint --ext .js,.ts js src test",
21 | "format": "prettier --write ."
22 | },
23 | "bin": {
24 | "ecmarkup": "bin/ecmarkup.js",
25 | "emu-format": "bin/emu-format.js"
26 | },
27 | "files": [
28 | "/bin",
29 | "/lib",
30 | "/js",
31 | "/css",
32 | "/img",
33 | "/fonts",
34 | "/boilerplate",
35 | "/entities-processed.json"
36 | ],
37 | "repository": "tc39/ecmarkup",
38 | "keywords": [
39 | "ecmascript",
40 | "javascript",
41 | "specs",
42 | "specifications",
43 | "markup",
44 | "markdown",
45 | "html",
46 | "code"
47 | ],
48 | "author": "Brian Terlson",
49 | "license": "MIT",
50 | "dependencies": {
51 | "chalk": "^4.1.2",
52 | "command-line-args": "^5.2.0",
53 | "command-line-usage": "^6.1.1",
54 | "dedent-js": "^1.0.1",
55 | "ecmarkdown": "^8.1.0",
56 | "eslint-formatter-codeframe": "^7.32.1",
57 | "fast-glob": "^3.2.7",
58 | "grammarkdown": "^3.3.2",
59 | "highlight.js": "11.0.1",
60 | "html-escape": "^1.0.2",
61 | "js-yaml": "^3.13.1",
62 | "jsdom": "^25.0.1",
63 | "nwsapi": "2.2.0",
64 | "parse5": "^6.0.1",
65 | "prex": "^0.4.7",
66 | "promise-debounce": "^1.0.1"
67 | },
68 | "devDependencies": {
69 | "@types/command-line-args": "^5.2.0",
70 | "@types/command-line-usage": "^5.0.2",
71 | "@types/js-yaml": "^3.12.1",
72 | "@types/jsdom": "^16.2.13",
73 | "@types/node": "^13.1.8",
74 | "@types/parse5": "^6.0.2",
75 | "@typescript-eslint/eslint-plugin": "^8.6.0",
76 | "@typescript-eslint/parser": "^8.6.0",
77 | "eslint": "^8.56.0",
78 | "eslint-config-prettier": "^9.1.0",
79 | "eslint-plugin-prettier": "^5.1.3",
80 | "mocha": "^5.2.0",
81 | "prettier": "^3.2.3",
82 | "safe-publish-latest": "^1.1.4",
83 | "typescript": "^5.5.4"
84 | },
85 | "prettier": {
86 | "singleQuote": true,
87 | "arrowParens": "avoid",
88 | "printWidth": 100
89 | },
90 | "engines": {
91 | "node": ">= 18"
92 | }
93 | }
94 |
--------------------------------------------------------------------------------
/src/RHS.ts:
--------------------------------------------------------------------------------
1 | import type Spec from './Spec';
2 | import type Production from './Production';
3 |
4 | import Builder from './Builder';
5 |
6 | export default class RHS extends Builder {
7 | /** @internal */ production: Production;
8 | /** @internal */ constraints: string | null;
9 | /** @internal */ alternativeId: string | null;
10 |
11 | constructor(spec: Spec, prod: Production, node: HTMLElement) {
12 | super(spec, node);
13 | this.production = prod;
14 | this.node = node;
15 | this.constraints = node.getAttribute('constraints');
16 | this.alternativeId = node.getAttribute('a');
17 | }
18 |
19 | build() {
20 | if (this.node.textContent === '') {
21 | this.node.textContent = '[empty]';
22 |
23 | return;
24 | }
25 |
26 | if (this.constraints) {
27 | const cs = this.spec.doc.createElement('emu-constraints');
28 | cs.textContent = '[' + this.constraints + ']';
29 |
30 | this.node.insertBefore(cs, this.node.childNodes[0]);
31 | }
32 |
33 | this.terminalify(this.node);
34 | }
35 |
36 | terminalify(parentNode: Element) {
37 | // we store effects to perform later so the iteration doesn't get messed up
38 | const surrogateTags = ['INS', 'DEL', 'MARK'];
39 | const pairs: { parent: Element; child: Text }[] = [];
40 | for (const node of parentNode.childNodes) {
41 | if (node.nodeType === 3) {
42 | pairs.push({ parent: parentNode, child: node as Text });
43 | } else if (surrogateTags.includes(node.nodeName)) {
44 | for (const child of node.childNodes) {
45 | if (child.nodeType === 3) {
46 | pairs.push({ parent: node as Element, child: child as Text });
47 | }
48 | }
49 | }
50 | }
51 | let first = true;
52 | for (const { parent, child } of pairs) {
53 | if (!first && !/^\s+$/.test(child.textContent ?? '')) {
54 | if (parent === parentNode) {
55 | parentNode.insertBefore(this.spec.doc.createTextNode(' '), child);
56 | } else {
57 | // put the space outside of `` (etc) tags
58 | parentNode.insertBefore(this.spec.doc.createTextNode(' '), parent);
59 | }
60 | }
61 | first = false;
62 | this.wrapTerminal(parent, child);
63 | }
64 | }
65 |
66 | private wrapTerminal(parentNode: Element, node: Text) {
67 | const textContent = node.textContent!;
68 | const text = textContent.trim();
69 |
70 | if (text === '' && textContent.length > 0) {
71 | // preserve intermediate whitespace
72 | return;
73 | }
74 |
75 | const pieces = text.split(/\s/);
76 |
77 | let first = true;
78 | pieces.forEach(p => {
79 | if (p.length === 0) {
80 | return;
81 | }
82 | const est = this.spec.doc.createElement('emu-t');
83 | est.textContent = p;
84 |
85 | parentNode.insertBefore(est, node);
86 | if (!first) {
87 | parentNode.insertBefore(this.spec.doc.createTextNode(' '), est);
88 | }
89 | first = false;
90 | });
91 |
92 | parentNode.removeChild(node);
93 | }
94 | }
95 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/figure.html:
--------------------------------------------------------------------------------
1 |
2 | Intro
15 |1 C
40 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 | Figure 1
15 | this is a figure!
16 | Figure 2 (Informative): Informative figure
20 | this is a figure!
21 | Table 1: An example table
24 |
25 |
26 |
33 | Table 2 (Informative): An example table 2
36 |
37 |
43 | Figure 3 (Informative): This is the caption
46 |
47 | this is a figure!
48 | Table 3: This is a table
51 |
52 |
53 |
54 |
61 | Table 4 (Informative): This is a second table
64 |
65 |
66 |
72 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/dfn.html:
--------------------------------------------------------------------------------
1 |
2 | | Column 1 | Column 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Column 1 | Column 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Column 1 | Column 2 |
|---|---|
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
| Value | Value 2 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
18 |
19 |
27 |
32 |
33 |
39 |
44 |
45 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/autolinking.html:
--------------------------------------------------------------------------------
1 |
2 | Intro
15 |Forward references to
Also terms from ES6 are auto-linked: Lexical Environment,
1 dfn
20 | 21 |The term dfn means the dfn tag. Other mentions of dfn in this clause should not be auto-linked.
22 | 23 |Terms with ids are called id dfns. Since this dfn has an id, other occurences
24 | of
1.1 dfn subclause
28 | 29 |Also terms are auto-linked in algorithms. But not naked abstract ops!
34 | 35 | 36 |1.2 dfn autolink
40 | 41 | 42 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
26 |
27 |
39 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/proposal-copyright.html:
--------------------------------------------------------------------------------
1 |
2 | 1 Autolinking
15 |Type, type,
Lowercase
19 |strict mode
20 |%Percent%
21 |extra spaces
22 |Await
23 |Variants
24 |2 Autolinking 2
28 |lowercase should not autolink. But
Vars to dfns should be vars not dfns: Lowercase.
34 |Also, no autolinks in anchors: Lowercase.
35 |Similarly, no autolinks for [Await].
36 |- Non-word-chars AOs still link when invoked, like
𝔽 (x).
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
Stage 0 Draft / September 26, 2014
test title!
13 | 14 |Copyright & Software License
16 | 17 |Copyright Notice
18 |© 2014 Brian Terlson, Ecma International
19 |Software License
21 |All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.
22 | 23 |Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
24 | 25 |-
26 |
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 27 |
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 28 |
- Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission. 29 |
THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 | 33 |
7 |
-
8 |
- Toggle shortcuts help
?
9 | - Toggle "can call user code" annotations
u
10 |
11 | - Jump to search box
/
12 | - Toggle pinning of the current clause
p
13 | - Jump to the nth pin
1-9
14 | - Jump to the 10th pin
0
15 | - Jump to the most recent link target
`
16 |
20 |
21 |
22 |
24 |
27 |
29 |
31 |
32 |
33 |
35 |
37 |
38 |
39 |
40 |
42 |
43 |
44 |
46 |
--------------------------------------------------------------------------------
/test/baselines/generated-reference/boilerplate-copyright.html:
--------------------------------------------------------------------------------
1 |
2 | 1 One
23 |1.1 Two
25 | 26 |1.2 Three
28 |1.3 four
30 |1.4 Three Again
34 |1.5 Four Again
36 |1.6 Two Again
41 |2 One Again
45 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
test title!
13 | 14 |Copyright & Software License
16 |Ecma International
17 |Rue du Rhone 114
18 |CH-1204 Geneva
19 |Tel: +41 22 849 6000
20 |Fax: +41 22 849 6001
21 |Web: https://ecma-international.org/
22 | 23 |Copyright Notice
24 |© 2018 Rick Waldron, Mid-World
25 |Software License
27 |All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.
28 | 29 |Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
30 | 31 |-
32 |
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 33 |
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 34 |
- Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission. 35 |
THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 | 39 |
3 |
-
4 |
- Toggle shortcuts help
?
5 | - Toggle "can call user code" annotations
u
6 |
7 | - Jump to search box
/
8 | - Toggle pinning of the current clause
p
9 | - Jump to the nth pin
1-9
10 | - Jump to the 10th pin
0
11 | - Jump to the most recent link target
`
12 |
13 |
14 |
17 |
19 |
20 |
27 |
--------------------------------------------------------------------------------
/src/formatter/text.ts:
--------------------------------------------------------------------------------
1 | import { LineBuilder } from './line-builder';
2 | const entities = require('../../entities-processed.json');
3 |
4 | function isBadNumericReference(codePoint: number) {
5 | // https://html.spec.whatwg.org/multipage/parsing.html#numeric-character-reference-end-state
6 | if (
7 | // NULL character
8 | !codePoint ||
9 | // out of range
10 | codePoint > 0x10ffff ||
11 | // surrogate
12 | (0xd800 <= codePoint && codePoint <= 0xdfff) ||
13 | // noncharacter
14 | (0xfdd0 <= codePoint && codePoint <= 0xfdef) ||
15 | (codePoint & 0xfffe) === 0xfffe ||
16 | // control character (but without exceptions for tab/line feed/form feed/space)
17 | (0 <= codePoint && codePoint <= 0x1f) ||
18 | (0x7f <= codePoint && codePoint <= 0x9f)
19 | ) {
20 | return true;
21 | }
22 | return false;
23 | }
24 |
25 | export function printText(text: string, indent: number, commonIndent: string = ''): LineBuilder {
26 | const output: LineBuilder = new LineBuilder(indent);
27 | if (text === '') {
28 | return output;
29 | }
30 | text = text.replace(/&(?:[a-zA-Z0-9]+|#[Xx]([0-9a-fA-F]+)|#([0-9]+));?/g, (m, hex, decimal) => {
31 | if (hex || decimal) {
32 | // pass through bad references,
33 | // normalize '&' and '<' into named references,
34 | // and transform everything else
35 | const codePoint = parseInt(hex || decimal, hex ? 16 : 10);
36 | if (isBadNumericReference(codePoint)) {
37 | return m;
38 | }
39 | const ch = String.fromCodePoint(codePoint);
40 | if (/\p{White_Space}|\p{DI}|\p{gc=M}|\p{gc=C}/u.test(ch)) {
41 | return m;
42 | }
43 | if (ch === '&') {
44 | return '&';
45 | } else if (ch === '<') {
46 | return '<';
47 | }
48 | return ch;
49 | }
50 |
51 | // entities[m] is null if the entity expands to '&', '<', or a string which has blank/control/etc characters
52 | if ({}.hasOwnProperty.call(entities, m) && entities[m] !== null) {
53 | return entities[m];
54 | }
55 | const lower = m.toLowerCase();
56 | if (lower === '<' || lower === '&') {
57 | return lower;
58 | } else if (lower === '<' || lower === '&') {
59 | return lower + ';';
60 | }
61 | return m;
62 | });
63 |
64 | const leadingSpace = text[0] === ' ' || text[0] === '\t';
65 | const trailingSpace = text[text.length - 1] === ' ' || text[text.length - 1] === '\t';
66 |
67 | const lines = text.split('\n').map((l, i) => {
68 | if (i === 0 || commonIndent === '' || !l.startsWith(commonIndent)) {
69 | return l.trim();
70 | }
71 | const withoutIndent = l.substring(commonIndent.length);
72 | const moreIndent = withoutIndent.match(/^ +/)?.[0];
73 | if (moreIndent) {
74 | return { indent: moreIndent, line: l.trim() };
75 | }
76 | return l.trim();
77 | });
78 |
79 | if (leadingSpace) {
80 | output.appendText(' ');
81 | }
82 | if (lines.length === 1) {
83 | if (lines[0] !== '') {
84 | output.appendText(lines[0] as string);
85 | if (trailingSpace) {
86 | output.appendText(' ');
87 | }
88 | }
89 | return output;
90 | }
91 | for (let i = 0; i < lines.length; ++i) {
92 | const line = lines[i];
93 | if (typeof line === 'string') {
94 | output.appendText(line);
95 | } else {
96 | output.last = line.indent;
97 | output.appendText(line.line);
98 | }
99 | if (i < lines.length - 1) {
100 | output.linebreak();
101 | }
102 | }
103 | if (trailingSpace && output.last !== '') {
104 | output.appendText(' ');
105 | }
106 |
107 | return output;
108 | }
109 |
--------------------------------------------------------------------------------
/src/lint/lint.ts:
--------------------------------------------------------------------------------
1 | import type { default as Spec, Warning } from '../Spec';
2 |
3 | import { collectNodes } from './collect-nodes';
4 | import { collectGrammarDiagnostics } from './collect-grammar-diagnostics';
5 | import { collectSpellingDiagnostics } from './collect-spelling-diagnostics';
6 | import { collectAlgorithmDiagnostics } from './collect-algorithm-diagnostics';
7 | import { collectHeaderDiagnostics } from './collect-header-diagnostics';
8 | import { collectTagDiagnostics } from './collect-tag-diagnostics';
9 | import type { AugmentedGrammarEle } from '../Grammar';
10 | import type { AlgorithmElementWithTree } from '../Algorithm';
11 |
12 | /*
13 | Currently this checks
14 | - grammarkdown's built-in sanity checks
15 | - the productions in the definition of each early error and SDO are defined in the main grammar
16 | - those productions do not include `[no LineTerminator here]` restrictions or `[+flag]` gating
17 | - the algorithm linting rules imported above
18 | - headers of abstract operations have consistent spacing
19 | - certain common spelling errors
20 |
21 | There's more to do:
22 | https://github.com/tc39/ecmarkup/issues/173
23 | */
24 | export async function lint(
25 | report: (err: Warning) => void,
26 | sourceText: string,
27 | spec: Spec,
28 | document: Document,
29 | ) {
30 | collectSpellingDiagnostics(report, sourceText, spec.imports);
31 |
32 | collectTagDiagnostics(report, spec, document);
33 |
34 | const collection = collectNodes(report, sourceText, spec, document);
35 | if (!collection.success) {
36 | return;
37 | }
38 | const { mainGrammar, headers, sdos, earlyErrors, algorithms } = collection;
39 |
40 | const { grammar, oneOffGrammars } = await collectGrammarDiagnostics(
41 | report,
42 | spec,
43 | sourceText,
44 | mainGrammar,
45 | sdos,
46 | earlyErrors,
47 | );
48 |
49 | collectAlgorithmDiagnostics(report, spec, sourceText, algorithms);
50 |
51 | collectHeaderDiagnostics(report, headers);
52 |
53 | // Stash intermediate results for later use
54 | // This isn't actually necessary for linting, but we might as well avoid redoing work later when we can.
55 |
56 | await grammar.emit(undefined, (file, source) => {
57 | const name = +file.split('.')[0];
58 | const node = mainGrammar[name].element;
59 | if ('grammarkdownOut' in node) {
60 | throw new Error('unexpectedly regenerating grammarkdown output for node ' + name);
61 | }
62 | if (name !== +grammar.sourceFiles[name].filename) {
63 | throw new Error(
64 | `grammarkdown file mismatch: ${name} vs ${grammar.sourceFiles[name].filename}. This is a bug in ecmarkup; please report it.`,
65 | );
66 | }
67 | (node as AugmentedGrammarEle).grammarkdownOut = source;
68 | (node as AugmentedGrammarEle).grammarSource = grammar.sourceFiles[name];
69 | });
70 | for (const { grammarEle, grammar } of oneOffGrammars) {
71 | await grammar.emit(undefined, (file, source) => {
72 | if ('grammarkdownOut' in grammarEle) {
73 | throw new Error('unexpectedly regenerating grammarkdown output');
74 | }
75 | if (grammar.rootFiles.length !== 1) {
76 | throw new Error(
77 | `grammarkdown file count mismatch: ${grammar.rootFiles.length}. This is a bug in ecmarkup; please report it.`,
78 | );
79 | }
80 | (grammarEle as AugmentedGrammarEle).grammarkdownOut = source;
81 | (grammarEle as AugmentedGrammarEle).grammarSource = grammar.rootFiles[0];
82 | });
83 | }
84 |
85 | for (const pair of algorithms) {
86 | if ('tree' in pair) {
87 | const element = pair.element as AlgorithmElementWithTree;
88 | element.ecmarkdownTree = pair.tree ?? null;
89 | element.originalHtml = pair.source ?? pair.element.innerHTML;
90 | }
91 | }
92 | }
93 |
--------------------------------------------------------------------------------
/js/print.js:
--------------------------------------------------------------------------------
1 | /**
2 | * Some notes:
3 | * - Prince cant grok trailing commas, so prettier is disabled anywhere it tries to enforce wrapping with trailing comma
4 | * - Prince doesn't support template strings yet
5 | * - Set Prince.trackboxes to true for advanced debugging, see https://www.princexml.com/doc/cookbook/#how-and-where-is-my-box
6 | * */
7 |
8 | /* eslint-disable no-undef */
9 | 'use strict';
10 |
11 | // Prince.trackBoxes = true;
12 |
13 | const shortname = document.querySelector('h1.shortname');
14 | const version = document.querySelector('h1.version');
15 | const title = document.querySelector('h1.title');
16 |
17 | shortname.innerHTML = restoreSuperScripts(shortname.innerHTML);
18 | version.innerHTML = restoreSuperScripts(version.innerHTML);
19 | title.innerHTML = restoreSuperScripts(title.innerHTML);
20 |
21 | rearrangeTables();
22 |
23 | PDF.pageLayout = 'two-column-right';
24 | PDF.pageMode = 'show-bookmarks';
25 | PDF.duplex = 'duplex-flip-long-edge';
26 | PDF.title = document.title;
27 | PDF.author = 'Ecma International';
28 | PDF.subject = shortname.innerHTML + (version ? ', ' + version.innerHTML : '');
29 |
30 | /**
31 | * Terms and definitions section should not have every term listed in the table of contents.
32 | * */
33 | const terms = document.querySelector('#toc a[href="#sec-terms-and-definitions"]');
34 |
35 | if (terms) {
36 | (terms.parentElement.querySelector('ol.toc') || document.createElement('i')).remove();
37 | }
38 |
39 | function restoreSuperScripts(string) {
40 | if (!string) return false;
41 |
42 | return string
43 | .replace(/(\d)st/, '$1st')
44 | .replace(/(\d)nd/, '$1nd')
45 | .replace(/(\d)rd/, '$1rd')
46 | .replace(/(\d)th/, '$1th')
47 | .replace('®', '®')
48 | .replace('®', '®')
49 | .replace('™', '™')
50 | .replace('™', '™');
51 | }
52 |
53 | /**
54 | * Sets up table captions and figcaptions for tables, which provides for
55 | * continuation table captions.
56 | * */
57 | function rearrangeTables() {
58 | const tables = Array.from(document.getElementsByTagName('emu-table'));
59 |
60 | tables.forEach(emuTable => {
61 | const figcaption = emuTable.getElementsByTagName('figcaption')[0];
62 | const tableCaptionText = figcaption.innerHTML;
63 | const table = emuTable.getElementsByTagName('table')[0];
64 | const captionElement = document.createElement('caption');
65 |
66 | captionElement.innerHTML = tableCaptionText;
67 |
68 | table.insertBefore(captionElement, table.getElementsByTagName('thead')[0]);
69 | table.appendChild(figcaption);
70 | });
71 | }
72 |
73 | /**
74 | * @typedef {Object} PrinceBox
75 | * @property {string} type
76 | * @property {number} pageNum
77 | * @property {number} x
78 | * @property {number} y
79 | * @property {number} w
80 | * @property {number} h
81 | * @property {number} baseline
82 | * @property {number} marginTop
83 | * @property {number} marginBottom
84 | * @property {number} marginLeft
85 | * @property {number} marginRight
86 | * @property {number} paddingTop
87 | * @property {number} paddingBottom
88 | * @property {number} paddingLeft
89 | * @property {number} paddingRight
90 | * @property {number} borderTop
91 | * @property {number} borderBottom
92 | * @property {number} borderLeft
93 | * @property {number} borderRight
94 | * @property {string} floatPosition "TOP" or "BOTTOM"
95 | * @property {PrinceBox[]} children
96 | * @property {PrinceBox} parent
97 | * @property {Element|null} element
98 | * @property {string|null} pseudo
99 | * @property {string} text
100 | * @property {string} src
101 | * @property {CSSStyleSheet} style
102 | * */
103 |
--------------------------------------------------------------------------------
- Can call
abstract operations in this spec:Internal (); - Can call
abstract operations in ES6:ReturnIfAbrupt (completion); - Can call
abstract operations in a biblio file:Biblio (); - Unfound
abstract operations just don't link: Unfound(); - Can prefix with ! and ?.
- A
Record looks like this:Record { [[Key]]: 0 }. - A
List looks like this: « 0, 1 ».
1 Internal Function
18 |2 Refs
21 |Can refer to functions in prose, eg.
Don't autolink references inside square brackets, eg: [[Internal]]. 24 | Likewise, percent things: %%Internal%%. 25 | Likewise, mentions of Internal.foo.
26 |