Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issues exporting terms #4133

Open
mattgarrish opened this issue Apr 21, 2022 · 2 comments
Open

Issues exporting terms #4133

mattgarrish opened this issue Apr 21, 2022 · 2 comments
Labels

Comments

@mattgarrish
Copy link
Member

We just went through the process of exporting terms/elements/attributes from the EPUB 3.3 specification, so wanted to share a few of the issues we ran into:

First, it would really help to have the element and element-attr definition types documented. I didn't realize these existed until I was looking up the exported terms in the xref database and followed some html examples through to the source markup.

Second, it's not clear when or how data-dfn-for works for elements and attributes. It appears for attributes you can specify tbe element name and then you can reference as [^elem/attr^]. This is incredibly useful for avoiding naming collisions, but it doesn't appear to work well for elements. The EPUB specification defines multiple grammars - package document, media overlays, container file, etc. These grammars have some elements whose names collide, but I couldn't find a way to make data-dfn-for work to indicate that elements belong to different grammars.

For example, if I put data-dfn-for="package" on the package document's metadata element and data-dfn-for="smil" on the media overlays version, I was able to write [^package/metadata^] and [^smil/metadata^] internally, but the definitions didn't export so in any other document I'd get a message that the element "metadata" for "package" was not defined in any referenced specifications.

In the end, I had to skip defining the lesser-used elements to avoid collisions.

Third, is it a bug that you can't use the <a data-lt="..."> syntax for attributes or a missing feature? For example, writing [^script/src^] is fine but <a data-lt="script/src"> results in an error.

In any case, the [^...^] syntax would be helpful to note in the linking shorthands section. I didn't spot the link to the other shorthands after the example, so it confused me initially when you use [=...=] and when [^...^].

That's everything I can think of right now. Any other issues I missed @iherman?

@iherman
Copy link
Member

iherman commented Apr 21, 2022

Just a minor documentation issue, additionally to the list: in the shorthand cheatsheet, as well as the section on Element shorthands the text talks about HTML and SVG elements only. However, the same mechanism would work for any XML element that is exported into xref, like, say, MathML or indeed EPUB.

@mattgarrish
Copy link
Member Author

mattgarrish commented May 17, 2022

Another issue we've just discovered is that if you define a local element with the same name as an HTML element (and I presume SVG), respec will always turn it into a link to the local element.

For example, the EPUB package document defines a link element, but we also sometimes refer to the HTML link element. To differentiate the HTML element, I tried this:

<span data-cite="html">[^link^]</span>

But the generate link still goes to the internal link element definition. The only syntax that creates a link to the HTML spec is: <a data-cite="html#the-link-element"><code>link</code></a>.

This problem doesn't occur if there isn't a local definition. If we refer to the link element from the reading systems specification, for example, adding data-cite works as expected to disambiguate which specification we mean to refer to.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants