View Full Version : epubcheck errors regarding NCX - can you help me translate these?


Dusk
05-27-2011, 07:15 PM
Here are the error messages from epubcheck (specifically, Threepress's Web-based validation service) concerning an ePub file I'm trying to validate:

* * *

ERROR: first-time-the-eternal-dungeon-13.epub/toc.ncx(17): element "navMap" incomplete; missing required element "navPoint"

ERROR: first-time-the-eternal-dungeon-13.epub/toc.ncx(2): assertion failed: first playOrder value is not 1

* * *

I'm using Smashwords's Meatgrinder for the conversion of the DOC file. I'm in touch with Smashwords's customer service concerning this, but since they're not experts on ePub code (and I certainly am not), I thought I'd try you folks as well.

What's mysterious about this particular situation is that the DOC that's being converted is an abridged version of a DOC file which, when converted to ePub by the Meatgrinder, *did* pass epubcheck. So I'm mystified as to why the converted abridgement isn't passing.

pholy
05-27-2011, 11:33 PM
I'm guessing here, but when you created your abridged version of the doc file, did you re-create the Table of Contents after your edits? I've fouled up more than one of my documents by forgetting that, although I don't know if it would create the Meatgrinder problem you are getting.

Dusk
05-28-2011, 02:40 AM
There's no table of contents; it's a single-story e-book. I've tried formatting the file with and without bookmarks (i.e. internal links); I get the same error messages, either way.

Jellby
05-28-2011, 03:58 AM
It seems your TOC is empty. Try this "minimal" NCX:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN" "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" xml:lang="en" version="2005-1">
<head>
<meta name="dtb:uid" content="the book id" />
<meta name="dtb:depth" content="1" />
<meta name="dtb:totalPageCount" content="0" />
<meta name="dtb:maxPageNumber" content="0" />
</head>
<docTitle>
<text>Title</text>
</docTitle>
<docAuthor>
<text>Author</text>
</docAuthor>
<navMap>
<navPoint id="Book" playOrder="1">
<navLabel>
<text>Title</text>
</navLabel>
<content src="filename" />
</navPoint>
</navMap>
</ncx>

Dusk
05-28-2011, 05:21 AM
"It seems your TOC is empty."

Since my e-book doesn't have a table of contents, I take it you're using "TOC" in a technical sense. Could you say more, please? Remember, I don't work with ePub code.

"Try this 'minimal' NCX."

I'm afraid I can't. I'm not creating the ePub file manually; it's being created automatically through a conversion at Smashwords (http://smashwords.com). The only thing I have control over is the DOC file I submit to Smashwords. None of my previously submitted files underwent this problem during conversion. I want to learn what the error messages mean, so that I can figure out whether the problem lies with the DOC file I'm submitting.

Sorry - I know this is a rather roundabout query. :) But could somebody please tell me, in layman's language, what the error messages are referring to?

Jellby
05-28-2011, 06:05 AM
Then it's a problem with the automatic conversion. I can't help much with that, but you could try adding a title, as if it were a one-chapter book.

Dusk
05-28-2011, 05:23 PM
If somebody here would tell me what the error messages mean, then I might be able to fix the problem by altering the DOC file I submit. All I know so far, from what you've said, is that it's connected with the TOC, but you haven't said what the TOC is or how the TOC relates to the two error messages.

"you could try adding a title, as if it were a one-chapter book."

By "adding a title," you mean . . . ?

JSWolf
05-28-2011, 07:34 PM
Like Chapter One or Start Here or something.

But no matter what you do to fix the problem, Smashwords is going to take the mess from Word and put the mess into your ePub and make that a mess. Smashwords is a terrible meatgrinder. It basically does it in a way that makes awful code. They really should allow you to upload an already made ePub and use that to convert from instead of a Word document.

Dusk
05-28-2011, 10:46 PM
I was wondering when the Smashwords-bashing would begin. :) My preference would be for Smashwords to accept HTML files, since that's what I start with (my DOC file is actually a conversion of an HTML file), but I have to work with the circumstances I'm given.

My previous files - including a file without any table of contents - have gone through Meatgrinder without any problems, which is why it's important to me to identify the exact nature of the problem here.

Let me try to be more specific in my questions:

What does "element 'navMap' incomplete; missing required element 'navPoint'" mean?

What does "assertion failed: first playOrder value is not 1" mean?

Dusk
05-28-2011, 11:56 PM
Just an additional note that I only come online on Friday and Saturday; I'll check for replies next weekend.

Jellby
05-29-2011, 03:30 AM
My previous files - including a file without any table of contents - have gone through Meatgrinder without any problems, which is why it's important to me to identify the exact nature of the problem here.

The problem is not the table of contents that you might have in the DOC file, but the generated NCX built from the chapter-like headings in the text. At least, that's what I'm guessing the conversion does.

If your text has some bold, centered heading saying "Chapter 1", or "The Death of Mary Poppins", or whatever, those are probably detected as "chapters" and included in the NCX (which is a TOC). If your text has none of these and is only plain paragraphs, there are no "chapters" detected and the NCX is empty, which is apparently not allowed. By "adding a title" I mean adding a heading in a different style, that looks like a chapter title.

What does "element 'navMap' incomplete; missing required element 'navPoint'" mean?

What does "assertion failed: first playOrder value is not 1" mean?

See the post #4 (http://www.mobileread.com/forums/showpost.php?p=1557349&postcount=4) above, there is a <navMap>, with a <navPoint> inside, and the <navPoint> has a playOrder="1" attribute.

The first message says that in your case there is no <navPoint> inside the <navMap>, and since it is required, the <navMap> is regarded as incomplete. The second message says that the first playOrder attribute is not "1", this is probably a bogus message due to the lack of <navPoint> (and therefore of any playOrder attribute).

AlexBell
05-29-2011, 04:44 AM
I was wondering when the Smashwords-bashing would begin. :) My preference would be for Smashwords to accept HTML files, since that's what I start with (my DOC file is actually a conversion of an HTML file), but I have to work with the circumstances I'm given.

My previous files - including a file without any table of contents - have gone through Meatgrinder without any problems, which is why it's important to me to identify the exact nature of the problem here.

Let me try to be more specific in my questions:

What does "element 'navMap' incomplete; missing required element 'navPoint'" mean?

What does "assertion failed: first playOrder value is not 1" mean?

Below is part of the toc.ncx file from an ebook I'm working on

<navPoint id="navpoint-1" playOrder="1">
<navLabel><text>Cover page</text></navLabel>
<content src="Frontmatter.html#coverpage"/>
</navPoint>

You see the last line? The error message tells you that </navPoint> is missing. The error message does not tell you why it's missing; that's up to you to find out, and I think that will be very difficult without at least some knowledge of HTML and of the ePub standards. Have you read Harrison Ainsworth's book? It's very helpful, but again you'll need some HTML knowledge.

You see the first line? The first navPoint MUST have "1" in both places in that line, and the navPoints MUST be consecutive 1, 2, 3, etc. That's part of the standards. Again, the error message does not tell you why whatever number is there is not "1", that's for you and Smashwords to find out.

I really and truly am not trying to put you down, but it seems to me that what I think you are asking (to be able to produce valid ePub ebooks with no knowledge of HTML) is simply not realistic.

Regards, Alex

JSWolf
05-29-2011, 12:47 PM
Here's my suggestion...

Take your Word file and run it through Calibre to convert it to ePub. Then take the ePub and run it through ePubcheck. I believe that Smashwords is using Calibre to meatgrind the Word document into different eBook formats. This might help you figure out what the problem is.

Dusk
05-30-2011, 11:46 PM
AlexBell wrote about me:

"with no knowledge of HTML"

It's a bad idea to make assumptions. ☻

I know basic HTML, just not at this high a level, and not in reference to ePub. (These codes are specific to ePub, aren't they?) I agree that it would be ideal for me to know ePub code, but I'll likely learn it the same way I learned HTML: by having things go wrong with my files, with the result that I dig into the code to try to figure out what the problem is.

So thank you all for your ePub 101 lessons; I really appreciate it.

Anyway, I and Smashwords put our heads together, and we identified the problem, with the help of some of your posts above. See, I didn't know that "toc.ncx" was ePub-talk for the table of contents that e-readers use for navigation (for example, in the sidebar of Adobe Digital Editions) - that was the information I was seeking above, in my garbled fashion. To me, "TOC" meant that list of links that the e-book designer puts at the top of the file. (Or that page in between the dedication page and the epigraph page, unless the epigraph page is replaced by a second bastard title page. Threads like this make me miss the old days, when I knew the lingo.) Hence my confusion when you guys kept saying, "There's a problem with your TOC."

The exact problem - it turned out - was that recent changes to Smashwords's converter, Meatgrinder, accidentally eliminated its ability to automatically identify chapters and create a TOC for them (in the ePub sense), in cases where there isn't a linked table of contents (in the HTML sense) within the file (just as you guys guessed; man, you're good). Smashwords is working now on correcting the problem, but since it's no sweat for me to create a linked table of contents, I did so in my DOC file, and my converted e-book passed epubcheck.

Thank you! It's been really nice knowing that there are folks here who've been willing to help me out.

JSWolf
06-01-2011, 10:09 PM
But, I would want to return any ePub that had an internal ToC (totally useless) and not an external ToC. I just wish publishers would stop putting in an internal ToC when they have a perfectly good external ToC.

Hitch
06-03-2011, 04:21 PM
But, I would want to return any ePub that had an internal ToC (totally useless) and not an external ToC. I just wish publishers would stop putting in an internal ToC when they have a perfectly good external ToC.

@JSWolf:

This will continue to happen (dualling TOC's {groan, bad pun alert}) for so long as mobi requires that you link an html.toc via the Guide, IMHO, for Kindle. It's a PITA, commercially-speaking, to make two books (like what we're all going through with making "Apple-compliant" epubs as opposed to REALLY compliant/valid epubs for everyone else) instead of one.

Hitch

JSWolf
06-03-2011, 07:56 PM
@JSWolf:

This will continue to happen (dualling TOC's {groan, bad pun alert}) for so long as mobi requires that you link an html.toc via the Guide, IMHO, for Kindle. It's a PITA, commercially-speaking, to make two books (like what we're all going through with making "Apple-compliant" epubs as opposed to REALLY compliant/valid epubs for everyone else) instead of one.

Hitch

But you do get a ToC. It's just not at the front. It's at the back. And it is linked via the Table fo Contents link. So really, an internal ToC is useless and a waste of space. I really dislike when the chapter titles are linked to the ToC.

As far as I am concerned, let Amazon fix their conversion software to deal with toc.ncx hoever they want so we don't have to infest the ePub with an internal ToC.

Dusk
06-04-2011, 02:35 AM
JSWolf wrote:

"I just wish publishers would stop putting in an internal ToC when they have a perfectly good external ToC."

Different people have different reading habits. I appreciate a table of contents within the file, especially if it includes blurbs for each of the chapters (as mine does). I agree with you, though, about the usefulness of the external table of contents.

Hitch
06-04-2011, 05:43 AM
But you do get a ToC. It's just not at the front. It's at the back. And it is linked via the Table fo Contents link. So really, an internal ToC is useless and a waste of space. I really dislike when the chapter titles are linked to the ToC.

As far as I am concerned, let Amazon fix their conversion software to deal with toc.ncx hoever they want so we don't have to infest the ePub with an internal ToC.

@JSWolf: we may be speaking at cross-purposes. Having an ncx in an epub and dropping it on KindleGen doesn't create a user-visible toc, at the back or elsewhere. While the 5-way button may be able to make use of the ncx, to jump from chapter to chapter, the human reader can't "see" an NCX in a Kindle device through the simple expedient of running it through KG or Previewer (unless someone is running it through Calibre). Only a MBPC-created TOC (which is still an html.toc) shows up at the back in a quasi-automated fashion. That's the TOC that's linked via the TOC link--that IS an html.toc; the ncx is not directly linked to the TOC "button" or menu item, as bizarre as that all sounds. The TOC that is linked to the TOC menu button is an html-toc--NOT the toc.ncx, FWIW.

HTH,
Hitch

JSWolf
06-10-2011, 09:50 PM
@JSWolf: we may be speaking at cross-purposes. Having an ncx in an epub and dropping it on KindleGen doesn't create a user-visible toc, at the back or elsewhere. While the 5-way button may be able to make use of the ncx, to jump from chapter to chapter, the human reader can't "see" an NCX in a Kindle device through the simple expedient of running it through KG or Previewer (unless someone is running it through Calibre). Only a MBPC-created TOC (which is still an html.toc) shows up at the back in a quasi-automated fashion. That's the TOC that's linked via the TOC link--that IS an html.toc; the ncx is not directly linked to the TOC "button" or menu item, as bizarre as that all sounds. The TOC that is linked to the TOC menu button is an html-toc--NOT the toc.ncx, FWIW.

HTH,
Hitch

We should not have an internal ToC just to appease Amazon. They could design KindleGen to take toc.ncx and generate an internal ToC. No reason they cannot. And Calibre generates a linked ToC. Sure, it's at the back, but that's OK. An internal ToC (at the front) just makes us have to turn more pages to get past it.

eping
06-11-2011, 12:22 AM
Your navmap part of NCX code may like this
<navMap>

</navMap>

It's a blank NCX file without TOC, such epub can be read properly
on ADE and iPad, but can't pass epubcheck, which will report


element "navMap" incomplete; missing required element "navPoint"
first playOrder value is not 1


ePub Maker before 1.2 also generates such code if there's no TOC in Word,
also received such error code from epubcheck.
I guess Smashword also has such a problem.

You may have to insert a navpoint manually to suppress this error, or you may use another tool to convert.

By the way, the error tip from epubcheck is generally weird, misleading or meaningless.

Hitch
06-12-2011, 10:36 PM
We should not have an internal ToC just to appease Amazon. They could design KindleGen to take toc.ncx and generate an internal ToC. No reason they cannot. And Calibre generates a linked ToC. Sure, it's at the back, but that's OK. An internal ToC (at the front) just makes us have to turn more pages to get past it.

@JSWolf:

I don't use Calibre to create mobi files, firstly; but more importantly, all Calibre does is create an internal toc--an html.toc--which it links via the Guide; it does exactly what you are saying we should NOT have to do to 'appease Amazon.' Calibre isn't magically utilizing the ncx sans an html.toc; it uses the ncx navmap to create an html.toc and linking it to via the Guide items. The TOC "at the back" to which you refer (is also not due to Calibre; it's due to KindleGen/MobiGen) is the very TOC you're saying we don't need.

So, call it by any other name, but the "Calibre TOC" that you're saying is sufficient is the selfsame "internal TOC" that you're saying we should not create to appease Amazon. More importantly, and more relevant to the discussion, if you're using Calibre you ARE "infesting the epub with an internal TOC;" you're simply allowing Calibre to do it for you. The "perfectly good external toc" you're referring to, a few posts ago, does not exist for Mobi/PRC; if you are discussing those created by Calibre, those have INTERNAL TOC's, created as I've described.

My point was, and still is: any user who simply has an epub with an ncx solely will NOT get a user-viewable and usable TOC via KindleGen or MobiGen sans an html.toc that is linked via the Guide. NOT the ncx.

Hitch
(Please check out SHAKEN: STORIES FOR JAPAN (http://www.amazon.com/SHAKEN-Stories-for-Japan-ebook/dp/B00556WX9A/)--Great reads, great authors, great cause; 100% of all royalties go directly to tsunami, earthquake and radiation victims in Japan.)

JSWolf
06-13-2011, 09:56 AM
I think you've got it somewhat wrong. ePub can have two different ToC. One internal and one external. The NCX file it the external ToC. if your ToC is in the NCX file, you don't need the internal ToC.

When you convert ePub to Mobi, the NCX gets converted to a linked ToC that is at the back of the Mobi. If you have both an NCX and an internal ToC, you may or may not end up with two ToC in the Mobi. But if the requirement is to have an internal ToC near the front of the Mobi, there there is no reason at all that Kindlegen could not manage that by using the NCX file. The fact that the NCX gets relegated to the back is not my concern. My concern it to get rid of any internal ToC. And the worst ones of all are when the publisher links the ToC headers back to the internal ToC. That's just wrong for an ePub.

What does Kindlegen do with the NCX? I knwo what Calibre does with it. It creates a linked ToC at the back of the Mobi.

DiapDealer
06-13-2011, 11:21 AM
When you convert ePub to Mobi, the NCX gets converted to a linked ToC that is at the back of the Mobi.
By what software?? Kindlegen certainly doesn't create a "linked ToC at the back of the mobi" from the NCX file. Nor does MobiPocket Creator. Calibre will do it if you tell it to, but it's quite easy to check the box that will stop that behavior. You might be the one that's confused here.

JSWolf
06-13-2011, 01:55 PM
Calibre will do it without having to tell it to...

ebook-convert file.epub file.mobi

And from there you will get a linked ToC at the back of the Mobi and no other ToC if the ePub has no internal ToC but only a ToC in the NCX.

Hitch
06-13-2011, 02:38 PM
I think you've got it somewhat wrong. ePub can have two different ToC. One internal and one external. The NCX file it the external ToC. if your ToC is in the NCX file, you don't need the internal ToC.

When you convert ePub to Mobi, the NCX gets converted to a linked ToC that is at the back of the Mobi. If you have both an NCX and an internal ToC, you may or may not end up with two ToC in the Mobi. But if the requirement is to have an internal ToC near the front of the Mobi, there there is no reason at all that Kindlegen could not manage that by using the NCX file. The fact that the NCX gets relegated to the back is not my concern. My concern it to get rid of any internal ToC. And the worst ones of all are when the publisher links the ToC headers back to the internal ToC. That's just wrong for an ePub.

What does Kindlegen do with the NCX? I knwo what Calibre does with it. It creates a linked ToC at the back of the Mobi.

@JSWolf:

I'm sorry...but you're simply incorrect. What you see, via Calibre, is nothing more than an internal TOC created via the use of the navmap in the ncx.

I'm really very well aware of what an ncx is versus a Guide-linked html.toc (what you are calling an "internal toc"). What Calibre does is create a Guide-linked internal, html.toc; it is doing EXACTLY what you say we should not do to kowtow to Amazon. That toc displayed by Calibre is absolutely not some dynamic, created-on-the-fly usage of the ncx; that is a plain old internal toc, created by Calibre, linked via the Guide, as per the Amazon specs.

Just because Calibre creates it doesn't make it something it isn't. That's an internal toc, just like Amazon wants. That is NOT an ncx (aka "external TOC"). It simply takes the navmap, makes an internal toc, which, via use of KindleGen, gets popped in the back of the book.

HTH,
Hitch
(Please check out SHAKEN: STORIES FOR JAPAN (http://amzn.to/lsKlS2)--Great reads, great authors, great cause; 100% of all royalties go directly to tsunami, earthquake and radiation victims in Japan.)

DiapDealer
06-13-2011, 03:00 PM
And from there you will get a linked ToC at the back of the Mobi and no other ToC if the ePub has no internal ToC but only a ToC in the NCX.
You're making absolutely no sense now.

There's an inline TOC (xhtml) that's completely optional in either epub or mobi. It's part of the ebook's text. And there's an internal/structural TOC (NCX for ePub and OEBPS) that you will never see by turning pages. It's part of the ebook's structure.

Calibre is the only conversion software (I know of) that will turn the internal (NCX) TOC of an epub into an inline (XHTML) TOC and add it to the back of the mobi—and you can easily tell it not to do that. So it makes no sense to blame an ebook having two TOC's on any particular conversion software. It's simply a choice or an oversight on the part of the creator.

JSWolf
06-14-2011, 09:58 PM
Why isn't anybody understanding?

Calibre takes the NCX and generates a ToC from it for the Mobi. It is put at the back. Yes it's HTML and not NCX. I didn't say otherwise. And yes it is guide linked. What it isn't is near the front of the eBook.

Mobipocket Reader doesn't deal with the NCX file properly when t converts an ePub. I'm guessing Kindlegen botches the ToC as well.

I blame publishers for kow-towing to Amazon. Because if not for Amazon's botched conversion software, there would be no need for an internal ToC in an ePub.