HelpXplain in ePub3

HelpXplain is the exciting new animated infographics and screencast tool that integrates with Help+Manual.

Moderators: Alexander Halser, Tim Green

Post Reply
Simon_Dismore
Posts: 205
Joined: Thu Jul 13, 2017 2:57 pm

HelpXplain in ePub3

Unread post by Simon_Dismore »

I've been thinking about how to distribute H+M and HX-generated material in a way that's not platform-specific, doesn't get blocked by email services, doesn't require a code-signing certificate, doesn't need to be unblocked because it came from the Internet, and works offline without a web server.

The only standards-based approach I could find is ePub, which in the latest 3.2 version is pretty close to being a carefully structured web-site in a box (previous versions weren't, as discussed here).

That's not to say you can simply drop an xplain into an H+M project, publish to epub and expect it to work everywhere. Readers may not support scripting (which is needed to load and run xplains), they may ignore the scripts because H+M doesn't declare them in the manifest (my epub had errors and warnings at http://validator.idpf.org), or they may just not work correctly with dynamic eBooks ... there aren't a lot of those about yet. My test epub* failed with ADE, Edge, and Bluefire Reader on Windows and with Moon+ Reader Pro and R2 Reader on Android.

The good news is that the Lithium reader on Android and the Calibre viewer on Windows display my embedded xplain successfully. Apple Books (on iPad Pro) displays the xplain but the fonts aren't sized perfectly and the background image is missing. So it's not ideal but it's a good start especially in a corporate environment where you could pre-distribute the Calibre viewer.


* I inserted HX's example-15-mindmap-with-click-actions.xplain into a blank topic added at the beginning of H+M's ePubConfiguration.hmxz example, then published as epub via H+M 7.5.1 Build 4710.
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Re: HelpXplain in ePub3

Unread post by Alexander Halser »

I've been thinking about how to distribute H+M and HX-generated material in a way that's not platform-specific
We, too. The EPUB 3.2 format is still too new, I think.

But we are thinking about upgrading the Help+Manual proprietary eBook ("eWriter") format to a more universal format. This could work by creating those eBooks as data packages only and upgrading the viewer for multiple platforms. After a couple of experiments last weekend, it doesn't look too bad. We could offer this viewer as a Windows Store app, as a stand-alone distribution for Win32/64 and probably for MacOS as well. iOS and Android should be possible later on. On Windows, the viewer would still have the same API as the current eBook viewer, though we would be missing the custom menus. The biggest difference would be, that the executable and the data are no longer entangled, but separate. This has the advantage of being able to sign the viewer application.

It will require a distinctive file extension, that is absolutely unique.
Like:
mybook.ewriter
mybook.helpbook
mybook.younameit
Alexander Halser
Senior Software Architect, EC Software GmbH
Simon_Dismore
Posts: 205
Joined: Thu Jul 13, 2017 2:57 pm

Re: HelpXplain in ePub3

Unread post by Simon_Dismore »

Alexander Halser wrote:The EPUB 3.2 format is still too new, I think.
OK, we'll have to agree to disagree about that. AFAICS 3.2 is essentially EPUB 3.01 with a more permissive approach to versioning HTML5 standards. In the short term the Calibre Viewer would be a fine way for corporates to view HX-generated EPUB content. If you don't offer that route there's a risk that another authoring tool will: anyone can license Greensock, your output is easily reverse-engineered and I'm not aware of any restriction on bundling Calibre with content.
Alexander Halser wrote:We could offer this [EC-eWriter] viewer as a Windows Store app
I doubt your eWriter will be accepted if ShellExecute remains possible. The stores increasingly check for attack vectors ... I did a fascinating course on Malware a while back and the academics were all over the ways external library dependencies could be manipulated to introduce vulnerabilities. If that's your business model it could be switched off at any moment if the stores change their policies.

On the other hand, if you are already aiming to generate EPUB compatible-output from H+M — therefore investing time to understanding the standard — maybe you should evolve eWriter in an EPUB-reader direction ('eHelper', 'eXplainer' etc) with all the sandboxing that implies. You could have it read CHM too: that's not a format you expect to change any more.

Hope you don't mind me being argumentative about this in public. I know it is tough deciding development priorities :roll:, so best of luck 8)
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Re: HelpXplain in ePub3

Unread post by Alexander Halser »

Hope you don't mind me being argumentative
Not at all.

My argument against a general EPUB 3.2 output is that such a file still has the extension ".epub". But it's content can hardly be displayed by legacy readers. Backwards compatibility of the EPUB format doesn't help much, if the entire content relies on JavaScript, as Xplains do. So, if you create a file ending in ".epub" and email it to someone, but the content requires an EPUB 3.2 reader, the user experience might be disappointing in the end. That's why I think this format is still too new.
Alexander Halser
Senior Software Architect, EC Software GmbH
Kimberly Hitchens
Posts: 14
Joined: Mon Apr 02, 2018 3:38 pm

Re: HelpXplain in ePub3

Unread post by Kimberly Hitchens »

AND, the bottom line is, most eReaders still don't support ePUB3. Sure--iOS does in its Books app, but in terms of physical devices, e.g., the Nooks, Kobos, etc.--not so much. I don't know how many typical users are going to want to download and install Calibre, just to read an eBook. I can't speak for your prospective demographic, but mine can't even manage to download and install Adobe Digital Editions (which doesn't successfully support ePUB3, either) or Kindle previewer (a self-extracting, self-installing tool, mind you). I hope your readers are more tech-savvy than mine! :-) As Alexander mentioned, there's no simple way, from looking at the file in the front end, to know whether an ePUB-labeled file is ePUB 2 or 3.

If someone also wanted to sell the end product, you can't distribute ePUB3 to most self-publishing portals, either. I realize that wasn't the topic of discussion--selling the product--but it's a factor.

Hitch
Post Reply