[Plugin] ePub3-itizer - epub3 output plugin for Sigil

[KevinH]

For epub3, the full identifier is actually a combination of the book identifier plus the modification date and time. Sigil automatically updates this with every save.

From the epub3 spec ...

The Unique Identifier of an EPUB Publication typically SHOULD NOT change with each minor revision to the package or its contents, as Unique Identifiers are intended to have maximal persistence both for referencing and distribution purposes. Each release of an EPUB Publication normally requires that the new version be uniquely identifiable, however, which results in the contradictory need for reliable Unique Identifiers that are changeable.

To redress this problem of identifying minor modifications and releases without changing the Unique Identifier, this specification defines the semantics for a Release Identifier, or means of distinguishing and sequentially ordering EPUB Publications with the same Unique Identifier.

The Release Identifier is not an actual property in the package metadata section, but is a value that can be obtained from two other mandatory pieces of metadata: the Unique Identifier and the last modification date of the Rendition. When the taken together, the combined value represents a unique identity that can be used to distinguish any particular version of an EPUB Publication from another.

To ensure that a Release Identifier can be constructed, each Rendition MUST include exactly one [DCTERMS] modified property containing its last modification date. The value of this property MUST be an [XMLSCHEMA-2] dateTime conformant date of the form:

CCYY-MM-DDThh:mm:ssZ
The last modification date MUST be expressed in Coordinated Universal Time (UTC) and MUST be terminated by the "Z" (Zulu) time zone indicator.

Additional modified properties MAY be included in the package metadata, but they MUST have a different subject (i.e., they require a refines attribute that references an element or resource).

[KevinH]

FWIW, when an ebook with embedded but obfuscated fonts is opened in Sigil, the fonts are automatically de-obfuscated so that they can actually be read and used. They are kept in this deobfuscated state inside Sigil while Sigil is open and editing the file. The obfuscation step is only done on save. So you are free to change book id's when inside Sigil and the fonts will be properly obfuscated based on the new id when saved.

[DiapDealer]

Out of curiosity, what happens with obfuscated fonts when using an export plugin like this one? If the files are copied from the temp directory created for the plugin's use, then..... ?

[KevinH]

Good question. In the sample output plugin, I think there is code to reobfuscate them. But in this plugin, the are written out deobfuscated but no encryption.xml either.

So the user can load the newly generated epub3 into Sigil, and use right click on the fonts to set the desired obfuscation method, idpf or adobe. The save will do what you set.

[KevinH]

The same is true for FolderIn and FolderOut, I think as well.

[DiapDealer]

Thanks. I couldn't remember off-hand if there was reobfuscation code in place, or if it was up to the plugin dev to do it.

[KevinH]

It is up to the plugin devs, but the epub_utils.py has the necessary support routines and sample code (for idpf obfuscating) is in the sample output plugin attached near the front of the plugin dev main thread.

[Mister L]

Originally Posted by KevinH

For epub3, the full identifier is actually a combination of the book identifier plus the modification date and time. Sigil automatically updates this with every save.

From the epub3 spec ...

Thanks, also good to know, very useful to have such an elegant way to differentiate between versions in the frequent case of revisions.

I do notice they explicitly refer to "minor" changes; so it really does come back to the question of what to do when significant changes are being made. If the new file includes major changes to the version, the meta-data, the css, the internal file-structure, removing some text and adding other text, it seems to me that it would make no sense to continue to refer to the new file as merely an iteration of the original file.

Would it be possible to add the option to generate a new ID when updating the file? This would also resolve the issue of "invalid" IDs which are not accepted in their original format in epub3.

[AlanHK]

Originally Posted by DiapDealer

in my opinion, id-changing decisions should always be firmly in the content creator's camp and not an algorithm's. I certainly wouldn't recommend that an epub2 to epub3 converter automatically generate a new book id by default. Let alone attempt to alter the scheme used.

You may be creating an epub, generating an epub2 and then converting to epub3, never releasing the epub2. You probably don't want the uuid you had chosen to be changed.

Originally Posted by DiapDealer

Something like this would be better in its own ID-related Edit plugin, I think.

Sigil's "Metadata Editor" can add a UUID.
But for some reason, it does not show the existing one or allow you to edit it, or enforce its "uniqueness".
You can add a new UUID with this, and epubcheck doesn't complain there are two UUIDs.

I don't know what real-world effect the UUID has.
Before I even knew the UUID existed, I know I created many epubs by cloning an existing one and replacing text. So they would all have the same UUID.
But they all worked and never had any issues.

[Mister L]

Originally Posted by AlanHK

Sigil's "Metadata Editor" can add a UUID.
But for some reason, it does not show the existing one or allow you to edit it, or enforce its "uniqueness".
You can add a new UUID with this, and epubcheck doesn't complain there are two UUIDs.

Yes, of course; you can also manually add or change it by editing the opf directly. But then you have to generate the UUID first somewhere, add it to the file... If it's a one-time thing it's not a big deal, but if you have to do that to a lot of books it's time-consuming.

Originally Posted by AlanHK

I don't know what real-world effect the UUID has.
Before I even knew the UUID existed, I know I created many epubs by cloning an existing one and replacing text. So they would all have the same UUID.
But they all worked and never had any issues.

Yes, I'd be very surprised if it had any incidence at all from a reader's perspective. I guess it might be important for reference. For my own personal use I am not particularly bothered one way or another but for clients I hold myself to a stricter standard. And just on principle if a thing is explicitly called a "unique" ID then I feel like it shouldn't be the same as the ID of a radically different file.

Anyway maybe this is outside the scope of this particular plugin, in which case apologies for the digression.

[KevinH]

The minor change refers to the book text itself. Not its layout, css, etc. If the text content has had major changes then indeed it must be a new book.

Changing a book from epub2 to epub3 does not mean major changes to the book text content. So adding a uuid when a perfectly good id already exists will not be part of ePub3-itizer.

I will look into adding such functionality to Sigil or providing a plugin at some point.

[Mister L]

Originally Posted by KevinH

The minor change refers to the book text itself. Not its layout, css, etc. If the text content has had major changes then indeed it must be a new book.

Changing a book from epub2 to epub3 does not mean major changes to the book text content. So adding a uuid when a perfectly good id already exists will not be part of ePub3-itizer.

I will look into adding such functionality to Sigil or providing a plugin at some point.

Fair enough. It would be great if it were possible to do that with Sigil or via a plugin though in the cases where it is warranted, thanks very much for considering it.

[AlanHK]

I was about to request/suggest this, but see it was mentioned 5 years ago. Could not see a response, so adding a me-too.

Originally Posted by RbnJrg

Hi Doitsu;
IAlso, it would be nice to have the option in the plugin (as you explained well by PM) that the users can see (or can't) the nav.xhtml file by writing in content.opf:

<itemref idref="navid" linear="no"/>

or

<itemref idref="navid" linear="yes"/>

Maybe with some settings in an .ini file -or a check box in the plugin gui- is possible

Also, the saving location seems to be always in the top level of the user's "Documents and settings" folder (on Windows at least). I'd prefer if it output in the same folder as the source file, so I don't have to click 10 times to select my working folder every time I run it. There is no possibility of overwrite, since it adds "_epub3" to the filename.

[KevinH]

The plugin has no info or idea of where Sigil itself loaded the epub2 originally from. The plugin should remember the last folder something was saved to after its first use.

You really should open the epub3 after creation, validate it passes epubcheck, etc. At this point changing the nav to linear = no or yes can be done by the user in the opf tab quite easily.

[AlanHK]

Originally Posted by KevinH

The plugin has no info or idea of where Sigil itself loaded the epub2 originally from. The plugin should remember the last folder something was saved to after its first use.

Not for me, have to start over in "Documents and settings" every time.

Originally Posted by KevinH

You really should open the epub3 after creation, validate it passes epubcheck, etc. At this point changing the nav to linear = no or yes can be done by the user in the opf tab quite easily.

I don't just send the file out without checking it, and I do epubcheck compulsively.
But fixing the same setting every time I do a conversion is something that programs do more reliably, and faster, than people.

I literally only found out today what the "linear" property does, after editing and distributing epubs for about 10 years, and just shrugging off the ugly extra TOC at the back as something I had to put up with. It's not a well known feature.
There are a couple of other options that would be useful: e.g. to optionally add
<meta property="ibooks:specified-fonts">true</meta> to the OPF so embedded fnts will work in i-devices.

Also easily done manually, if you know you need to do it and know the syntax.