Skip to content

Issue #397 - Make sur all IDL terms have <dfn> in prose - #403

Merged
markafoltz merged 2 commits into
w3c:gh-pagesfrom
tidoust:issue-397-dfn
Jan 5, 2017
Merged

markafoltz merged 2 commits into
w3c:gh-pagesfrom
tidoust:issue-397-dfn

Conversation

@tidoust

@tidoust tidoust commented Jan 3, 2017

Copy link
Copy Markdown
Member

Done:

  • All IDL terms now have <dfn> in prose
  • Added "simple" constructor logic for custom Events to clarify how EventInit dictionary members are to be used
  • Added missing reference to Web Messaging spec (which defines MessageEvent)
  • Linked terms to definition throughout the spec
  • Improved support for linking to methods with parentheses, e.g. start(), reconnect()
  • Occurrences of "presentation" that should link to "controlling browsing context" now effectively link to it
  • Occurrences of "Presentation" that should link to the IDL definition now effectively link to it

Notes:

  • There is simply no way to define an idiom "presentation" and an interface "Presentation" using ReSpec without running in all sorts of linking issues. I've hardcoded "presentation" (as an idiom) links as a workaround. Not perfect, but at least it works!
  • Some definitions are not real definitions (e.g. BinaryType is merely defined as the type of the binaryType attribute), but they do not seem to warrant proper definitions.
  • Description of custom events constructors could be turned into real algorithms but that seems straightforward enough not to require crisper language.

Done:

- All IDL terms have <dfn> in prose
- Added constructor logic for custom Events
- Added missing reference to Web Messaging spec
- Linked terms to definition whenever possible
- Improved support for linking to methods with parentheses: "start()"
- Occurrences of "presentation" that should link to "controlling browsing context" now effectively link to it
- Occurrences of "Presentation" that should link to the interface definition now effectively link to it

Notes:

- No way to define an idiom "presentation" and an interface "Presentation" using ReSpec, so "presentation" (as an idiom) links are hardcoded
- Some definitions are not real definitions (e.g. BinaryType is merely defined as the type of the binaryType attribute), but they do not seem to warrant proper definitions.
- Description of custom events constructors could be turned into real algorithms but that seems straightforward enough not to require crisper language.
@markafoltz

markafoltz commented Jan 3, 2017 •

Copy link
Copy Markdown
Contributor

Can ReSpec be modified to use <code> to link IDL terms and <a> to link idioms?
Otherwise, could a script snippet be added to add links automatically to <a>presentation<a>?

@tidoust

tidoust commented Jan 4, 2017

Copy link
Copy Markdown
Member Author

Can ReSpec be modified to use <code> to link IDL terms and <a> to link idioms?

I suppose that's something you could propose to ReSpec maintainers.
I note that, in our case, having an option to make ReSpec respect case sensitivity (especially for IDL terms) would be enough, and perhaps an easier sell. There's an open issue on case insensitivity in particular:
https://github.com/w3c/respec/issues/893

Otherwise, could a script snippet be added to add links automatically to <a>presentation<a>?

Well, it's code, anything is possible :) We should be able to attach to ReSpec events and run some magic before it gets confused in particular. I doubt I'll have time to look into it within the next couple of weeks though, as I'll be traveling here and there. Feel free to give it a shot.

@markafoltz

Copy link
Copy Markdown
Contributor

This looks fine and thanks for improving this @tidoust. If maintaining the linking for the presentation idiom is a hassle we can look at more automated solutions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants