Liza Daly from threepress.org has just released an article outlining problems she is having with users uploading invalid ePub formatted documents to Bookworm; an online ePub book reader. It’s very important for anyone developing ePub eBooks to produce valid markup. Not only will Bookworm give desirable results when rendering, but you’ll also be covering yourself for any future rendering engines and conversions you might need to do.
It’s actually quite surprising how many errors are showing up from files submitted to Bookworm. You should go over to the threepress blog for a full explanation, but here’s a list of the main errors;
- Missing required attributes in the metadata
- Metadata that hasn’t been proofread
- Improper nesting of the ePub zip file
- Items declared in the OPF file that are missing from the archive
- Invalid XHTML
Points 1 to 4 are really quite vital, although it is understanable for many documents to have invalid XHTML. Still, if it is within your means, I would try to control this the best you can.
I have plans to write some detailed articles regarding the creation of both the NCX and OPF files found in an ePub document, so keep a lookout for those.
I’m wondering how much interest there is in these parts for a wysiwyg EPUB editor. Automated conversion is great if certain factors are controlled, or if there are robust heuristics and corrective mechanisms, but in many cases, some mediated human intervention (ie through a GUI) is an easy and sometimes better way to avoid many of these problems.
A wysiwyg editor on top of epubcheck could provide some friendly messages to the user about things like image format, filetype, etc, while the editing system itself could normalize markup and hide the more confusing aspects of the format.
Is this something that people find interesting?
This is not something I would need myself but I think your idea is spot on Aaron. Not everyone is fully up to speed on the ePub specs and it’s easy to make mistakes, so having a visual editor would be a great tool.
If the editor is also made to be informative then users can learn while they work.
It’s tougher than it sounds to make a full-blown WYSIWYG editing system, especially for XML. There are lots of products that attempt to do that and most of them are terrible.
What might be a good first step is a method to inline-edit the source for the various metadata files, if they are found to have simple problems. In the early stages of Bookworm I considered allowing users to edit the human-readable metadata (e.g. title or publisher) and export that back out as an ePub. Something like that could be incorporated not into the Bookworm reader itself, but a separate product that could also perform validation against the specific schemas for OPF and NCX.
So, upload test ePub -> validate -> get opportunity to tweak it -> validate (repeat as necessary) -> output valid ePub.
I think trying to create a full suite for non-technical users is probably best left to the big commercial software firms, though.
One of the problems with hand-editing XML, though, is that it’s very unforgiving compared to HTML. It is by nature, strict, and many libraries developed for it are accordingly stern (not to mention inconsistent in their implementations). Combine this with inevitable human error and you have a lot of potential problems. I think it would be very frustrating for many people used to editing HTML by hand to have to struggle with XML, especially with something like EPUB which requires XHTML 1.1 and several different namespaces.
Also, the feedback process you mention between validation and user corrections is often unnecessary. For example, if I type ‘text/xml’ in a media-type attribute, I don’t want to go through a feedback process to fix that–I just want it to auto-correct. Likewise, if I duplicate something in the manifest, I don’t want to have to go through feedback and confirmation to have it removed, I just want it to go away. Same with spine ordering–if I move or remove something in the toc, I want the changes reflected across manifest, spine and navMap, but I don’t want to have to edit all three elements, much less go through two feedback/validation cycles before realizing that I forgot to duplicate the change across all three.
There are a lot of issues like these that come up with EPUB, and if it’s ever going to appeal to consumers, these things need to become more transparent, not less.
Aaron: I agree in principle although I think we’re talking about different groups of “users.”
As a reading system, Bookworm is largely targeted at end-users (i.e., readers) who just want to upload a book. If the ePub has recoverable errors, such as listing the XHTML as ‘text/html’ rather than ‘application/xml+xhtml’, then it ignores them.
What I was proposing was targeted at publishers or developers who use Bookworm as a test bed. It’s a usage I encourage but don’t provide specific tools for. These would be more sophisticated users who need to know what the exact problems were so they can go back and fix their pipeline.
It sounds like you’re thinking of a hybrid group that is producing ePubs as custom books rather than programmatically in batch (for example, tech-savvy self-published authors). That’s similar to what Feedbooks is doing now with their authoring tools, and while it’s a little clunky to use it certainly abstracts away the entire XML underpinning of ePub. I think that’s a better approach than WYSIWYG XML, which I’ve never seen done well.