epub validation error

[karenb27703346]

I am getting the following error when trying to validate a reflowable epub that I exported from InDesign: ERROR(RSC-012): epub/OEBPS/toc.xhtml(63,94): Fragment identifier is not defined.

Nothing I try is getting rid of the error. I've tried rebuilding the TOC in multiple ways. But it is not fixing the issue. 

[James Gifford—NitroPress]

For both @delehman and @JKunkel99999999 — EPUB can be fussy about TOC elements, never more so than when you try to omit one. There's a regular error in FXL EPUBs where selecting "None" for the TOC, even if that's sensible, leaves a tag end in the TOC file that many book portals dislike.

I'd suggest generating a dynamic TOC, under a style name EPUB or EBOOK or the like, even if it's essentially empty or null, and assigning it to the export using the Multi-Level option. That's the only thing that seems to provide a proper stub or "empty" dynamic TOC.

Not at all sure if the fault lies with ID or inconsistent interpretation of its idea of an empty TOC. Many of these files seem to pass validation but not upload to one book vendor or another.

[delehman]

Thank you. I suppose it could be a change in Ingram's validation, too. I'll give it a shot, although I'll probably have to muddle through the steps, never having done a TOC this way beofre.

[delehman]

Nope, that didn't work. I still get the errors. I created a TOC called EbookToc, using my Chapter Heading style. I checked "Include Book Documents." (I have a book with separate documents for each chapter and for verious front/back matter). I also syncronized the book documents. I'm not sure if that's needed, but it can't hurt. When I import the resulting epub into Kindle Previewer, it seems to have build the TOC correctly, but the import to Ingram still gives the errors.

[delehman]

Oh, and exported to reflowable epub using the multi-level option with the EbookToc style selected.

[James Gifford—NitroPress]

I lean towards it being an Ingram issue, but not with any confidence. The whole field is in churn right now, as the new accessibility standards are being implemented by some players (InDesign, EPUBcheck, etc.) but not by all. It's not that either party is wrong, just that validation and doc checking and such is out of step.

I'd have to look at some sample output to have any better ideas. I will say that a complex source structure like yours doesn't make it any easier — each layer of books and so forth adds places for the export to go wrong. EPUB really likes a simple source doc structure.

Still, putting any null TOC in place, which it sounds as if you've done correctly, should fix these TOC errors. Check the exported book in a vanilla EPUB reader (Calibre suggested).

[delehman]

I think I see the problem. In toc.xhtml, there is a section called "Page List." Under that, there are links to pages within chapters. The IDs on these links are of the form "Chapter_X.xhtml#pageN", where X is the chapter number and N is presumably a page number within the chapter. Inside the chapter files, there are page break elements that have IDs, some of them of the form "pageN" format but others of the form "pageN-M" where M is a number that doesn't seem to make much sense. I supect the latter elements are the ones causing the issue. For Chapter 2 in my book, for example, the TOC links to Chapter_2.xhtml#page1, Chapter_2.xhtml#page2, etc., but the IDs in the chapter file are "page1-4",  "page 2-1," etc. "page3" doesn't have the extra number, then "page4-1." So some of the links to the pages are broken, but others are not.

My thought was to uncheck "page navigation" when doing the export., but the page list is still built in toc.xhtml, so the problem is still present. I don't know if deleting that section and re-compressing the epub would work or if that would create other problems. But it seems ID is doing something odd, or I have a problem in my files that causes it to do something odd.

[James Gifford—NitroPress]

At this point, it could be any of ten little things. It sounds as if you are constructing too complex of a TOC, though — the style setup should contain nothing but the minimum list of headings (Chapter Titles only, if the TOC really isn't that important), and no page numbers, following info or assigned styles. You should not be trying to manually link to anchors or cross-references within the documents, just let TOC run and generate its own list. (By the way, it's essential that you save your "style" AFTER each change and BEFORE you run the update, or the changes will be lost the next time you open the TOC menu.)

This all should be very simple; I have only seen those "fragment" and "missing something" errors when no TOC is defined and the book portal doesn't like an extra closing tag or some such.

Have you passed the result through EPUBcheck? The raw command line version is best but you can use other versions that wrap that core in an app or website. I just don't care for all the extra "help" and spin and interpretation the latter provide.

ETA: Yes, absolutely, keep Page Navigation unchecked. It's part of the new accessibility features (the rest of which can be found under the Metadata pane of the EPUB export) — and unless you know exactly what you're doing, they should be left alone until some bugs and refined behavior are addressed.

[delehman]

I'm actually doing nothing fancy. For the epub, each document contains a single text frame. I don't set up anything internally for the TOC. On the export, I tell it to use the file names for the TOC. It seems to deo that right, but it's messing up on building the page links. I think the page links are something fairly new. I don't recall that checkbox on the export the last time I did this (which was late in 2023). I'm not even sure how an ereader uses that feature.

I did find two places where I had a couple of elements in separate text frames from the rest of the document. I know that can cause problems with the display order, but in the past it's never had this effect. Nevertheless, I fixed those and re-exported and got the same issue. I'm under a bit of time pressure right now, so I probably will have to manually fix the xhtml files if I can. Not ideal, but it's at least an option. Thanks for your input, though. I do appreciate it.

[James Gifford—NitroPress]

I'm not sure File Names is a reliable TOC method. And while extra text flows are not usually a problem (except that they can be left out of the export, or fall to a random order at the end), they should be removed. EPUB really works best with completely clean, linear source files, and adding a book structure if it's not needed is a contrary idea.

I'd bet, on a completely WAG basis, that these stray bits are creating unintended, unattached elements that the Ingram checker doesn't like. But beyond that, from way over here, I got nothin' else.

ETA: if you aren't using Multi-Level for the TOC model and defining/generating a simple TOC as outlined, all bets are off. I am not sure the other options are compatible with any platform; I have notes to the effect that File Name should be avoided but I can't quire remember why.

[delehman]

Huh. Well, you probably have a deeper undrestanding of I than I do. All I know is, for my first 10 books, file names worked just fine. Now suddenly they don't, but neither does multi-level TOC. Both methods seem to generate the same thing. I'll keep fiddling with it and let you know if I get anything to work. My only advantage is that I'm a software developer and understand xhtml files, generally speaking. But I'm not an expert in epub format. Not yet. 😛

[James Gifford—NitroPress]

Knowing HTML/CSS is a huge advantage,. but the structural "glue" of an overall EPUB file is... not nearly as linear and sensible. And the lack of any enforcement of standards means that the field is chaotic, as well. In many cases, it comes down to the old "compiles... first screen comes up... ship it!" level of validation. (I have some time in software as well...)

Something has very likely changed, which is why this book is giving you pushback. Probable cause: the new accessibility changes, which led to collateral changes and "fixes" of old, sloppy code and structure. The solution is to figure out what, and how to get around it. The reason I suggest different structure is that all of the above means, not entirely unexpectedly, that somewhat hacked, workaround, deprecated methods that have worked overall now no longer do. And while I can't put a finger on it, my collective info is that the file name basis for a TOC was never a very good option, kind of like the option to rasterize the first doc page to "make a cover." They had some place in someone's notion of useful at some point — and remember that EPUB 3 alone is 12 years old now — but a lot of these options are no longer in step with the more standardized, mature e-book world. Ingram may be implementing a quirky, idiosyncratic check of their own, or may be enforcing something that should have been caught all along. No (useful) way to tell.

I'd put time and effort into a more standard TOC rather than keep trying to hack around a wonky approach, even if it worked in the past.

BTW, there are three poles of expertise with EPUB, all fairly opposed. Choose wisely. 🙂

[delehman]

So...I got the ebook fixed, but not the exporet problem as yet. The solution was to use Calibre to edit toc.xhtml and delete the page navigation section. Then it works fine for uploading to Ingram and displays fine in both Calibre and Kindle Previewer.

After poking around a bit in the files, I think you're pobably right that the problem is related to exporting a book. It looks like the pagination stuff is built assuming that it's all one file, so there can only be a single page 1, page 2, etc. If it finds more (treating each doc in the book as a separate entity), it appends a number to distinguish them, even though that's not actually necessary, because the tags are in separate xhtml files. This must be related to the new Page Navigation feature. Problem is unchecking it does not prevent these tags from being generated. Maybe one of the other options you mentioned would do that, but I'll play with that later. Thanks again for your input. There is a bit of light at the end of the tunnel now. (And with luck it's not an oncoming train!)

[James Gifford—NitroPress]

Not quite sure we're on the same page, but multiple content files are common. Best to have a single one, but multiple text flows and/or defined splits will create multiple ones, sometimes dozens. Nothing to do with the accessibility changes. If you use multiple articles in an ID doc, or a Book, you'll get one XHTML file per text flow.

[delehman]

To explain better, I have an .indb file. Within that, there is one .indd file for each chapter, plus a few more for front and back matter. I set up my print book first, then I copy those files to a new folder, create a new .indb for the epub, and add in the copied .indd's. I then do such formatting changes as are required (non-breaking spaces, etc.) to make them display correctly. In the print version, the chapter headings are in a separate text frame from the body of the chapter. In the epub version, I move the chapter headings into the main frame. I sometimes use small graphics to separate scenes. These are all in-line in the text frames for the epubs. That's about it. I try to keep it as basic as I can, especially for the epub version.

[James Gifford—NitroPress]

Sorry, I was on a glass keyboard for the prior post — by on the same page, I wasn't sure if you were describing multiple XHTML files, which are perfectly okay.

I do have questions about your layout, though — for one thing, you don't have to have two versions, for print and EPUB, if you follow some basic layout rules. Putting text in multiple boxes on a page is a kind of sloppy and deprecated technique; it's better to use paragraph styles to position and space things so that text is always-always in an orderly single flow. That breaking things into boxes might be part of the problem here.

As for graphics, you can include them in an EPUB as well as long as they're anchored to the text. Again, it's "one continuous text flow" including any inserted or anchored elements, and you can get that to come out as EPUB with no mucking around if you do things right.

[delehman]

Admittedly, I may be doing things the archaic way. My late wife used to do the layout for me. She learned ID by doing it back in the early 2010's. She set up a template for the print books, which I've been using since her passing. I only publish 2 books a year right now, so I haven't had much incentive to fiddle with it, since it works well for me. I probably should find some time to play with it. It would certainly be nice to not have to do an ebook conversion.

That said, the ebooks don't have multiple text boxes. As I mentioned, I move everything into a single text box (within each .indd) for the ebook version. So that shouldn't have anything to do with the TOC issue.

[James Gifford—NitroPress]

Sure sure. For print, you can do almost anything — stick boxes and elements all over, leave unconnected elements, etc. Lots of apps and processes either worked that way or made it hard to be structured, for a long time. It's rare for a PDF export, even, to mess anything up from that kind of layout.

But when you get to tools and processes that depend on structured content — TOC, index, and above all e-book export — all that hack and slash turns projects into a nightmare. Using/learning organized layout skills goes a long ways in not just simple print layouts, but as things get more complex and then when you make the jump to where document content and structure are paramount, not just visual layout on each page.

If, for example, your text boxes with the chapter headings were a linked part of the text flow, it would still be an outdated layout method, but at least (for EPUB export) the text would be all one piece and not need modification for export. Same result and mostly the same method, just not leaving any content as a disconnected element.

But as always, "what works for you...." And we don't really have an absolute answer on this TOC glitch. 🙂

[delehman]

Thanks again for all the info. As for the TOC issue, I've done a bit more digging, and I can see exactly what's happening now. As I mentioned before, in my book file, I have a set of documents. The first few are named thus:

Books by the Author

Title Page

Information

Dedication

Chapter 1

Chapter 2

[etc.]

The toc.xhtml file has a section for the TOC itself, which is built correctly, and a page-list section, which appears to be built correctly :

<nav id="toc" epub:type="toc" role="doc-toc">
	<h2>Contents</h2>
	<ol>
		<li><a href="Books_by_the_Author.xhtml">Books by the Author</a></li>
		<li><a href="Title_Page.xhtml">Title Page</a></li>
		<li><a href="Information.xhtml">Information</a></li>
		<li><a href="Dedication.xhtml">Dedication</a></li>
		<li><a href="Chapter_1.xhtml">Chapter 1</a></li>
		<li><a href="Chapter_2.xhtml">Chapter 2</a></li>
		...
	</ol>
</nav>
<nav epub:type="page-list" role="doc-pagelist">
	<h2>Page List</h2>
	<ol>
		<li><a href="Books_by_the_Author.xhtml#page1">1</a></li>
		<li><a href="Title_Page.xhtml#page1">2</a></li>
		<li><a href="Information.xhtml#page1">3</a></li>
		<li><a href="Dedication.xhtml#page1">4</a></li>
		<li><a href="Chapter_1.xhtml#page1">5</a></li>
		<li><a href="Chapter_1.xhtml#page2">6</a></li>
		<li><a href="Chapter_2.xhtml#page1">7</a></li>
		<li><a href="Chapter_2.xhtml#page2">8</a></li>
		<li><a href="Chapter_2.xhtml#page3">9</a></li>
		<li><a href="Chapter_2.xhtml#page4">10</a></li>
		<li><a href="Chapter_2.xhtml#page5">11</a></li>
		<li><a href="Chapter_2.xhtml#page6">12</a></li>
		<li><a href="Chapter_2.xhtml#page7">13</a></li>
		<li><a href="Chapter_2.xhtml#page8">14</a></li>
		...
	</ol>
</nav>

 But in the indivudal xhtml files themselves, the page-list links are different. Just looking at the page1 link for each file, I find:

// Books_by_the_Author.xhml
<div id="page1" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

// Title_Page.xhtml
<div id="page1-1" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

// Information.xhtml
<div id="page1-2" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

// Dedication.xhtml
<div id="page1-2" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

// Chapter_1.xhtml
<div id="page1-4" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

<span id="page2" role="doc-pagebreak" aria-label="2" epub:type="pagebreak"> </span>

// Chapter_2.xhtml
<div id="page1-5" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

<div id="page2-1" role="doc-pagebreak" aria-label="2" epub:type="pagebreak">
</div>

<span id="page3" role="doc-pagebreak" aria-label="3" epub:type="pagebreak"> </span>

 And so forth. It appears that ID is acting like all the page 1's are in the same file and thus disambiguating them by adding a sequence number to them. But the toc.html file treats them as separate files and doesn't disambiguate them. So most of these links end up broken.

As I mentioned, I unchecked the "Page Navigation" checkbox, but it still built the doc-pagelist section. So the only way to fix it right now is to manually delete that section (or to go through all the individual files and fix the links one by one, which would be a pain). I'm not sure where to go to report this to Adobe. Will it get picked up from here, or do I need to send it somewhere? Thanks again!

[delehman]

Copy paste error. The Dedication.xhtml page link should have been:

// Dedication.xhtml
<div id="page1-3" role="doc-pagebreak" aria-label="1" epub:type="pagebreak">
</div>

[James Gifford—NitroPress]

Okay. It looks like a collision between elements added in the new accessibilty changes and export from a Book structure (or, possibly, any export that generates mulitiple XHTML files, such as when file splits are used). I'd have to dig out a corresponding project and do some experimenting; all I can say is that I've have no problem with two books, not using a Book structure, under v19.4 to KDP.

If the edit fixes it, well and good, but do consider that a hack/workaround — I strongly deprecate EPUB surgery as an obsolete method and believe all problems can be fixed in the source-to-export path. (If ID is actually exporting incompatible code, though, at least until Ingram updates its validation... the "fix" would be waiting it all out.

I will say — knowing the history of your books and your likely unwillingness to mess them all up now — that this is a weak if not poor use of the Book feature. Yes, one of its uses is to assemble otherwise separate, often standard or boilerplate documents, more or less as you've done,. but with so few elements it's gaining nothing and possibly adding unnecessary structure, complexity and problems here. If it's not too late in the game or otherwise off the table, I'd really consider rebuilding this book and all future ones as a single INDD document. You won't lose much besides some need to update the doc as a unit (instead of relying on external edits to those component files), and you'll have that simpler structure that, with some other changes, is suitable for both PDF/print and EPUB export. The lack of separately processed docs into XHMTL segments might well bypass this new problem as well, too.

But for now, I guess edit, submit and look to the next iteration with some updates in mind. And, of course, make sure all the new accessibility options are disabled, not just that single "Page Navigation" checkbox but all of them under Export |  Metadata | Accessibility.

I'm going to experiment a little to compare older exports to what v19.4 is doing here.

[James Gifford—NitroPress]

Okay, I just looked up an older EPUB I generated from a Book structure and looked at its toc.xhtml file. The first part is identical. However, it has no pagelist section. I then looked at an EPUB I generated just days ago, from v19.4, from a single file format. No pagelist section.

I conclude that you have some accessibility option, among the new stuff, checked somewhere. Keep in mind that each component file has EPUB export settings, which may or may not be completely overruled by the Book export settings. I suggest you review the EPUB export settings for each component file and make sure all accessiblity stuff including that "Page Navigation" checkbox are disabled, then possibly create a new Book and make sure its export settings are simililarly "non accessible."

My thought right now is that this is the whole of the problem: your export is generating that second TOC section, which I've never seen before, that it's due to something enabled in the accessibility options, and that Ingram just doesn't like/recognize it correctly yet.

I don't have a Book project I can conveniently export under 19.4 to check that combination; I've used it only for one truly massive project that would take a long time to re-export successfully under 19.4. So if you do the above and find absolutely no accessibility stuff enabled and it still generates the pagelist, try exporting, say, one of your Chapter files alone to EPUB and see if it does.

I will double down, here, on the value of making these one-file projects, perhaps beginning with conversion of this one. It will remove a whole layer of fuss and bother and possible source of errors and problems, and lose you very little in project management etc.

[delehman]

I'll look at making a one-file project for the next one I do. (I'm too close to publicaiton date now to risk messing this one up.)

I don't see any epub export options at the file level. I'm probably missing something. Where do I find that?

[James Gifford—NitroPress]

Open each INDD file and go to EPUB export. Be sure all the accessibility stuff is checked off — in theory, the Book settings should override any such but the whole implementation is so patchy and undercooked I have no doubt things slip through. I'd actually export each chapter file to a junk EPUB to make sure, then save it. You will probably have to update the Book after you do this.

[delehman]

Ugh. Yeah, I think it would require actually exporting each file. I guess I can try it, although at this point I'm not sure it's worth it. The book-level option is definitely not being respected right now. FYI, non of the other accessibility options are filled in. They are all blank by default. Thanks once more.

[James Gifford—NitroPress]

Understood. If the edit works, it works, and you can call this one done. 🙂

And, VICTORY (of a sort). I just exported a book project, under v19.4, with Page Navigation checked and then unchecked. That's definitely the toggle; unchecked, no "pagelist" in the TOC file; checked, there it is. So if nothing else we ran down an absolute cause and theoretical fix, here — and another reason Book projects can be a PITA.