replacement for conf.definitionMap?

[gkellogg]

Important info

• URL to affected spec: https://w3c.github.com/json-ld-syntax
• ReSpec version: 24.1.0
• I did a "hard refresh", but it's still busted.

Description of problem

#1954 removed definitionMap from the configuration. This is used in my specs to iterate over definitions and remove those that aren't referenced; it's now broken.

Is there a replacement mechanism for me to do this using pubsub or something similar?

What happened (e.g., it crashed)?:

Developer console complains TypeError: undefined is not an object (evaluating 'respecConfig.definitionMap[item]')

But what I was expecting?: A means to iterate over definitions. The code also still depends on jQuery for makeID.

Optional, steps to reproduce:

1. Load, for example, https://w3c.github.com/json-ld-syntax
2. Note developer console message

[marcoscaceres]

Oh whoops. Should be easy to fix as we do export the the definition map.
https://github.com/w3c/respec/blob/develop/src/core/dfn-map.js#L4

In theory, it should be:

  require(["core/dfn-map"], ({definitionMap}) => {
    // do stuff.
  }); 

But for some reason it's not working for me. @saschanaz, any ideas from recent changes?

[saschanaz]

But for some reason it's not working for me

The require() function is now whitelisted because 1) webpack doesn't expose require() so we manually implemented a tiny replacement 2) exposing everything will prevent tree shaking optimization, and 3) we just shouldn't expose every internal things...

This is used in my specs to iterate over definitions and remove those that aren't referenced

Is that to suppress warnings?

[marcoscaceres]

Is that to suppress warnings?

@gkellogg can correct me, but I believe they import a HTML file with definitions that they use across many spec (and then cull the ones that are not used).

[marcoscaceres]

Might be worth us looking at what the following script does:
https://w3c.github.io/json-ld-syntax/common/common.js

And seeing if any of that stuff can become part of core. Or, at least figure out a good way to expose things people are using.

[saschanaz]

A quick fix is to add expose("core/dfn-map", { definitionMap }); in core/dfn-map.js which will enable require(["core/dfn-map"], ...). IMO we should avoid adding such AMD API, though...

[marcoscaceres]

Agree about not adding that... what are some alternatives? Should we temporarily again expose conf.definitionMap while we figure this out? That will at least fix the existing spec and let us come up with something cleaner.

[saschanaz]

Yes, that will give us some time. #1976 is my suggestion, BTW.

[marcoscaceres]

I like where #1976 is going. We should pick that back up.

[gkellogg]

There are different things in https://w3c.github.io/json-ld-syntax/common/common.js besides the support for managing definition lists, the important parts is the following:

https://github.com/w3c/json-ld-syntax/blob/6f92b1d634760cd7a393b41bce01e151bfd753f0/common/common.js#L15-L115

This is based on code originally created by @halindrome (IIRC) but used in a number of projects where multiple specs share definitions. It's quite dependent on the use of definition lists (dl) to determine if definitions are used outside of the scope of the definition itself. Abstracting this for definitions in general would be difficult using this approach.

A better solution might be to introduce something like a data-dfn-scope attribute, to separate the definition from the use. Then, you could determine if uses are inside or outside of the scope, and (optionally) remove all elements having a data-dfn-scope matching the unused definition. I think this would be broadly useful, and would simplify editors dependence on ReSpec internals.

For example, the definition found at https://github.com/w3c/json-ld-syntax/blob/6f92b1d634760cd7a393b41bce01e151bfd753f0/common/terms.html#L66-L69 might instead be the following:

<dt data-dfn-scope="absolute IRI"><dfn>absolute IRI</dfn>
<dd data-dfn-scope="absolute IRI">An <a data-cite="RFC3987#section-1.3" class="externalDFN">absolute IRI</a>
    is defined in [[RFC3987]] containing a <em>scheme</em> along with a <em>path</em>
    and optional <em>query</em> and fragment segments.</dd>