Feature request: Implement targeting of a specific "topic" on reader startup

[saprentice]

(I know, you're probably not looking for feature requests, but this should be really "easy", and will be a huge help to opening up the world of EPUB to the technical communication profession. Hoping I'm not overstepping here.)

Provide the ability to include a command line parameter that opens a specified EPUB and optionally a specified content document on application startup. This could be as basic as ..

<readium-app> book.epub#itemref-idref

• If the specified book is already open, switch to the specified idref rather than opening a new window.
• Preserve the application window size and position between instances.

A better implementation would be to provide a programmatic API (via DLL, etc) to this functionality rather than needing to use the CLI, but the CLI implementation is probably much easier and is quite sufficient (for an initial implementation).

Background:

The technical communication (techcomm) industry has made use of Online Help applications to deliver context sensitive documentation for many years. First with WinHelp and then HTML Help (CHM files). But Microsoft stopped supporting HTML Help many years ago, and techcomm has been scrambling for a replacement. Many companies are fine with delivering documentation as "web help" in a browser, but many still need to have a locally installed deliverable and still (for now) use HTML Help (on Windows only).

I see EPUB as a possible replacement for this deliverable. It fundamentally provides (or can provide) all of the necessary features, and is platform independent. I've developed prototypes for "EPUB Help" for a number of years and presented these at conferences. It mostly works. The main piece missing for a basic implementation is the ability for the main software application to launch a specific EPUB on the desired topic. Now that rendition:flow=scrolled-doc is available, I no longer need to do javascript hacks to get nice vertically scrolling topics (much better for reference documentation).

If a viable ereader was available that provided this basic functionality, I'd be able to encourage the tool vendors to update their publishing tools to provide better support for EPUB. Right now they say their clients aren't asking for it (which in my mind is because there are no readers that do what's needed to offer good techcomm deliverables)

There is reasonable interest in techcomm for use of EPUBs, but the ereaders and publishing tools are lacking in feature support. If Readium Desktop can provide more of these features, we may see more adoption.

[danielweck]

I agree that this is a very useful feature. File extension association ("double-click to open") is relatively easy to implement with Electron on different platforms (Linux, Mac, Windows), but the parameter passing will require a bit more thinking. In the Readium cloud reader (not Readium 2) the goto query string parameter is used to load a particular location within the publication, at the character level (CFI) or using HTML fragment identifiers.

[saprentice]

I'd be fine with most any parameter syntax for targeting the topic. CFI would be fine if you've already got code to use that. The "build" process for creating techcomm deliverables could generate a mapping from internal IDs (to the software) to CFIs (or whatever syntax is used). People will typically target the root of a content document, but I suppose it's possible that a mid-topic location could be useful. Thanks.

[danielweck]

Related to: #65

[danielweck]

Related: #85

[saprentice]

Hey there .. me again, the annoying guy with the feature request.

I've been presenting talks and workshops on EPUBs for a number of years at the tekom conference in Germany. I've been talking about this thing I call "EPUB Help" as a possible option (someday) for delivering Help on the desktop using EPUBs. Problem is that there are no viable desktop readers .. yet. I'm pinning my hopes on Readium-desktop (no pressure though). It's that time of year again where they (tekom) are asking for proposals (with a deadline of mid-April). My question is .. will Readium-desktop be ready for testing and experimenting by August/September timeframe? The conference is in November, but I'd need some time to set things up. I'd love to be able to introduce this reader to the techcomm community, and hopefully show that EPUB Help isn't just another of my crazy ideas!

[llemeurfr]

Hi @saprentice, Well, I've got a .dmg of the alpha version of my MacBook, and we'll provide it asap for early testers on the EDRLab website. A .msi should follow soon. It's by no way a finalized product, and we aim at showing a beta version during the next Digital Publishing Summit Europe in Berlin, mid-May (more info on the EDRLab website). So yes, a great demo in November is ok. Please contact us via email (contact at edrlab.org) to discuss that in details.

[saprentice]

Hi @llemeurfr .. I emailed the contact address last week, but didn't hear back. Would love to get a DMG of the alpha and any other development releases. Will try resending the email. Thanks!

[saprentice]

Just me again .. the reader is looking awesome! Thanks for all your hard work!

As of thorium-1.0.6-rc.0.1615, I'm seeing that you can use the MacOS open command to open a specified EPUB from the command line ..

open THORIUM-APP --args EPUB-FILE

Is there any way to target a specific topic? It appears to open on the last viewed topic (sensible), but would be great to be able to pass a second argument as the topic filename or the item ID.

I'm seeing various discussions on command line operation. Is there someplace that describes the current syntax?

BTW .. I'll be giving a presentation on EPUB at the tcworld conference in Stuttgart next week, and will be featuring this reader!

[danielweck]

Hi Scott!

What syntax do you envision using from the command line in order to reference a specific EPUB "topic"? Maybe a combination of:

1. reference to a HTML document (e.g. OEBPS/chapters/1.xhtml)
2. reference to a content fragment within that HTML document (e.g. #id or a CSS selector like body div.class > p#id or a CFI pointer)

Internally Readium uses a "location" object type / data structure, which is serialized to JSON for storage purposes (e.g. bookmarks). This is how the "last reading location" is restored every time a publication is re-opened. At the moment CSS selectors are the primary pointer type, we generate CFI just for fun. The engine actually supports character-level (DOM Range) pointers, but this is currently only used for text selections / highlights.

As for the CLI arguments, here is some basic documentation:
https://github.com/readium/readium-desktop/blob/develop/README.md#command-line

[saprentice]

Hi Daniel...

The simplest (from an integration perspective) would be to allow the use of an item ID to target a topic. Alternatively, specifying the HTML document path/name would be fine as well. Further granularity (to a subtopic location) to an ID within the HTML file would likely be helpful for some implementations. A CSS selector seems unnecessary to me, and CFI .. while "fun" .. might scare too many people away. :-)

Something like one of these would be fantastic (subtopicid being optional) ..

thorium /path/file.epub topicid#subtopicid
thorium /path/file.epub OEBPS/topics/topic1.xhtml#subtopicid

I'm using this on MacOS, so the command line info doesn't quite seem to work for me. I need to use the "open" command to get this to work to open the EPUB. Or maybe it's a path issue or requires some additional library?

Thanks!

[danielweck]

thorium /path/file.epub topicid#subtopicid

What does topicid represent? The unique identifier of an HTML document inside the package.opf (manifest item)?

[saprentice]

Sorry .. yes, the item/@id in the manifest.

[saprentice]

I see that the CLI for opening an EPUB is working well .. but has the ability to open on a specific topic been added? This is crucial for being able to open an EPUB from an application, when using the EPUB as documentation/help. I'm hoping to give a presentation (virtual likely) on this at the tcworld conference in Germany, later this year. Is is possible that this feature will be available?

[llemeurfr]

After discussing that with the developers of Thorium, some comments:

Such an evolution is not too complex but needs to be carefully designed.
Currently one can use thorium [publication-path] and this opens the publication (after importing it if needed) and moves the user at the last reading location if any.

Let's imaging that we add a second parameter after the path, containing the internal path of a resource inside the zip + a fragment id.
Example: thorium "moby dick.epub" "OPS/chapter 003.xhtml#leviathan"

This works for ebooks which have internal html ids .
Note that this is even usable for audiobooks also using the "t" syntax (e.g. "#t=12").

If this solution is good, we can implement it.

But this solution does not work if there is not HTML id in the content (warning: few ebooks have such ids).
The user cannot say "open on the 3rd paragraph" or "open on the 5fth div", or "open on page 25". A solution to such commands can be complex, as we would have to develop custom fragment id syntaxes.
Note that "page 25" is certainly the simplest and more useful, as we have a notion of "position" (~page) which can be used here.

So first let's settle on the requirements. Then we'll see if we can integrate it in the pile of work.

[saprentice]

I think your proposal is fine. Just to be clear, the ID you're referring to is fragment id defined by an id attribute on an element in the content HTML file, not the item/id in the OPF file, right? I assume it doesn't matter which element in the HTML, and there can be multiple IDs? And, you're saying that you can't just use the internal path without the ID? It would be great to allow no ID, but if that's not possible/reasonable, requiring the ID is fine. One further clarification, if this is an HTML ID, I'm assuming that the ID is not required to be unique across HTML files (only within an individual file), so in theory, all HTML files could use the same top-level ID, since the file name is what makes the target distinct, and the ID adds no further focus. Regarding a "page number" .. that would be unknown to the EPUB developer, since that's going to be dependent on the rendering, so not really a useful solution to the use case I'm looking for.

I don't see this as a "user feature" .. it would likely be used by software developers who want to deliver their online Help as an EPUB (hence "EPUB Help"). They would be generating the EPUB using a tool and can add IDs as needed, and will also know the path to the topics. This type of Help is called "context sensitive help" and is very common. From various UI elements (dialogs or screens) the end user can request Help and it would open the EPUB on the topic that describes that screen. This is a popular type of Help but the options are limited to platform-specific solutions. If Thorium implements this feature it would be the only (viable) platform independent solution.

Hope that helps .. let me know if you need further clarification!

[llemeurfr]

the ID you're referring to is fragment id defined by an id attribute on an element in the content HTML file, not the item/id in the OPF file, right?

right.

and there can be multiple IDs?

There is only one id value per html element, and we plan one single id value in the command line also.

It would be great to allow no ID

Yes this is possible.

I'm assuming that the ID is not required to be unique across HTML files (only within an individual file)

Yes

They would be generating the EPUB using a tool and can add IDs as needed, and will also know the path to the topics.

In this case the solution makes sense, yes.

[saprentice]

All sounds good .. thanks!

Regarding the id values .. yes, one per element, and the use here is to scroll (or page) to the indicated target element within the HTML file (same as with browser-based HTML). If no id specified, it would open at the root of the HTML content file.

Just out of curiosity .. would it be possible for a query string to be passed in and used by JavaScript internal to the content file? Something like .. OPS/chapter 003.xhtml?param=value#leviathan .. ?

[danielweck]

the use here is to scroll (or page) to the indicated target element within the HTML file (same as with browser-based HTML). If no id specified, it would open at the root of the HTML content file.

Yes, this is already supported in the readium-desktop SDK. Essentially, all HTML relative paths within a given publication package / archive container are unique, and each HTML document contains unique "locations" such as Elements (referenced via their ID or CSS Selector), or even character-level locations (although at this point in time I suggest we stick to simple uses-cases ... we do have the technical plumbing in place to support such fine grain document references, for example for text selections + annotations, but the CLI UX should remain laser-focused on simple cases, in my opinion).
As Laurent said, we can also target "audio books" which is to say that instead of HTML documents, we have paths to audio files, and a "start" timestamp expressed as a Media Fragment URI (t=...).
Internally the SDK implements a JSON data structure to transport all this information, but externally in the CLI we can support a simple syntax, as suggested by Laurent (i.e. publication resource path + # fragment ID)

[danielweck]

Just out of curiosity .. would it be possible for a query string to be passed in and used by JavaScript internal to the content file? Something like .. OPS/chapter 003.xhtml?param=value#leviathan .. ?

Yes and no :)
Internally the readium-desktop SDK carefully handles such URL query params, mostly for internal needs.
Personally I have never come across authored publications that make use of URL query params (only fragment ID), which makes sense as this would be poorly supported in most reading systems. There are some cases where URL query params can be useful to content creators, for example to pass simple string-serialized data from one "FXL page" / "chapter" to another (via hyperlinking), with some ad-hoc Javascript built into said HTML documents to handle the input query params. However to my knowledge such functionality would break in most reading systems, so this is effectively not a practical proposition in the real world.
As for supporting the specific CLI use-case, which is less standard and therefore offers opportunities to experiment ... I suppose we would implement a Proof of Concept as part of the main feature, to figure out whether it would work given the current technical hooks (I do not remember from the top of my head)

[saprentice]

I agree that the "path + fragment ID" is likely all that's needed for referencing of content. Anything more complex should probably be reconsidered.

One use case for including a query param in the CLI (as well as internal linking) is for the creation of a search feature within an EPUB. I've done this in prototypes that work to a reasonable degree in AZARDI as well as Chrome+Readium, and a lesser degree in other readers. Search is a very important feature in technical documentation, and since this is often not provided as a feature in readers (and when it is it's not implemented well), it's easy enough to include a JavaScript-based search within the EPUB itself. Allowing a query param in a link lets you pass the query from one page to another which can run the query to generate a list of results, and when a result is selected, the search terms can be highlighted in the target page. I've done a lot of work with various types of scripting in AZARDI and Chrome+Readium, with spotty success in other readers.

It does appear that my search feature does mostly work in Thorium! That means the query param is doing it's job (from page to page). I'm just starting to dig into this again after a long absence, so need to do some debugging and analysis, but this is very encouraging. The one thing that's not working in Thorium is the absolute positioning of a navigation bar across the top of the page, hmm. My current prototype uses jQuery to add a common UI structure to all pages, then uses fuse.js as the fuzzy search library. If this is something you'd like to see, please let me know.

Other uses of query params and passing data from page to page are for training documents. There is a whole industry that surrounds online learning and training, that could benefit from highly dynamic EPUBs. Much of this would rely on the ability to store data (either locally or remote), which is tricky at best with EPUBs .. although not completely outside the scope of the spec. This is on my radar, but pretty low on the list.

Yes .. I'm pushing the limits of a typical EPUB, but these are all things that are expected in online Help, and I'm hoping to make EPUB into a delivery for online Help. I'm really excited with the work you all are doing. Not only is this functionally an incredible desktop reader, but it looks great, and seems quite stable. Thanks for all you're doing!

[danielweck]

Hello, we are doing some bug triage, and we are now moving this meta-issue to a "discussion".

[danielweck]

So, further thoughts on this topic: technically this is not a trivial problem to solve, and this is also tricky from a UX perspective. For example, publications in Thorium's database are internally uniquely identified with private / non-interoperable UUIDs, plus there is also a CRC SHA1 checksum computation for each individual publication package / set of resources (which is not a recognised standard, but just the method Thorium uses to detect duplicated imports / downloads). The dc:identifier metadata is not reliable enough. Then there is the issue of handling the level of indirection into individual publication resources / documents (e.g. a relative URL path in the publication manifest / reading order, or possibly non-linear resource). Finally there is the precise anchoring into a specific region / location (text, image, audio, video, etc.). We're basically entering the realm of annotations, which is definitely worth pursuing, but not without a proper development roadmap / budget.

[danielweck]

From #1908
=> suggestion to produce an interchange URL inside clipboard text copy. Effectively, this could be the DOM range which Thorium already internally serialises across the IPC boundary as an interoperable JSON data structure (well, "interoperable" within the limited Readium world but nonetheless useful to generate CFI or similar data referencing technique)