Skip to content

make GWT epub friendly#10148

Merged
zbynek merged 4 commits intogwtproject:mainfrom
evoludolab:epub
Sep 4, 2025
Merged

make GWT epub friendly#10148
zbynek merged 4 commits intogwtproject:mainfrom
evoludolab:epub

Conversation

@evoludolab
Copy link
Contributor

GWT is a great tool to bring interactivity in ebooks to a whole new level. Unfortunately, the epub v3 specs are still based on XHTML... even though the newer bells and whistles of HTML5 are acceptable too.

With respect to GWT, issue arise solely due to the   character entity, which is undefined in XHTML. Once replaced by   GWT works like a charm inside any epub (and javascript capable reader).

This PR does just that by replacing those characters but only where it matters, e.g. no replacements under the test or samples directories.

niloc132
niloc132 previously approved these changes Aug 20, 2025
Copy link
Member

@niloc132 niloc132 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't increase compiled size at all, and improves compatibility... I think I'm in favor of it?

If we do identify a downside, we could extract this as a constant so that projects could use configuration properties to control it rather than just the single constant.

But as far as I can tell, using the # syntax should make it only more compatible rather than less compatible - every browser should support the non-special cased xml escapes?

@jnehlmeier
Copy link
Member

If you have control over the doctype you can also import the missing named entities. XHTML is modular and thus nearly all named entities have been moved to modules and you have to import them if required.

See: https://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_module_XHTML_Latin_1_Character_Entities

Every browser supports the hex notation so it should not be an issue for GWT. It is less readable though if you don't know what &#160 or &#xA0 represent.

I would favor nbsp and import the XHTML module but I assume epub readers don't like imports that much.

@evoludolab
Copy link
Contributor Author

Thanks for your encouraging assessment and the remark regarding XHTML entities.

Based on this I did some more digging and defined the   entity, for example in the doctype:

<!DOCTYPE html [
	<!ENTITY nbsp "&#160;">
]>

The use of &nbsp; in the document is now possible. However, the GWT generated JavaScript instructions of the form:

element.innerHTML = '&nbsp;'

nevertheless throw an error: The string does not match the expected pattern.!

Note, this is not even ePub related but seems to be a quirk with XHTML...

@niloc132
Copy link
Member

niloc132 commented Sep 3, 2025

Looks like the flavor of xhtml supported in epub doesn't support any named entities, see https://ebooks.stackexchange.com/a/7001

This appears to be a change in epub3, see https://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg20132.html and https://www.mobileread.com/forums/showpost.php?s=267124a77d91aea967edc6c39cd216c4&p=3821413&postcount=3

@jnehlmeier any other thoughts, given that defining the entity doesn't seem to work? Maybe you'd like a comment in each place to specify that 0xa0 is a non-breaking space?

@jnehlmeier
Copy link
Member

Yes a comment like ePub/XHTML friendly &nbsp; would make sense.

As @evoludolab said it is possible to define nbsp and the document is valid then however it seems like JS does not respect/know the definition and complains.

@evoludolab
Copy link
Contributor Author

Thanks for this constructive discussion!

I wish I had come across the helpful pages @niloc132 pointed out a long time ago...

I have now added explanatory comments as @jnehlmeier suggested and merged the latest changes on main.

zbynek
zbynek previously approved these changes Sep 3, 2025
panel.setVerticalAlignment(HasVerticalAlignment.ALIGN_BOTTOM);

HTML first = new HTML("&nbsp;", true), rest = new HTML("&nbsp;", true);
HTML first = new HTML("&#xA0;", true), rest = new HTML("&#xA0;", true); // '&#xA0;': ePub/XHTML friendly &nbsp;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To fix this style issue, maybe move the comment to the previous line - might make sense for other lines too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. Done consistently for all occurrences.

@zbynek zbynek merged commit 4a85a12 into gwtproject:main Sep 4, 2025
4 checks passed
@niloc132 niloc132 added this to the 2.13 milestone Oct 30, 2025
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.

4 participants