New to Sigil, frustrated: bad TOC

[RootlessAgrarian]

A) you people are Wonderful. Bouquets and heartfelt thanks all around.

B) case-sensitive tags in XHTML/XML, doh! my bad. got too used to loose, case-insensitive HTML parsers.

C) after fixing (ahem) this little problem I tried again... and found a new problem.

Looks like Sigil wrote an incomplete metadata block? I get complaints about "Unfinished element" at line 9 of content.opf. I hadn't touched this file with vim afaik, only the content???.xhtml files further down in text/.

I consulted Ainsworth's guide to XHTML (my current favourite tutorial/ref) and found that the metadata block must include title, identifier, and language. Looks like "language" is missing from the block in my content.opf, so I am adding Ainsworth's sample "en" language element.

<dc:language xsi:type="dcterms:RFC3066">en</dc:language>

this didn't fly either.

ERROR: AgCiv.epub/OEBPS/content.opf(8): The prefix "xsi" for attribute "xsi:type" associated with an element type "dc:language" is not bound.

(sigh) I get rid of the offending xsi:type syntax. finally, my epub is valid!

I now restart Sigil (drum roll...) and load the freshly validated epub. Yes, it loads! Yes, I can see the entire document. And best of all, YES it has a table of contents.

Now I'm going to Save it back and see if Sigil (a) writes a correct metadata block and (b) writes toc.ncx...

... and the answer is... Yes, the language tag has persisted in the metadata block, and Yes, toc.ncx is now fully populated with (I trust) correct section/subsection references.

I am, as far as I know, one happy camper and no longer *quite* such a n00b.

So why was the language element missing from the metadata block? Did Sigil leave it out? Did Calibre leave it out and Sigil simply replicate the bad block? Or have I been into that file with vim, accidentally deleting one line and subsequently forgetting all about it? I guess I'll find out next time I convert pdf to epub in Calibre and then export it for edit :-)

[Valloric]

Originally Posted by RootlessAgrarian

So why was the language element missing from the metadata block? Did Sigil leave it out? Did Calibre leave it out and Sigil simply replicate the bad block?

The spec says that an epub file needs to have a title, author and language specified. But Sigil cannot just make these up. If the book you imported doesn't have some of these elements, then it won't have them in Sigil either. If you don't use the Meta Editor (in Sigil) to add this missing information, then on export, some of these elements will still be missing.

Do you really want your editor to "guess" at your book's title, author and language? This is one of the things you have to make sure you include yourself.

What Sigil can do (and will, in time) is warn you that you failed to specify this information. But that's as far as it can go.

[RootlessAgrarian]

Originally Posted by Valloric

Do you really want your editor to "guess" at your book's title, author and language? This is one of the things you have to make sure you include yourself.

Ah, I see -- Sigil is intended for use by people who already know the XML spec for EPUB? OK. I assumed it was meant to hide expert knowledge and guide the newbie -- in which case, user pre-knowledge of the names of metadata elements, and which ones are required, would not be a given (as in fact it wasn't in my case). If it's intended to be a helper app for people who already know the spec then I agree it should not do more than warn/remind.

If Sigil did want to be more newbie-friendly... perhaps in the metadata editor, any missing *required* elements for a structure could be created with value BLANK and visually highlighted, so if you pop open the editor you immediately see that the doc is damaged or incomplete? Most every commercial Web form on the planet flags (w/asterisks, colour, boldface, etc) "required fields" -- it's a visual convention familiar to most 'net users.

What Sigil can do (and will, in time) is warn you that you failed to specify this information. But that's as far as it can go.

Yes a simple warning would also be reasonable, particularly at Save or Save As time: "This EPUB is missing some required elements of the metadata structure: title, author and language. See (URL) for correct keywords and valid values for these elements. This EPUB will not pass most validity checkers."

One last thought... Couldn't 'language' be inferred -- if left uninitialised -- from the local environment? It wouldn't be infallible (my LANG may be en, but I may also read/author documents in French from time to time). But it might be a good starting guess.

"Element 'language' missing from metadata. Initialised to best-guess 'en' from local language configuration."

[Valloric]

Originally Posted by RootlessAgrarian

Ah, I see -- Sigil is intended for use by people who already know the XML spec for EPUB? OK. I assumed it was meant to hide expert knowledge and guide the newbie -- in which case, user pre-knowledge of the names of metadata elements, and which ones are required, would not be a given (as in fact it wasn't in my case). If it's intended to be a helper app for people who already know the spec then I agree it should not do more than warn/remind.

Sarcasm is rarely helpful.

The average epub user doesn't care that his epub file doesn't conform to the epub spec, he just wants to fix errors/improve layout etc. He only cares that the file displays correctly on his reading device.

The people who care about their epub file meeting the specification already use tools like epubcheck to verify the basic requirements. If you care about meeting the specification, the prerequisite is that you know it.

Guessing the language according to the system locale is a bad idea, since it lulls you into believing that you don't have to worry about setting a language directly. And then you create an epub in a different language and now your epub has incorrect information.

Not to mention other people (like for instance, me) who use a different locale than the majority of the books they create. And then you're still left with the title and author, so you have to open the Meta Editor either way. There's no way around this.

And you're still ignoring the main problem: Sigil can't guess the author or the book title. Nothing can. Case closed.

Bottom line, guessing is error-prone (hence, guessing). I'm against it. I'd rather force the user to make sure he used the correct information than have him curse my name when the guessing game bites him and causes considerable damage. I choose to err on the side of caution.

The only recourse is to provide a warning on export if some of this information is missing, and the user can either act on this or ignore it if he doesn't care.

Originally Posted by RootlessAgrarian

If Sigil did want to be more newbie-friendly... perhaps in the metadata editor, any missing *required* elements for a structure could be created with value BLANK and visually highlighted, so if you pop open the editor you immediately see that the doc is damaged or incomplete? Most every commercial Web form on the planet flags (w/asterisks, colour, boldface, etc) "required fields" -- it's a visual convention familiar to most 'net users.

And how many desktop applications do you know that do this?

[zelda_pinwheel]

Originally Posted by RootlessAgrarian

Ah, I see -- Sigil is intended for use by people who already know the XML spec for EPUB? OK. I assumed it was meant to hide expert knowledge and guide the newbie -- in which case, user pre-knowledge of the names of metadata elements, and which ones are required, would not be a given (as in fact it wasn't in my case). If it's intended to be a helper app for people who already know the spec then I agree it should not do more than warn/remind.

If Sigil did want to be more newbie-friendly... perhaps in the metadata editor, any missing *required* elements for a structure could be created with value BLANK and visually highlighted, so if you pop open the editor you immediately see that the doc is damaged or incomplete? Most every commercial Web form on the planet flags (w/asterisks, colour, boldface, etc) "required fields" -- it's a visual convention familiar to most 'net users.



Yes a simple warning would also be reasonable, particularly at Save or Save As time: "This EPUB is missing some required elements of the metadata structure: title, author and language. See (URL) for correct keywords and valid values for these elements. This EPUB will not pass most validity checkers."

One last thought... Couldn't 'language' be inferred -- if left uninitialised -- from the local environment? It wouldn't be infallible (my LANG may be en, but I may also read/author documents in French from time to time). But it might be a good starting guess.

"Element 'language' missing from metadata. Initialised to best-guess 'en' from local language configuration."

to be fair, when you open the meta editor in sigil (tools > meta editor), the only three fields which are specifically listed are the three which are required : title, author, language. "language" even has a drop-down list to choose from, so you don't even have to type it in yourself. you can add any further meta-data (like description for instance) using either the basic / advanced buttons, which give you the name of the meta-data and a short description of its purpose / use. i'm honestly not sure how much easier it could get, except for, of course, a warning if any of the three required fields are left blank, which is planned. compare this dialogue box to writing the entire content.opf and toc.ncx by hand in a text editor (as i have done... pre-sigil) and believe me, you'll have a whole new appreciation for user and newbie friendliness !

[softengdeb]

How to convert .epub to .awz

[RootlessAgrarian]

Originally Posted by Valloric

Sarcasm is rarely helpful.

My apologies, no sarcasm was intended. I have written a lot of GUI apps that were not for newbies at all, just convenience-tools for people who had to have expert knowledge well in hand before using the tool. So it makes sense to me that a tool can be GUI without being at all intended for newbies, and I would accept such a tool and bring to it different expectations than I'd bring to something intended to hand-hold the clueless. (And when it comes to epubs, as I've made embarrassingly clear, I am still firmly situated in the ranks of the clueless).

And how many desktop applications do you know that do this?

Well I have written a few in my time that pre-loaded required fields in saved structures (FITS headers, for example) with reasonable default values -- or with obviously bogus boilerplate values like "NO_OBJECT_NAME" or "?????". Or would refuse to save a data structure unless all required elements had been defined. But it's not that important. There's a proper way to use Sigil effectively (or an idiosyncratic way that will meet my own individual needs) and I'll get used to it.

Mostly, I'm sorry to have given the impression of sarcasm -- and offence -- when being quite serious and having friendly rather than baiting intent. Apologies again. Tone is difficult to convey -- with or without smileys -- and I seem to have conveyed an unintended tone here.

I've succeeded in making my epub compliant; I now know how to generate toc.ncx using Sigil (this alone is worth a bit of learning curve!); I now know which metadata fields are required for a well-formed content.opf; and I can move on to final proofing for those last few blankety-blank OCR errors. Everyone's been very helpful and all the patient n00b-education is much appreciated.

[zelda_pinwheel]

don't worry rootless agrarian, we all were clueless n00bs once. you learn as you go along, and pretty soon you'll be answering questions for the next wave of clueless n000bs. i'm glad you're getting everything sorted out. let us know if you have any more questions.

[pdurrant]

Originally Posted by softengdeb

How to convert .epub to .awz

Calibre is the simplest way.
Or extract the XHTML & images, and use Mobipocket Creator. Which will let you tweak the XHTML to give the best results, especially when there's fancy formatting that the Mobipocket format can't handle.

[DaleDe]

Originally Posted by softengdeb

How to convert .epub to .awz

Use calibre to convert to .azw and then rename.

Dale