Thoughts on new epub3 tool: generate guide from Landmarks

[DiapDealer]

For the purposes of this discussion, I really think we should separate #1from #2 & #3. In other words: "how do we want to treat #2 & #3?" And then "how do want to treat #1?"

Lumping them together only creates confusion, I think. Especially in light of the fact that I think #1 is a no-brainer: make it a manual menu option (so people can validate without having to save first), AND automate it upon Save(As), if feasible (because having manifest properties properly set is not an optional part of the spec, and properly setting them will never cause problems).

That leaves #2 and #3. Which I think should be combined into one, backward-compatibility action, and should be optional. Whether it's optional because it's left as a manual menu-action only, or because the user can opt out of automatically having them happen upon Save(As) makes no difference to me.

[KevinH]

We could easily combine 2 and 3 into a single "backwards compatibility" option.
I still need to study the code to see if making the ncx totally optional under epub 3 would be easy. Much of the earlier code required it (before epub3).

I will merge 2 and 3 into a single routine and change the menu in master. Something like:

- Generate NCX and Guide for backwards compatibility

[KevinH]

I wish Sigil had a "Publish" or "For Production" button that would run epubcheck if installed and then do the things that only need to be done once - like doing backwards compatibility, and manifest properties updating before saving the epub.

[DiapDealer]

Thank you for understanding what I meant when I transposed the numbers. So much for eliminating confusion, huh?

I'll try to mitigate the mess of my post with some editing.

[Turtle91]

Originally Posted by KevinH

I wish Sigil had a "Publish" or "For Production" button that would run epubcheck if installed and then do the things that only need to be done once - like doing backwards compatibility, and manifest properties updating before saving the epub.

Says the guy with complete control over what Sigil does... lolz

[KevinH]

Would you use a menu that said "Save for Production Use"? And even if you did, how many future novice users would it just confuse?

So even though I think it would make things simple for me codewise, I really do not think it would be used.

Originally Posted by Turtle91

Says the guy with complete control over what Sigil does... lolz

[Turtle91]

A menu item that said something like "Finalize" or "Publish" or "Push this button as the VERY LAST thing you do on this ePub" would be fairly obvious. Newbs go through a fairly short/steep learning curve when they first use Sigil anyway. I don't think that kind of a button would be hard to understand.

I'm assuming these ePub3 auto-save functions would only be a factor if you are working in ePub3...these features wouldn't even be looked at if you were still in ePub2. When I finally get around to making the switch to 3, I would like the idea of having the "finalize/publish" button rather than an auto-save feature. There are already several buttons I push in the editing process when finishing the book: spell-check, css-cleanup, Generate TOC, epubcheck...really easy to add/replace one of those with a "finalize ePub3" button.

[Tex2002ans]

Originally Posted by KevinH

Would you use a menu that said "Save for Production Use"? And even if you did, how many future novice users would it just confuse?

It would be similar to GIMP's or InDesign's "Save As" and "Export".

Personally, I just think these cause confusion for new users.

Example, GIMP always complaining about "making sure you save as xcf", when most basic users would just want to 'Save As' JPG or PNG.

Personally, I would keep all EPUB2 backwards compatibility on by default, then allow to disable in a menu option. Advanced users can disable the option if wanted, similar to Edit > Preferences > General Settings > Mend XHTML Source Code On.

[KevinH]

Good points.

Yes, this discussion only impacts epub3 users. A "Finalize" button or menu would not really be needed for an epub2.

If updating the epub3 manifest properties was cheap and fast, no worries but it needs to run in a bunch of threads concurrently to ask each html resource to check its contents and report back if it does specific things.

We just have to figure out the best place to make this happen once after all changes, thus my wish for some way of knowing when it would be a good time to do this for epub3.

Originally Posted by Turtle91

A menu item that said something like "Finalize" or "Publish" or "Push this button as the VERY LAST thing you do on this ePub" would be fairly obvious. Newbs go through a fairly short/steep learning curve when they first use Sigil anyway. I don't think that kind of a button would be hard to understand.

I'm assuming these ePub3 auto-save functions would only be a factor if you are working in ePub3...these features wouldn't even be looked at if you were still in ePub2. When I finally get around to making the switch to 3, I would like the idea of having the "finalize/publish" button rather than an auto-save feature. There are already several buttons I push in the editing process when finishing the book: spell-check, css-cleanup, Generate TOC, epubcheck...really easy to add/replace one of those with a "finalize ePub3" button.

[KevinH]

For the record, not adding an ncx resource to epub3 will take some work. FolderKeeper right now always creates it and it is the target of connect signals/slots. Having an ncx resource be present is also assumed in many places including ImportEPUB.cpp.

So we if want to relax that constraint for epub3 users, I would like to hold off on making these invasive changes until after we have a new version of Sigil (non-beta) out there, in case this change creates issues.

KevinH

[KevinH]

Okay to close off this topic: we have a new branch "optncx" which does not require epub3 epubs to have an NCX, and that uses two epub3 tools menus - one to generate an NCX and Guide from the Nav, and one to now Remove the NCX and Guide.

So no more warnings about creating an NCX on epub3 anymore, but still making it easy to edit your epub3 and before final save generating an NCX and Guide to help with backwards compatibility.

This branch is now undergoing testing. Once we know we have not broken anything we will probably merge this into master for the next release.

For some future version will can worry about making things automatic by default or not and how to let the user control that.

[DiapDealer]

As a result of now being able to create/open/edit/save EPUB3s without an ncx, plugin devs should make sure their EPUB3-compatible plugins test for the existence of an ncx before attempting to parse or alter it. I don't expect there will be that many, but it could potentially cause some breakage when the next version of Sigil is released.

[Doitsu]

Originally Posted by DiapDealer

As a result of now being able to create/open/edit/save EPUB3s without an ncx, plugin devs should make sure their EPUB3-compatible plugins test for the existence of an ncx before attempting to parse or alter it. I don't expect there will be that many, but it could potentially cause some breakage when the next version of Sigil is released.

I haven't had time to test the new "optncx" branch. Will be bk.gettocid() return None for epub3 books without toc.ncx or will it raise a custom Sigil error?

[KevinH]

Originally Posted by Doitsu

I haven't had time to test the new "optncx" branch. Will be bk.gettocid() return None for epub3 books without toc.ncx or will it raise a custom Sigil error?

I will take a look at that.

Thanks for the head's up.

Kevin

[KevinH]

Okay checked the wrapper.py code and if no file in the manifest has the correct mimetype for the ncx ("application/x-dtbncx+xml"), it will return a python None, not a empty string. And this case of no ncx is already properly handled when rebuilding the spine attributes.

So to detect if an epub3 has an ncx or not, you can check the return value against None.

    def gettocid(self):
        for id in self.id_to_mime:
            mime = self.id_to_mime[id]
            if mime == "application/x-dtbncx+xml":
	        return id
        return None