add support for <emu-example>

[caridy]

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

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

[domenic]

I'd suggest <emu-note label="Example"> maybe? It's a similar non-normative note, just with a different label.

[caridy]

Yeah, that's better. Only two notes:

• In some cases, we have more than one example per clause.
• example entries have their own counter

[domenic]

Maybe then <emu-note type="example"> where type defaults to note and each individual type gets its own counter.

[caridy]

👍

[bterlson]

Sounds good, I will add this (also add a type of "todo" which I've wanted!)

@caridy you have use for

yet? :-P

[caridy]

ah, todo is another good one... needed for the loader document.

As for <figure>, I have this today:

      <figure>
        <figcaption><span id="table-3">Table 3</span> &mdash; Components of date and time formats</figcaption>
        <table class="real-table">
....

I copied that markup from 262 to try to have the proper style for 402 tables, but I'm not sure this is the right way to do it.

[caridy]

btw, when cross linking to tables defined like that, I'm getting warnings like this: Warning: can't find clause with id #table-3, I suspect that since this is not an emu tag, it will not add the id to the biblio.

[domenic]

Hmm, note that <table>s can have <caption> as a child to give them a caption... figure/figcaption is reasonable though. The wrapping span with manually-updated table numbering sounds horrific... emu should ideally take care of that for you somehow.

[bterlson]

xrefs currently only work well with clauses. The rest is tracked by #24.

Yes, emu should support figures and tables natively for numbering purposes. Today tables and figures (images) are numbered separately. Is it reasonable to say figures with any table children are table figures (labeled/xref'd as "Table n", globally indexed) or otherwise just plain figures (labeled/xref'd as "Figure n", globally indexed)?

[bterlson]

There is ambiguity between emu-note and figure, too, I suppose. Examples could also be figures. Just to confirm, is the following rational?

entity	markup
note	emu-note
todo	emu-note type="todo"
bug	emu-note ghid="bugnum"
example	emu-note type="example"
table	figure > table
figure	figure > no table

[domenic]

I would argue todo is redundant with bug/issue, but don't feel strongly.

I kind of like <table><caption> instead of <figure><figcaption><table> but also don't feel strongly about that.

I am not sure tables and figures are in the same category as note/todo/bug/example but maybe you weren't trying to say they were.

[bterlson]

I was basically wondering if tables/figures are in the same category. From a pure semantic html perspective, I think all of these are "figures".

I don't think todo and issue are redundant. Maybe ideally they would be but I can see not wanting to make a tracking issue on GitHub for all known WIP stuff...

@domenic you would suggest <table><caption> for tables but <figure><figcaption><img> for images? Just making sure I understand.

[domenic]

Semantically I think most of these are <aside>s :P. Maybe not tables, and maybe not figures.

And yes, that was my suggestion for tables vs. images.

[bterlson]

I like having custom elements for things that will have magic in them. Talked with @domenic on IRC and we came up with the following:

• emu-aside: an informative aside. Default type is "note". Can specify "todo", "example", or "bug". Compiles to <aside><figure><figcaption>.
• emu-listing: a normative figure. Default type is "figure". Can specify "table". Compiles to <figure><figcaption>.

Both emu-aside and emu-listing support the caption attribute as well which adds a custom text after the "Figure N" part of the text. This is where you would flag a listing as informative.

How's this sound?

[caridy]

👏

[jmdyck]

we came up with the following:

emu-aside: an informative aside. Default type is "note".
Can specify "todo", "example", or "bug". Compiles to <aside><figure><figcaption>.
emu-listing: a normative figure. Default type is "figure".
Can specify "table". Compiles to <figure><figcaption>.

The appears to conflate two independent axes:
(a) whether something is informative or normative or other; and
(b) whether something is a figure or not.

The semantics of "aside" seem right for things like 'bug/issue' and 'todo', since those are outside the main flow of the document. They're basically annotations, and it would make sense to represent them in a sidebar. However, "aside" doesn't seem right for 'note' and 'example'. Note that the HTML says:

It's not appropriate to use the aside element just for parentheticals, since those are part of the main flow of the document.

To me, 'note' and 'example' seem like parentheticals.

It makes sense that <emu-aside> would compile to <aside>, but not necessarily <aside><figure><figcaption>.

To me, the name <emu-listing> suggests either a code listing (which would more likely be an example), or a list of things (maybe stretching to a table). It certainly doesn't suggest figures 1 and 2 of the ES6 spec (i.e., diagrams).

Both emu-aside and emu-listing support the caption attribute as well which adds a custom text after the "Figure N" part of the text. This is where you would flag a listing as informative.

So an emu-listing can be informative? But you defined it as normative.

---

Here's a counter-proposal:

• <emu-aside>: type="bug" or "todo" or "editor-note", etc.
  For content that is basically annotating the document.
  All of these should be gone (or at least, invisible) in the final version of the document.
  Compiles to <aside>.
  (Or why not just use <aside> directly, with a class attribute for the type.)
• <emu-info>: type="note" or "example".
  (Or you could have <emu-note> and <emu-example>.)
  For informative (non-normative) content.
  Compiles to <div class="informative"><p>NOTE/EXAMPLE [N]</p>
• We don't need an element for normative content, because that's the default.

Then, within each of those contexts, you can have paragraphs and figures and tables and lists, as appropriate. If you want to invent <emu- elements for them, fine, just keep them independent of the normative/informative/other axis.

[bterlson]

To me, 'note' and 'example' seem like parentheticals.

I can see that. But I think your axis of whether something should be visible in the final document to be a good deciding factor (and an easy rubric for authors to apply). That said...

We don't need an element for normative content, because that's the default.

But this doesn't easily allow for auto-numbering of specific types of normative content (table 1, figure 2, etc) so part of the feature request here is to make it easy to assemble a document with these kinds of elements.

But you could have a binary attribute on emu-info called "normative" and allow a type of note, example, figure, or table. Does this seem bad to you?

[jmdyck]

But this doesn't easily allow for auto-numbering of specific types of normative content (table 1, figure 2, etc)

Huh? As long as the specific types of normative content are easily detectable/distinguishable, then they're easily auto-numberable. I don't see the problem.

But you could have a binary attribute on emu-info called "normative" and allow a type of note, example, figure, or table. Does this seem bad to you?

Yes, because the whole point of <emu-info> was to demarcate non-normative content. If you allow the element to contain normative content too, then you've basically reduced its semantics to <div>. I realize you're thinking of it having the magic of auto-numbering (so you might call it <emu-numbered>, say), but that seems like the tail wagging the dog to me: whether something is auto-numbered isn't part of its inherent semantics.

E.g., I can easily imagine a 'house style' in which notes aren't numbered, but I can't imagine a style in which they aren't chunks of non-normative content. Or consider that we don't currently number paragraphs, but it's not an unreasonable style -- if it were desired, would you feel compelled to change every <p> to an <emu-numbered type="p">? I would hope not. It'd be easy enough to auto-number paragraphs without doing so.

Other smells:
Figures and tables (at least the ones you'd want to number) always have a caption, whereas notes and examples never do. (In the ES6 spec, at least.)

Presumably, <emu-numbered type="figure"> wouldn't take the place of a <figure> element, because that wouldn't be valid HTML. Instead it would contain a <figure>, whereupon the type="figure" is redundant. Ditto <table>. Contrast that with 'note' and 'example', where you can't rely on the presence of a particular built-in HTML element to signal that this is a note or example.

[bterlson]

Huh? As long as the specific types of normative content are easily detectable/distinguishable, then they're easily auto-numberable. I don't see the problem.

It's easier to add custom behavior for custom elements. Without a custom element you have to query the entire DOM. Doable but not as easy. Not a major issue.

Huh? As long as the specific types of normative content are easily detectable/distinguishable, then they're easily auto-numberable. I don't see the problem.

I would say the semantics are roughly identical to figure in HTML. The attribute adds semantics relevant to emu documents.

whether something is auto-numbered isn't part of its inherent semantics.

I think most authors would consider how an element is compiled and ultimately displayed part of the semantics. I think this is reasonable.

Figures and tables (at least the ones you'd want to number) always have a caption, whereas notes and examples never do. (In the ES6 spec, at least.)

Notes have captions (Note 1, etc.) Examples should if they don't.

Still thinking more about this, just putting down my thoughts.

[jmdyck]

We don't need an element for normative content, because that's the default.

But this doesn't easily allow for auto-numbering of specific types of normative content (table 1, figure 2, etc)

Huh? As long as the specific types of normative content are easily detectable/distinguishable, then they're easily auto-numberable. I don't see the problem.

It's easier to add custom behavior for custom elements. Without a custom element you have to query the entire DOM. Doable but not as easy. Not a major issue.

Ah, I think you misunderstood my statement "We don't need an element...". I wasn't saying "We don't need custom elements for tables and figures etc". (In fact, note that I said "If you want to invent <emu- elements for them, fine".) Rather, I was saying that, in a scheme where you distinguish the normative/informative/other dimension, you don't need a specific element simply to denote "normative": as long as you have elements to denote the other two, then "normative" can be the default. (Just justifying why a dimension with 3 values doesn't need 3 elements.)

whether something is auto-numbered isn't part of its inherent semantics.

I think most authors would consider how an element is compiled and ultimately displayed part of the semantics. I think this is reasonable.

In that case, what isn't part of the semantics? I'm inclined to think that how something is ultimately displayed is styling/presentation.

Figures and tables (at least the ones you'd want to number) always have a caption,
whereas notes and examples never do. (In the ES6 spec, at least.)

Notes have captions (Note 1, etc.) Examples should if they don't.

Okay, but "Note 1" and "Example 2" are entirely generated. What I meant was that notes and examples don't have an author-supplied caption (i.e., one that appears in the emu doc), whereas figures and tables do.

---

How would you feel about a vocabulary with <emu-note>, <emu-example>, <emu-figure>, and <emu-table>?

[bterlson]

In that case, what isn't part of the semantics? I'm inclined to think that how something is ultimately displayed is styling/presentation.

Think about it from an authors perspective. For example, a note is a non-normative explanation captioned and numbered appropriately for you.

How would you feel about a vocabulary with , , , and ?

This is what I was leaning toward. Still missing what to do with todo and bug, though :-P Are those just emu-notes? Or, because they should be removed from the final output, emu-aside?

[domenic]

This conversation has become way too complicated. I think conflating some axes is exactly what is necessary to produce a simple, convenient, and usable model.

[jmdyck]

For example, a note is a non-normative explanation captioned and numbered appropriately for you.

Yup, and what's "appropriate" is up to the presentation style. You could have a style in which notes are always numbered, or a style in which they're never numbered, or a style (as in the current spec) in which they're sometimes numbered and sometimes not.

Still missing what to do with todo and bug, though :-P Are those just emu-notes? Or, because they should be removed from the final output, emu-aside?

I'd say <aside> if it works, or <emu-aside> if necessary. Just not <emu-note>.

[bterlson]

@domenic for the record, I agree. I'm trying to find a good balance, though, if possible :) I think the following vocab is pretty straight forward:

entity	markup	normative?
note	emu-note	no
todo	emu-aside type="todo"	no
bug	emu-aside ghid="bugnum"	no
example	emu-example	no
table	emu-table	yes
figure	emu-figure	yes*

Everything except emu-note has a caption property that will fill in after the generated caption. Eg. emu-example will display with a caption of "Example 1" if no caption is provided, else "Example 1: Caption" if a caption is provided.

* emu-figure may be informative if the caption allows it

[jmdyck]

Presumably, whether a table or figure is normative depends on where it appears (same as with a paragraph or list). E.g., a table within a note is non-normative because the note itself is non-normative.

But yes, in practice, most tables and figures would be normative.

[bterlson]

50% of the figures in es6 are informative :-P But I agree in general

[domenic]

@bterlson take your proposal and replace:

• emu-table with table (or, with emu-listing type="table")
• emu-figure with figure (or, with emu-listing type="figure")
• emu-note with emu-aside (default type="note")
• emu-example with emu-aside type="example"

and you'll have something that's simple enough to understand and use, IMO.

[bterlson]

Can you explain your mental model? I don't see how emu-listing type="table" is simpler than emu-table. Also people seem to have to remember that an example isn't a listing which seems unusual.

[domenic]

My mental model is that there are "small textual things" (the hypothetical emu-asides) and "big blocky things" (the hypothetical emu-listing). The big blocky things need whole-document numbered sequences because they might be referred to from elsewhere in the text. They might be normative (and usually are). The small textual things are fairly incidental and self-contained, and are always non-normative.

[bterlson]

Since examples should be globally numbered as in latex and word (and are anyway considered listings from what I've seen) shouldn't they be an emu-listing in your model?

It also doesn't seem clear that table and figure are different from note on the textual things --> blocky things scale. Some notes are multiple paragraphs while some tables are very tiny and only referenced from inside the same clause.

[domenic]

Since examples should be globally numbered as in latex and word

If this is true, then I agree. But that would be an editorial change from ES402's usage.

[bterlson]

Interesting, 402 doesn't seem to ever reference examples from what I can tell. But yeah I think they should be globally indexed. Todos could be globally indexed too since it makes it easier to refer to a specific one?

But anyway, separating based on whether something is globally indexed/sometimes normative or locally indexed/informative seem harder than deciding if something is part of the specification (emu-note/figure/example/table) or metadata (emu-aside). The latter seems more clear to me and less likely to change as we evolve our editorial practices.

[domenic]

I think by that logic everything should be globally indexed.

[caridy]

about 402 examples, yes, they should be globally numbered, but right now we are trying to produce a Hi-Fi copy of the pdf before moving on into the 3rd edition where we can correct all those details.

[bterlson]

I think by that logic everything should be globally indexed.

I think so too. I think it matters more for things that will be globally or externally referenced which seems maybe true for todos and at least today not true for notes. That said I'm not trying to change it (at least for now?)

[bterlson]

Some new info: Both ISO/IEC Directives, Part 2: Rules for the structure and drafting of International Standards and ECMA's Working documents and formal documents: rules for editing and distribution mandate that examples and notes be numbered in a clause-local fashion. However, it gives basically the same justification I gave above for why tables and figures are numbered globally. It does not give rationale for why notes/examples should be numbered differently, but there you have it... for now we'll have to number them as the relevant documents say we must :-P

[bterlson]

Everything discussed in this thread should be present now in 2.0.0-beta4 (see here: https://github.com/bterlson/ecmarkup/releases/tag/2.0.0-beta4).

I have deviated from the exact letter (though not spirit, IMO) of the metaspec for examples, which are styled similarly to figures and tables as opposed to notes.