tc39 / ecmarkdown Goto Github PK

Currently this project exports a function for processing a full document, and does not export functions for processing anything else. The last release had functions for processing both full documents and fragments.

But the canonical way to process a full document is with ecmarkup, and ecmarkup only uses this project for processing fragments (like <p>in _this |Example|</p>) and algorithms. It might make sense to have exports for exactly those cases, and nothing else.

Sorry for opening a new issue again...

Please re-tag the new version of this npm module in this upstream, since I made some changes in #85...

Regards,

Vivek K J

In particular, use CMD's way of handling indentation/nesting of lists, and its way of starting a list with the first number. (That is, at least have lists composed of all 1s, not all 0s.)

Example: http://people.mozilla.org/~jorendorff/es6-draft.html#sec-static-semantics-coveredparenthesizedexpression

Ideas:

• |ParenthesizedExpression[Yield]|
• {ParenthesizedExpression[Yield]}
• /ParenthesizedExpression[Yield]/
• *ParenthesizedExpression[Yield]*
• [ParenthesizedExpression[Yield]] ???

Pretty sure it suffices to just escape & to & and < to < since we are not in an attribute context.

I'm on the fence ... seems like potentially more trouble than they're worth. But maybe it's OK, given that any other usage of ' and " should be inside code blocks?

Instead, smart quote them (#17).

Needed to avoid tc39/ecma262#1835 from happening again.

Proposed syntax:

Allow <label_name>: in ordered lists, where <label_name> matches the regular expression:

^[a-zA-Z_$][a-zA-Z0-9_$]*$

Example:

<emu-clause id="sec-assertfoo" aoid="AssertFoo">
	<h1>AssertFoo( _val_ )</h1>

	<p>The AssertFoo algorithm ensures that _val_ is an object with an [[IsFoo]] internal slot, by only returning in <emu-xref aoid="AssertFoo" step="Is_Foo_$1"></emu-xref>.</p>

	<emu-alg>
		1. Assert: Type(_val_) is Object.
		1. If ? _val_.[[IsFoo]] is *true*
			Is_Foo_$1:
			1. Return _val_
		1. Throw a *TypeError* exception.
	</emu-alg>
</emu-clause>

[step Is_Foo_$1] would be replaced with an anchor link linking to the labeled step with the HTML step ${num}, where ${num} is the number of the step.

See also:

• tc39/ecmarkup#192

Something changed since v3.19.1 broke rendering of ECMA 402: tc39/ecma402#450

New versions stop parsing after encountering double newlines as encountered at https://github.com/tc39/ecma402/blob/334b79ecacbb5283c27c968abf17e9235187acad/spec/overview.html#L31-L32 .

• Should be able to put a backslash before any punctuation and not have it show up in the output
• Verify that you can use backslashes to disable Ecmarkdownification of all grammar productions
• Make sure double-backslash translates to backslash correctly

Mapping ecmarkdown inline marks to semantically meaningful ecmarkup tags seems like a desirable goal. Thus, I propose:

Lists are written as a series of lines, each starting with either a number, e.g. 1., or a star, e.g. *.
The first list item's number determines the starting number in the output (via <ol start="x">);

The latter feature can handle algorithm fragments such as those in

• 7.1.12.1 (alternative step 5) and
• 9.3.2 (alternative step 9)

However, consider the fragments in

• 20.1.3.2 (alternative step12.b.i) and
• B.3.5 (alternative step 5.d.ii.2.a.i)

where the step(s) of the fragment are labelled by roman numerals, not decimals. Could a feature be added to handle such cases?

I suppose it might have to be added to ecmarkup, e.g. <emu-alg type="i"> (converting to <ol type="i">).

Hi there,
Please tag the npm version (i.e. 6.0.0) of this module in this upstream repo.. we want to pack this awesome npm module to debian, so please do as soon as possible,

Regards,
VIVEK K J
www.vivekkj.me
Debian Community

This would be the first step for building an "emdfmt" tool that reformats your Ecmarkdown exactly how I like it.

As a bonus, I suppose you'd want to re-build the HTML outputter as an AST visitor.

If my input consists entirely of line breaks, perhaps just return the string verbatim?

Hi there,
I am VIVEK K J from Debian community... I was just trying to make a package of ecmarkdown to Debian and while I tried to do that, I faced some errors due because of this module is using the old version of js-beautify as a dev dependency. I just changed the version of js-beautify in package.json to latest in #84 , because the version previously used is not packaged in Debian and not maintained more... I run mocha test and everything is fine. So please merge that pull request...

Regards,

VIVEK K J,
Debian JavaScript Packaging Team,
www.vivekkj.me

/cc @bterlson @jorendorff

The current list design (0. prefix; 2 space indents) is the result of tc39/ecmarkup#3.

In #4 @tabatkins points out that CommonMark has lists start at the number that appears in the source, instead of always starting at 1. I don't think we want to allow freedom in list construction, but there is an argument for using 1. instead of 0..

A second, and related question. Currently we go with 2-space indents per the linked issue. IMO this looks a little weird since the 0. for a nested list actually lines up with the space from the above list. Compare 2-space, 3-space, and 4-space indents:

0. Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
0. ReturnIfAbrupt(_hasReturn_).
  0. If _hasReturn_ is *true*, then
    0. Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
    0. If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
      0. Return _innerResult_.
0. Return _completion_.

0. Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
0. ReturnIfAbrupt(_hasReturn_).
   0. If _hasReturn_ is *true*, then
      0. Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
      0. If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
         0. Return _innerResult_.
0. Return _completion_.

0. Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
0. ReturnIfAbrupt(_hasReturn_).
    0. If _hasReturn_ is *true*, then
        0. Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
        0. If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
            0. Return _innerResult_.
0. Return _completion_.

The most natural is 3 space indents... or we could come up with another delimiter that makes 2-space indents work. Maybe just .? Or drop the prefix altogether and let it be entirely done with indentation? This latter looks like

Let _hasReturn_ be HasProperty(_iterator_, `"return"`).
ReturnIfAbrupt(_hasReturn_).
  If _hasReturn_ is *true*, then
    Let _innerResult_ be Invoke(_iterator_, `"return"`, ( )).
    If _completion_.[[type]] is not throw and _innerResult_.[[type]] is throw, then
      Return _innerResult_.
Return _completion_.

As noted in tc39/proposal-temporal#2290 (review) :

The sticky highlighting becomes less useful [for Record fields than for aliases]. When auditing the uses of BalanceDuration, for example, I found it a lifesaver to be able to highlight years, months, weeks, days, etc. in different colors. If they become durationFieldsRecord.[[Years]] etc., that's no longer possible.

I think fields and slots should participate in interactive highlighting, or at least be eligible, which requires them to have distinct parse nodes here.

As of f7da496 this bug has manifested. Not a big deal since documents should probably have a newline but worth fixing.

Currently it's only lists, but we can probably make this work for paragraphs too.

This is going to give my grammar skills a workout

People are constantly getting this wrong, e.g. https://lars-t-hansen.github.io/ecmascript_sharedmem/shmem.html uses spec-level constants for undefined, RangeError, etc.

README.md has some inconsistencies with respect to the ecmarkup document:

-- It refers to the elements <emu-val> and <emu-const>, which are not defined.

-- It has examples of <emu-nt> with the attribute params, but the ecmarkup doc says Params with a capital 'P'.

ecmarkdown converts, e.g.

  <p>__proto__</p>

to

  <p><var></var>proto__</p>

ecmarkdown should know that a variable can't have an empty name, and thus that an underscore immediately followed by another underscore can't be the start of an UnderscoreFormat.

And similarly with other format-characters*, though none of them occurs doubled in the ES6 spec. Or at least, not in a context that triggers this behavior.

(*Actually, <p>||</p> causes ecmarkdown's parser to throw a TypeError.)

I.e. does combining code, variables, and values behave as expected?

I don’t know if this is an issue of ecmarkdown proper or an interaction with some pre- or post-processing.

When working on the ES spec, I've noticed that the following code will not work as expected:

<emu-grammar>A :: `<!`</emu-grammar> 
<emu-grammar>A :: `&lt;!`</emu-grammar> 
<emu-grammar>A :: `&lt;&#x21;`</emu-grammar> 

It works when double-encoding one of the characters:

<emu-grammar>A :: `<&amp;#x21;`</emu-grammar> 
<emu-grammar>A :: `&amp;lt;!`</emu-grammar>

That makes very cumbersome to output the <! token in a grammar.

var emd = require('ecmarkdown');
var s = Date.now();
emd.paragraph('hello')
console.log("Took: " + (Date.now() - s))

On my machine this takes ~250ms on average, which seems excessive. Subsequent calls are very fast, however.

• Allow intra-word variables, e.g. _SIMD_Constructor
• In particular make _SIMD_Constructor or _foo_ work as expected

  * foo
* bar

will throw a parse error because the bar list item is dedented past the origin list item.

I had the following md:

1. abc
  <!-- comment -->
  1. def

And I get the error message:

Possibly unhandled SyntaxError. Expected "  " or [0-9] but "<" found.

The README.md needs to say what constitutes the start/end of a 'segment'. (Presumably newlines are involved.)

There are many unordered lists in the spec. This would be helpful.

See also tc39/ecmarkup#22.

Non-terminals can be optional and can also have many parameters. I suggest the following syntax:

|NonTerminalName|
|NonTerminalName_opt|
|NonTerminalName[Parameter1]|
|NonTerminalName[Parameter1, ?Parameter2]_opt|

Generally, Non-terminal name, followed by an optional ParameterList (which itself is a comma separated list of parameters surrounded by brackets, where parameters may be prefixed with a ?), followed by an optional "_opt" suffix.

_opt implies an optional non-terminal, Parameter1 is a parameter, and Parameter2 is a parameter whose value is dependent on the occurrence of the parameter in the current LHS.

This aligns with the current typographic practices of the document, though you could argue that _opt should come before the parameter list. I see no reason to do this.

We should handle Windows line endings somehow, either by explicitly supporting them in input (though presumably outputting them as just '\n') or (my preference) explicitly disallowing them, with a useful error message.

I hear @rwaldron wants a link syntax nicer than <a href>. Let's figure that out.

Directly borrowing CommonMark link syntax has a few problems in my opinion. In order from worst to least-bad, they are:

• [[internalSlot]] (parenthetical note) or O.[[InternalMethod]](arg) ends up as a link, which is not desirable.
• Internal links are common; external links are uncommon. Internal links often want auto-generated text (emu-xref style). Markdown requires text inside the brackets. We should have a syntax that fits with these needs better.
• The whole forward-reference model where you can do [x][y] or [x][] or similar, with [y]: ... or [x]: ... defined "later", is way complicated to implement and gives too many options.

Instead I propose the following:

• For external links, continue using <a href>. Specs should not have many of these.
• For "internal" links (including references to things in the biblios), we have a Markdown-inspired syntax for generating <emu-xref>s. My first pass:
  • [#](id-of-thing) => <emu-xref href="#id-of-thing"></emu-xref>
  • [!](id-of-thing) => <emu-xref href="#id-of-thing" title></emu-xref>
  • [any other characters](id-of-thing) => <emu-xref href="#id-of-thing">any other characters</emu-xref>
  • Except that "any other characters" cannot start with [ (at least, not without escaping).
• No forward references, and I'd say don't allow any spaces between ] and (.

I have no strong feelings on this syntax; [#] and [!] are arbitrary and chosen for brevity, but we could do other things like maybe ##(id-of-thing) and !!(id-of-thing), or choose other characters, or whatever. We could use different syntax that looks a bit less like Markdown so that people don't try to put URLs in the parens. We could use #id-of-thing instead of id-of-thing. We could use biblioname#id-of-thing for external references if we don't want to require unique IDs across referenced specs. Discuss!

Note also that we want tc39/ecmarkup#24 for this to be fully useful.

http://people.mozilla.org/~jorendorff/es6-draft.html#sec-ecmascript-language-types-number-type makes the case that NaN is produced by the program expression NaN.

Is this distinction really useful? Or could we use NaN everywhere? (Similarly 0, +Infinity, TypeError, etc.)

If we wanted to prefer typographic compatibility with the existing document we could list a set of "code strings" that always get bolded instead of monospaced.

In an emu-clause, if there is a blank line after the h1 tag, the initial text in that section is omitted.

If an Ecmarkup embedder is just going to beautify afterward anyway, it'd be a shame to slow things down for no real purpose.

In the latest draft Allen updated the convention for "List literals" to use «‍x» instead of (x).

To make this easier to type we might want to let people type it as ASCII and convert it to the correct Unicode characters.

Looking through the ES spec, the only times code font is used in algorithm steps is for strings. And, it seems, all quoted strings are in code font. So we could auto-wrap "x" into <code>"x"</code> instead of requiring the author to type "x"?

The spec also uses code font for some intro sentences and notes (e.g. "The bind method..."). So if we have ambitions of using Ecmarkdown for those (which is probably a good idea) we'd want to keep backticks around. But we could still take care of strings automatically...

@bterlson I did my best to update them but they might benefit from some tweaking.

Tag tokens are appended to text nodes. Seems like the emitter should get to handle tags separately from text so we should fix this.

Like http://spec.commonmark.org/dingus/ basically. I can do this.

Currently the ES spec has a few rare cases where a sans-serif font is used. So far I can only find it used for "spec constants" like completion types (example of throw) or empty (example).

I propose |empty| for this. Alternately, we could just make them values, i.e. use bold instead of sans-serif? @allenwb, any thoughts on what the sans-serif is supposed to signify as opposed to the bold, and whether it's worth keeping around?