tc39 / ecmarkup Goto Github PK

ecmarkdown converts

|Initializer_opt|

to

<emu-nt optional>Initializer</emu-nt>

which ecmarkup converts to

<emu-nt optional="">Initializer</emu-nt>

but this is missing

<emu-mods><emu-opt>opt</emu-opt></emu-mods>

Similarly,

|Pattern[U]|

converts to

<emu-nt params="U">Pattern</emu-nt>

which is missing

<emu-mods><emu-params>[U]</emu-params></emu-mods>

Extract code from bterlson/ecmascript, package using bower.

Would be awesome

Here's an idea to get things started:

A promise reject function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal slots.

When a promise reject function _F_ is called with argument _reason_, the following steps are taken:

1. Assert: _F_ has a [[Promise]] internal slot whose value is an Object.
1. Let _promise_ be the value of _F_'s [[Promise]] internal slot.
1. Let _alreadyResolved_ by the value of _F_'s [[AlreadyResolved]] internal slot.
1. If _alreadyResolved_.[[value]] is *true*, then return *undefined*.
1. Set _alreadyResolved_.[[value]] to *true*.
1. Return [RejectPromise](_promise_, _reason_).

<p>A promise reject function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal slots.</p>

<p>When a promise reject function <var>F</var> is called with argument <var>reason</var>, the following steps are taken:</p>

<ol>
  <li><a href="#sec-algorithm-conventions">Assert</a>: <var>F</var> has a [[Promise]] <a href="#sec-object-internal-methods-and-internal-slots">internal slot</a> whose value is an Object.</li>
  <li>Let <var>promise</var> be the value of <var>F</var>'s [[Promise]] <a href="#sec-object-internal-methods-and-internal-slots">internal slot</a>.</li>
  <li>Let <var>alreadyResolved</var> by the value of <var>F</var>'s [[AlreadyResolved]] <a href="#sec-object-internal-methods-and-internal-slots">internal slot</a>.</li>
  <li>If <var>alreadyResolved</var>.[[value]] is <b>true</b>, then return <b>undefined</b>.</li>
  <li>Set <var>alreadyResolved</var>.[[value]] to <b>true</b>.</li>
  <li>Return <a href="#sec-rejectpromise">RejectPromise</a>(<var>promise</var>, <var>reason</var>).</li>
</ol>

Notable:

• _x_ translates to <var>x</var>, not <em>x</em> or <i>x</i>. Variables are by far the most common usage of italics in ES and it makes sense to prioritize them.
• Use * for <b>, not ** or __. (I am not sure if it should be <b>true</b> or <code>true</code>...). The way Markdown allows * and _ to be used interchangeably is a bit annoying and forces you to type two **s and make sure you are consistent throughout the document. We'd be best off reserving double-punctuation for more rare things.
• It automatically regonizes "Assert:" and "internal slot" and auto-links those.
• The syntax [RejectPromise](_promise_, _reason_) tells it to auto-link to RejectPromise. It should be able to automatically figure that out without some kind of anchor; after all #sec-reject-promise was generated from ### RejectPromise ( promise, reason ). This will work best if there are authoring-time tools to check that the auto-linking works correctly.
• I used 1. for steps, but we could use - or even just a leading ..

As I understand it, can only refer to a clause in the document. What if one wants to refer to something other than a clause, e.g., a table?

As reported by Domenic in tc39/proposal-async-await#59:

• Add styling for emu-const
• Remove emu-t right margin when inside normal text.
• Make Completion auto-link appropriately.

Putting an emu-table's caption in an attribute (as opposed to a child element) complicates the story if there's markup in the caption. E.g., in ES6:

• Table 49 --The TypedArray Constructors
• Table 52 -- Iterable Interface Required Properties
• Table 53, 54, 55 -- similarly

(The same goes for markup in the caption of an emu-figure or emu-example, but ES6 doesn't have any examples of that.)

Terseness is an important goal of this proposal. Custom elements help a lot by removing a bunch of boilerplate HTML, but don't go far enough. Markdown, on the other hand, is very terse and readable but doesn't provide any semantic meaning (and may be too complex for our purposes anyway).

After a discussion on IRC with @domenic and @jorendorff, we think we need a shorthand for commonly used ECMAScript entities (see the readme for a list). At the very least, the following:

• Non-terminals. Any non-terminals can automatically be cross-referenced with the definition of that non-terminal.
• Cross references
• Code blocks

Additionally, es-algorithm elements need the following shorthands:

• Local variables
• Algorithm steps

Algorithms also use bold typeface to denote values like this, true, and false but I think this can be the same shorthand as used for code blocks.

es-algorithm will also want to auto-xref references to internal algorithms using a heuristic of somesort (@jorendorff can comment on this)

Proposal So Far

Algorithm steps could use markdown numbering syntax but putting numbers into the source text means adding/removing steps hoses up the diff so perhaps simply using bulleted list syntax would be good.

Open to additional suggestions!

All of the following seems annoying to have to maintain in my source file:

<!DOCTYPE html>
<meta charset="utf-8">
<script src="https://bterlson.github.io/ecmarkup/ecmarkup.js" defer></script>
<link rel="stylesheet" href="https://bterlson.github.io/ecmarkup/elements.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/solarized_light.min.css">

Should Ecmarkup generate these for me? It already generates <title> I noticed.

I guess it kind of gets away from the custom elements idea. (A custom element could generate the script and link elements, but doctype and meta charset would need to stay.)

Now that ecmarkdown has a grammar, ecmarkup's README.md should be clearer about what kind of ecmarkdown content is allowed/reasonable in ecmarkup elements.

For instance, ecmarkdown says:

Ecmarkup has an <emu-alg> element within which Ecmarkdown numeric lists can be used

which suggests that the content of an <emu-alg> is parsed as an ecmarkdown OrderedList. Is that the case?

Presumably the content of <emu-{intro,clause,annex,note}> is parsed as a Document. (In which case, is there much need for <emu-alg>?)

Then there are the "smaller" elements, like <emu-xref>, <h1>, and <td>. Is their content submitted as such to ecmarkdown, or are such elements (angle brackets and all) just part of a bigger submission? E.g., if I write

<emu-clause id="test">
  <h1>The `this` keyword</h1>

  See <emu-xref href="#foo">the `that` keyword</emu-xref>, please.
</emu-clause>

then is

  <h1>The `this` keyword</h1>

  See <emu-xref href="#foo">the `that` keyword</emu-xref>, please.

parsed (all at once) as an ecmarkdown Document? (Relying on the fact that the HTML tags will simply pass through unchanged.) As opposed to separate invocations for just the text content:

"\n      "

"The `this` keyword"

"\n\n      See "

"the `that` keyword"

", please.\n    "

I was wondering why the 'aoid' attribute was allowed on both emu-clause and emu-alg. Was there a particular situation you had in mind where you'd want to link to an emu-alg rather than an emu-clause?

(Also, in the description for emu-alg, it says "A unique name identifying this clause", but "clause" should presumably be "algorithm" or "element".)

ES2015 & Intl 2015 follow a naming convention for Well-Known Intrinsics that involves using an underscore, for example:

• Array.prototype.values => %ArrayProto_values%
• Date.now => %Date_now%

Currently ecmarkup ignores an escape and renders text that follows with emphasis

In streams, which is heavily promise-based, there are a lot of abstract operations that cannot throw. The ES spec has these too, in smaller number.

Of course, this kind of nothrow vs. throw characteristic can be contagious. If you only use nothrow abstract ops in your abstract op, then your abstract op is nothrow. Whereas if you use any throwing ops, you are now throwing.

We found in whatwg/streams#366 that it was much easier to trace potential exception flows if we used "Perform AbstractOp(x)" for nothrow ops, and "Let result be AbstractOp(x); ReturnIfAbrupt(result)" or similar for throwing ops. The ES spec uses "Perform" for a similar purpose, although it doesn't define it. I defined it in https://streams.spec.whatwg.org/#conventions

We are considering taking this a step further by notating every abstract op with "nothrow" or "throws" badges: whatwg/streams#371 I think it would be ideal if Ecmarkup supported this, e.g. <h1 aoid="..." nothrow>...</h1>.

The actual project of going through the entire ES spec and updating them with such notations would be ... work. But I think it could be very valuable, and helped along by work such as that @anba has done in the past. On top of such notations, you could even build automated checker tools to enforce the contagion rules, or to enforce the use of ReturnIfAbrupt.

WDYT?

My input html has

<p>1 &lt; 2</p>

and the output ends up being

<p>1 < 2</p>

See e.g. https://littledan.github.io/simd.html#simd-extract-lane. TOC contains "5.2 _SIMD_Constructor" but if you click the link it goes to a heading which is nicely italicized.

Within 20.3.1 ("Overview of Date Objects and Definitions of Abstract Operations"), many of the abstract operations are defined, not with a series of algorithmic steps, but with an equation (single-line or multi-line). For example, see 20.3.1.3 ("Year Number"): http://www.ecma-international.org/ecma-262/6.0/#sec-year-number

Should ecmarkup have a particular way to mark these up? E.g. something analogous to emu-alg:

    <emu-eqn>
        DaysInYear(_y_)
            = 365 if (_y_ modulo 4) != 0
            = 366 if ...
            ...
    </emu-eqn>

(Currently, over at es-spec-emu, such definitions mostly just inherit the markup they have in the HTML ES6 spec: <p class="normalBullet">DaysInYear(_y_) <br> = 365 if (_y_ modulo 4) &ne; 0 <br> ...</p>)

Let's continue the discussion from tc39/ecmarkdown#38

<emu-clause>
<h1>Foobar</h1>

Baz
</emu-clause>

The result has an empty body and just a heading.

<emu-biblio href="main-spec.json"></emu-biblio>
<emu-biblio href="other-strawman.json"></emu-biblio>

main-spec.json sample:

{
  "http://people.mozilla.org/~jorendorff/es6-draft.html": {
    "abstract operations": {
      "Get": "#sec-get-o-p"
    },
    "phrases": {
      "abrupt completion": "#sec-completion-record-specification-type"
    }
  }
}

Then <emu-alg> gets autolinked based on these. Unsure about <p>s.

Running ecmarkup v2.0.1 on

<emu-clause>
<h1>blah</h1>
<p>U+200C (ZERO WIDTH NON-JOINER) is abbreviated "&lt;ZWNJ&gt;"</p>
</emu-clause>

yields (in part):

<p>U+200C (ZERO WIDTH NON-JOINER) is abbreviated "<zwnj>"</zwnj></p>

@littledan mentioned this today and it's a great idea.

One benefit is that if you don't shut down the process, you can avoid the jsdom-require startup costs.

Here's a quick start; needs some hacking to remove the bikeshed stuff. https://github.com/whatwg/streams/blob/master/local-watch.js

Optional cool feature: insert live reload script tag and use websockets to communicate with it. I understand this is pretty easy to drop in these days.

Algorithm steps are littered with ReturnIfAbrupt calls. @wycats proposes a shorthand that could be compiled to ECMASpeak without too much difficulty: https://gist.github.com/wycats/1b829d55d1fdb97d8762.

Should highlight syntax inside pre tags based on a language attribute.

<emu-copyright>2015</emu-copyright>

Would add the following to a specification document:

Ecma International
Rue du Rhone 114
CH-1204 Geneva
Tel: +41 22 849 6000
Fax: +41 22 849 6001
Web: http://www.ecma-international.org
COPYRIGHT NOTICE

© 2015 Ecma International

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:

(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),

(ii)    works which incorporate all or portion of this document for the purpose of incorporating features that provide accessibility,

(iii)   translations of this document into languages other than English and into different formats and

(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.

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.

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.

The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or assigns.

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."

Software License

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 http://www.ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS*.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. 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.

3. 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.

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.

The following two blocks work fine:

<pre class="metadata">
title: String.prototype.padLeft / padRight
stage: 1
contributors: Jordan Harband
</pre>

<pre class="metadata">
  title: String.prototype.padLeft / padRight
  stage: 1
  contributors: Jordan Harband
</pre>

However, the following block, which is indented with \t:

<pre class="metadata">
    title: String.prototype.padLeft / padRight
    stage: 1
    contributors: Jordan Harband
</pre>

prints the following warning:
[2015-09-30T22:50:02.743Z] Warning: metadata block failed to parse [2015-09-30T22:50:02.749Z] Warning: Contributors not specified, skipping copyright boilerplate. Specify contributors in your frontmatter metadata.

Current implementation is backward.

https://wiki.php.net/rfc/combined-comparison-operator puts the TOC in a sidebar. That's kind of nice. It would be nicer if it floated (position: fixed basically). And maybe highlighted the section you were in.

I think Ecmarkup documents should be able to have this. Probably makes the most sense for smaller proposals but maybe it'd scale to the larger spec.

If I add

<pre class="metadata">
contributors: Domenic Denicola
</pre>

to https://github.com/tc39/Array.prototype.includes/blob/011759c0a1385ff12f9c4f8aadb12be56afd3a30/spec.html after <meta charset="utf-8">, I get the error

$ node_modules/.bin/ecmarkup spec.html out/index.html
Error: Clauses cannot follow annexes
    at Object.next (C:\Users\Domenic\Dropbox\GitHub\tc39\Array.prototype.includes\node_modules\ecmarkup\lib\clauseNums.js:10:36)
    at Spec.getNextClauseNumber (C:\Users\Domenic\Dropbox\GitHub\tc39\Array.prototype.includes\node_modules\ecmarkup\lib\Spec.js:236:27)
    at new Clause (C:\Users\Domenic\Dropbox\GitHub\tc39\Array.prototype.includes\node_modules\ecmarkup\lib\Clause.js:36:26)
    at Spec.buildAll (C:\Users\Domenic\Dropbox\GitHub\tc39\Array.prototype.includes\node_modules\ecmarkup\lib\Spec.js:119:17)

It disappears if I add copyright: false

In the editorial conventions section, in the last row of "Table 4: Inline styles/conventions", it describes "Non-terminal references" and defines the "Ecmarkup Functionality" as <emu-xref id="#prod-FunctionExpression"></emu-xref>. However, on the Ecmarkdown readme it says that nonterminals are written as |x| and translate to <emu-nt>x</emu-nt>.

This looks like a contradiction to me. Is the 4th line of Table 4 incorrect in using <emu-xref> as the output? Or is there something I'm not understanding here?

http://services.w3.org/htmldiff is OK except it disallows "invalid" (custom) elements.

http://www.w3.org/wiki/HtmlDiff contains a good list of possibilities

An example output is http://services.w3.org/htmldiff?doc1=https%3A%2F%2Frawgit.com%2Fwhatwg%2Ffetch%2F53c071b078bf345aaad7e9cbf2d1d425d53c82ef%2FOverview.html&doc2=https%3A%2F%2Ffetch.spec.whatwg.org%2F (example section with a few inline changes)

There are clauses that define multiple abstract operations, which the 'aoid' attribute doesn't (appear to) allow for. E.g. 20.3.1.2 "Day Number and Time within Day" defines Day(t) and TimeWithinDay(t), and the HTML ES6 spec links uses of those abstract operations back to that clause.

Moreover, that clause also defines msPerDay, which is a 'spec constant', not an abstract operation, but the HTML also links uses of that constant back to that clause.

Even more generally, the HTML also links certain phrases like "bound function" and "internal slot".

So I'm thinking it might be useful to generalize the 'aoid' attribute into something that gives a list of all the things (operations, constants, phrases, whatever) defined by an emu-clause. (Or at least, all the things whose uses should be auto-linked back to that section.)

_opt_.[[_<key>_]] is producing opt_.[[_<key>]]

Based on an off-line discussion, I thought that

<emu-clause>
<h1>Foo</h1>
Bar

Baz
</emu-clause>

might at some point result in <p> tags around Bar and Baz. Instead, it seems that, as of v2.0.3, while the parser doesn't complain (an improvement!), it just passes the whitespace through as-is, without creating paragraphs.

In the documentation, when the "Imports" section refers to "HTML Imports", do you mean elements of the form <link rel="import" href="external.html">? If so, such elements are restricted (in conforming HTML documents) to the document's <head> element, which is not where you want to inline the content of an external document.

Given that "HTML Imports are treated specially in an ecmarkup document", maybe ecmarkup should instead have a custom element for the purpose, e.g. <emu-include> or <emu-inline>.

http://tc39.github.io/ecmascript-asyncawait/#AsyncFunctionDeclaration-static-semantics could be prettier:

Some ideas (brainstorming):

• Don't allow breaking in component parts, e.g. "[no LineTerminator here]" should always stay on one line.
• New line and indent after the colon?
• Turn off linebreaking entirely? (Be careful this doesn't break mobile.)
• Try to make line breaks consistent, either by the author inserting them or by some heuristic? E.g. a line break before each of "function" and "{AsyncFunctionBody}" might work.
• Change the font or font color or...?

The introduction says:

Ecmarkup offers the following conveniences:
Ecmarkdown syntax in most elements.

It should probably be more specific.

For example, consider a paragraph:

  blah blah blah
  ~Atomics~ foo bar baz

There is no space at the end of the first line (though there are some spaces at the beginning of the second). The markup will then be something like this:

blah blah blah<emu-const>Atomics</emu-const> foo bar baz

with a space missing before the emu-const markup. Adding a space at the beginning of the first line fixes this but is unpleasant.

From @allenwb's feedback on Array.prototype.includes:

The ECMA rule is that within a sub-clause, multiple notes must be numbered.

This is true in the Word/PDF versions, but not in the HTML version or Ecmarkup output. Probably should fix.

I feel like I'm missing something obvious, but I find no mention of unordered lists in http://bterlson.github.io/ecmarkup/

This fails with the error "Unhandled rejection SyntaxError: Expected "*", "<", """, "_", "`", "|", "~", [^\n] or end of input but "\n" found."

<p>
  - The _options_ property localeMatcher in all constructors and supportedLocalesOf methods.
  - The _options_ properties usage and sensitivity in the Collator constructor.
  - The _options_ properties style and currencyDisplay in the NumberFormat constructor.
</p>

Attempting to "cheat" or "hack" my way around using <emu-alg> fails with the error "Unhandled rejection TypeError: Cannot read property '1' of null"

<emu-alg>
  - The _options_ property localeMatcher in all constructors and supportedLocalesOf methods.
  - The _options_ properties usage and sensitivity in the Collator constructor.
  - The _options_ properties style and currencyDisplay in the NumberFormat constructor.
</emu-alg>

The latter definitely makes sense, but the former not-so-much.

I also expect that markdown just isn't allowed like that, which is fine, I just want to verify. I'd love to not have to <p> all the time, but any \n seems to fail.

Help?

Many times an abstract operation ID will be identical to the clause ID that defines it. I propose

<emu-clause id="foo" aoid>

be equivalent to

<emu-clause id="foo" aoid="foo">

[I'm not sure if this is an issue with ecmarkup or grammarkdown.]

From ES6 B.1.3, the production:

SingleLineHTMLOpenComment ::
  `<!--` SingleLineCommentChars?

is translated into an <emu-production> containing:

<emu-t><!--</emu-t>

which opens up an HTML comment that swallows up the next few productions.

In Table 3, the distinction between star/emu-val and backtick/code is unclear. E.g., given the example of putting 'Function.prototype' in backticks, it seems like it would also be reasonable to put 'TypeError' in backticks, but we have the example of putting 'TypeError' in stars. Are they both valid, depending on context? If so, can you explain when one should use one vs. the other?

It doesn't seem to be recognized by ecmarkup as optional. For example: http://rbuckton.github.io/grammarkdown/typescript.html#EnumDeclaration

The const terminal should be marked with _opt.

Ron

https://resources.whatwg.org/file-issue.js

In action: https://url.spec.whatwg.org/ or other specs

Would be great to be able to report issues easily in Ecmarkup specs.

<emu-xref id=#foo-bar-baz></emu-xref> should by default be filled in with the sec num of the target.

As discussed recently in the web components spec repo, HTML imports are not the same as HTML includes. But Ecmarkup uses them as the latter.

I'd suggest instead introducing an <emu-include href="..."> element. I'd further suggest that the post-processed version not be a simple replacement, but instead nest all the appropriate child content underneath the <emu-include> node. This latter because it's more like what would actually happen with a custom element, I think.

In the spec, when Type(x) appears, "Type" links to http://www.ecma-international.org/ecma-262/6.0/#sec-ecmascript-data-types-and-values. Can ecmarkup link that too?

Seems like a good idea in general, and in particular I'd find it a useful workaround for integrating with Bikeshed which recognizes <pre is="emu-alg"> as "do not touch this" but does not recognize <emu-alg> as such.

This came up in the context of issue #43, but I think it deserves its own ticket: Preserving more line breaks from the input in the output would be helpful, as it makes diffing the output with its previous version(s) more meaningful. As it is, when I have a bulleted list (say) it is run together as one very long line in the output, making it effectively meaningless to "git diff" it.

On a closely related note, the markup that is generated for the TOC should have meaningful line breaks, for the same reason.

Since it's redundant to specify both <title> and a metadata title:, when both are present, ecmarkup should ideally error out and instruct me to remove one.

Alternatively, it should stop supporting both, and force one method of specifying the title.

In ecma402, we have a lot of examples within the spec. e.g.:

Should we add something very similar to <emu-note /> for this?