View Full Version : Inserting com.apple.ibooks.display-options.xml file in EPUB


roger64
09-30-2012, 01:22 AM
Hi

I produce EPUB with embedded fonts. According to our MR wiki, if I wish iBooks to use my "specified fonts", I need to add to META-INF a com.apple.ibooks.display-options.xml file with the following text.


<?xml version="1.0" encoding="UTF-8"?>
<display_options>
<platform name="*">
<option name="specified-fonts">true</option>
</platform>
</display_options>


I would like to know what is the simplest and easiest way to do it. What I tried (which failed) is:
- rename epub to zip and extract here.
- open META-INF and add the com.apple.ibooks.display-options.xml file
- create a new folder. Name it.
- insert the new META-INF folder (with the new file)
- insert mime and OEBPS folders
- compress to zip
- rename to EPUB.

Easy to do but, it does not work. Something in the above process is wrong and the newly created EPUB can't be opened.

PS: XML processing instructions in all my EPUBs begin with:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
I do not know if this may conflict with the new com.apple file.

Doitsu
09-30-2012, 02:47 AM
On my Windows machine the following steps worked:

1. Rename .epub to .zip.
2. Double-click the .zip file to open it
3. Drag & drop the .xml file to the META-INF folder.
4. Close the Explorer window that shows the contents of the .zip file.
5. Rename .zip to .epub.

The resulting file with pass epubcheck.

roger64
09-30-2012, 03:22 AM
Thank you. This works and it's simpler. :)

roger64
02-23-2013, 11:35 PM
Hi

I tried it today on some files using an Epubcheck 3 validation. It does not work anymore: I get this message. FlightCrew does not care about this.


Epubcheck Version 3.0

ERROR: À grandes guides v2.epub: Length of the first filename in archive must be 8, but was 45
Validating against EPUB version 2.0

Check finished with warnings or errors


Note: using Linux.

dgatwood
02-24-2013, 12:04 AM
The first file in the archive must be the mimetype file. If it isn't, it won't pass validation. Also, that file must be stored uncompressed (in theory, anyway), and the directories themselves must not appear as separate entries, IIRC.

Getting this right usually requires either a command-line tool or an app that knows how to do it. For example, in OS X, you can usually get away with

cd folder_containing_extraction
zip -Xr9D ../filename.epub mimetype * -x .DS_Store

DiapDealer
02-24-2013, 05:55 AM
With an existing, pre-validated epub, I do something similar to doitsu, but I use 7zip: open the archive in 7zip (no need to rename epub to zip) and drag the xml file into the META-INF folder. Of course if the mimetype file isn't already properly first and uncompressed, it's all moot anyway.

roger64
02-24-2013, 07:29 AM
With an existing, pre-validated epub, I do something similar to doitsu, but I use 7zip: open the archive in 7zip (no need to rename epub to zip) and drag the xml file into the META-INF folder. Of course if the mimetype file isn't already properly first and uncompressed, it's all moot anyway.

I do not understand your last words. :blink:

I take a clean EPUB (see lower down)

Epubcheck Version 3.0

Validating against EPUB version 2.0
No errors or warnings detected.
Open it with 7-zip (1), open META-INF (2), insert the file (3),

Epubcheck is angry:
Epubcheck Version 3.0

ERROR: Brochette de cœurs v2.epub: Length of the first filename in archive must be 8, but was 45
Validating against EPUB version 2.0

Check finished with warnings or errors

Of course, why this file goes from 500k (properties) to 800k (screen 1) is another mystery...

Jellby
02-24-2013, 07:52 AM
It seems 7z has inserted the file first (the string "META-INF/com.apple.ibooks.display-options.xml" is 45 char long), which means that it's not a good way of modifying epubs. Or maybe there's some setting you can change.

DiapDealer
02-24-2013, 08:07 AM
You're absolutely right. :o I never notice the issue before. It appears that 7-zip (at least this version of it) is rearranging the archive a bit rather than just adding the file.

The Tweak Book feature of calibre would be my suggestion in that case. No conversion necessary to do that. 1) Explode the ePub. 2) copy the the xml file to META-INF. 3) Rebuild the book.

I just verified that the above process keeps Epubcheck happy. It's unfortunate that there's not a less convoluted way for adding this file to ePubs--for users on platforms other than OS X, that is. The situation seems ripe for a "tool/addon."

roger64
02-24-2013, 08:10 AM
It seems 7z has inserted the file first (the string "META-INF/com.apple.ibooks.display-options.xml" is 45 char long), which means that it's not a good way of modifying epubs. Or maybe there's some setting you can change.

I am keen to learn. calibre seems to be a little overkill, but if there is nothing else. :)

Jellby
02-24-2013, 08:30 AM
Well, chances are a different program like WinZip or WinRar may behave better. Or maybe you can use 7-zip through the command line.

But it seems it doesn't work with the command line either:
http://sourceforge.net/p/sevenzip/feature-requests/1055/

Toxaris
02-24-2013, 10:51 AM
You could also use ePUBpack, there is a links somewhere on the forum.

roger64
02-24-2013, 06:38 PM
You could also use ePUBpack, there is a links somewhere on the forum.

I'll try it, though it does not work with Wine (a pity for a GPL tool). At least it's considerably lighter than calibre for this purpose.

If somebody can explain, I've noticed this on a commercial EPUB:

- When you extract the files which are included in the zip (a former epub renamed zip), the com.apple.ibooks.display-options.xml file is included as usual close to the container.xml file in the META-INF folder.

- BUT, it appears alone within a Misc folder when you open the EPUB with Sigil.

:blink:

JSWolf
02-24-2013, 06:42 PM
I do use WinRAR and yes, you can add files to an ePub without messing up the structure. So you could add the XML and it would not cause a problem.

DiapDealer
02-24-2013, 06:43 PM
If somebody can explain, I've noticed this on a commercial EPUB:

- When you extract the files which are included in the zip (a former epub renamed zip), this apple xml file is included as usual close to container.xml file in the META-INF folder.

- BUT, it appears within a Misc folder when you open the EPUB with Sigil.

:blink:
That's "expected" behavior. It just appears to be in the 'Misc' folder when open in Sigil. Just part of whatever it is Sigil has to do to "ignore" that file. It definitely stays in the META-INF folder after you close/save the ePub though. Not to worry.

dgatwood
02-25-2013, 03:26 AM
I'll try it, though it does not work with Wine (a pity for a GPL tool). At least it's considerably lighter than calibre for this purpose.


If you're running Linux or OS X, just use the command-line zip tool. The syntax should be the same as in OS X.

roger64
02-25-2013, 04:01 AM
I do use WinRAR and yes, you can add files to an ePub without messing up the structure. So you could add the XML and it would not cause a problem.

Thanks. At long last using WinRAR has been the most convenient solution for me. Though WinRAR is also working with Linux (Wine), I took no chance and did use a virtualised XP. Now the EPUB files have a successful Epubcheck validation and this dammed apple.xml file appears in the Misc folder when I open Sigil.

Thanks to all of you. :thumbsup:

Jellby
02-25-2013, 04:39 AM
If you are on linux, it's best to just use the command-line zip, or maybe some front-end like ark, Xarchiver...

roger64
02-25-2013, 05:33 AM
If you are on linux, it's best to just use the command-line zip, or maybe some front-end like ark, Xarchiver...

You're surely right but I went for what looked the easiest for me and my 45 files as I had already lost some time on this. Unhappily, the sky is not my limit...

I also used GPRename (Linux) to batch rename files from epub to zip and back, which saved some time.

If you have a command available for this, I'll be happy to try it next time.

Jellby
02-25-2013, 05:43 AM
For renaming?

rename 's/.zip/.epub/' *e.zip

(or with other versions of rename: rename .zip .epub .zip)

roger64
02-25-2013, 05:56 AM
No. Renaming was easy enough (see screenshot) though your solution is really nice.

I mean, opening the zip file (s), inserting the apple file in META, and back.

Jellby
02-25-2013, 06:21 AM
zip file.epub META-INF/com.apple.ibooks.display-options.xml

It requires having the apple file in a META-INF directory, though.

roger64
02-25-2013, 07:13 AM
zip file.epub META-INF/com.apple.ibooks.display-options.xml

It requires having the apple file in a META-INF directory, though.

Looks very useful. How can I resist messing around... :)

Following what you said, I put the apple.xml file in a META-INF folder, alongside with two EPUBS (screenshot).

I then tried the customary:
roger@lmde64:~/Bureau/Test$ zip *.epub META-INF/com.apple.ibooks.display-options.xml
updating: META-INF/com.apple.ibooks.display-options.xml (deflated 27%)
adding: Cocardes et dentelles v2.epub (deflated 1%)
roger@lmde64:~/Bureau/Test$

Result: Only the first EPUB file was correctly processed. The second one, "Cocardes et dentelles v2" was not. Is there a way to batch this?

If I take away from the Test folder the first processed EPUB and then repeat the same command, the second EPUB is correctly processed. This can go quickly...

Jellby
02-25-2013, 07:40 AM
I then tried the customary:
roger@lmde64:~/Bureau/Test$ zip *.epub META-INF/com.apple.ibooks.display-options.xml
updating: META-INF/com.apple.ibooks.display-options.xml (deflated 27%)
adding: Cocardes et dentelles v2.epub (deflated 1%)
roger@lmde64:~/Bureau/Test$

Result: Only the first EPUB file was correctly processed. The second one, "Cocardes et dentelles v2" was not.

Not only that, but the whole second EPUB was added to the first, that's the way the zip command works. What you did is equivalent to:

zip file1.epub file2.epub apple.xml

which adds file2.epub and apple.xml to file1.epub.

For what you want, you could use bash loops, which may look daunting, but it's really simple:

for i in file1.epub file2.epub
do zip "$i" apple.xml
done

(the first line is just "repeat the block, each time assigning to the variable 'i' one of the values listed"). The linebreaks are important, but you can replace them with semicolons:

for i in file1.epub file2.epub; do zip "$i" apple.xml; done

(putting $i between quotes ensures that it works properly if the filename includes spaces, in which case, of course, you should write them between quotes in the first line as well).

roger64
02-25-2013, 08:10 AM
I am sorry to give you all this trouble. :o

I found that the first try was very convenient for my level of understanding (even then I did a mistake...) as it allows to process one EPUB at a time. Furthermore, as we can use again and again exactly the same command, it's easy to use. We just have to replace an EPUB with the next one.

I'm afraid the "loop" thing is way beyond my capacity. I did not expect it to become so quickly so complex. Just writing long file names for the terminal (using antislashes and things like that) is a chore.

So, I will keep myself at the first level. Thank you for your help, explanations and brilliant solution that, for sure, I will use next time... :thumbsup:

Jellby
02-25-2013, 08:32 AM
Just writing long file names for the terminal (using antislashes and things like that) is a chore.

Easier, use quotes: "Cocardes et dentelles v2.epub"

(that sometimes fails with exclamation marks, probably a bug in my bash version, just avoid exclamation marks).

and you know you can use autocompletion too, don't you? Write the first few letters of the filename and press the TAB key, the filename will probably be completed (as far as it can be, without ambiguity)

roger64
02-25-2013, 07:23 PM
Hi

Just the time to sleep over it with a little nagging remorse for being lazy. OK, I must admit once again you're very right. I did a try with three EPUB and my META-INF folder and it works brilliantly.

Once all the files were here, I used TAB to auto-complete. I had three EPUB with three filenames beginning with "La ". The terminal wrote every successive name with antislashes but who cares?

roger@lmde64:~/Bureau/Test$ for i in La\ brune\ et\ la\ blonde\ v2.epub La\ grande\ fête\ v2.epub La\ main\ aux\ dames\ v2.epub; do zip "$i" META-INF/com.apple.ibooks.display-options.xml; done
adding: META-INF/com.apple.ibooks.display-options.xml (deflated 27%)
adding: META-INF/com.apple.ibooks.display-options.xml (deflated 27%)
adding: META-INF/com.apple.ibooks.display-options.xml (deflated 27%)
roger@lmde64:~/Bureau/Test$


This is the code I will keep

for i in FILE; do zip "$i" META-INF/com.apple.ibooks.display-options.xml; done


This one works not only for one but for as many files as you wish (once their name has been added, even if the name includes some whitespace).

:thumbsup:

Jellby
02-26-2013, 04:16 AM
and... you can also use wildcards:

for i in *.epub; do zip ...

;)

dgatwood
02-26-2013, 11:30 PM
Looks very useful. How can I resist messing around... :)

Following what you said, I put the apple.xml file in a META-INF folder, alongside with two EPUBS (screenshot).

I then tried the customary:
roger@lmde64:~/Bureau/Test$ zip *.epub META-INF/com.apple.ibooks.display-options.xml
updating: META-INF/com.apple.ibooks.display-options.xml (deflated 27%)
adding: Cocardes et dentelles v2.epub (deflated 1%)
roger@lmde64:~/Bureau/Test$

Result: Only the first EPUB file was correctly processed. The second one, "Cocardes et dentelles v2" was not. Is there a way to batch this?

If I take away from the Test folder the first processed EPUB and then repeat the same command, the second EPUB is correctly processed. This can go quickly...

The correct commands would be:


mkdir ex
cd ex
unzip /path/to/file.epub

[modify files here]

zip -Xr9D ../file-edited.epub mimetype * -x .DS_Store



Those flags (-X -r -9 -D and "-x .DS_Store") are pretty much required for proper spec conformance.

Then repeat for the next book in a different directory. You can create only a single zip file per command. Everything after that is considered to be a file that you want to include *in* the output file.

Jellby
02-27-2013, 04:13 AM
Those flags (-X -r -9 -D and "-x .DS_Store") are pretty much required for proper spec conformance.

Not really. -r is, because otherwise the files in the subdirectories are not stored. But the rest just make the epub file somewhat smaller. -9 simply uses highest compression level, -D does not include entries for the directories themself, and -X does not store additional file attributes. As far as I know, neither -X nor -D are required for ePub compliance. And "-x .DS_Store" may be required only if .DS_Store files exist (in a Mac?)

Anyway, for the problem is here, which is adding a specific file to an existing ePub, creating one from scratch is a bit of an overkill...

dgatwood
02-28-2013, 01:07 AM
Not really. -r is, because otherwise the files in the subdirectories are not stored. But the rest just make the epub file somewhat smaller. -9 simply uses highest compression level, -D does not include entries for the directories themself, and -X does not store additional file attributes. As far as I know, neither -X nor -D are required for ePub compliance.

I've seen epubcheck scream if you don't have some of those flags. I'm not positive about which ones, but at least one of them is definitely required. Probably not -9; it's just a good idea. I think it was the -X flag, without which, at least in OS X, you get all sorts of errors about illegal fields in the ZIP file caused by the way it preserves file permissions and EAs. I'm assuming most of the same behavior occurs in Linux.

And "-x .DS_Store" may be required only if .DS_Store files exist (in a Mac?)


Right. The hack to remove Finder turds is definitely not required on Linux. :)