Thoughts on new epub3 tool: generate guide from Landmarks

KevinH · 07-05-2019, 01:49 PM

Hi All,
I am looking for some input from users on a change in how semantics are managed for epub3.

Right now for epub3, Sigil properly puts and updates semantics in the nav landmarks but tries hard to keep the older (actually deprecated in epub3) guide section of the content opf in sync.

Unfortunately, if guide and the nav landmarks are ever at odds, the sync is lost forever (or until the content.opf guide is manually edited).

To prevent these issues for epub3 users, I would like to stop trying to keep the guide section of the opf updated at all under epub3. But then add a new epub3 tool menu "Generate Guide from Nav Landmarks".

That way if a epub3 user wants to create an epub3 that is very compatible with older epub2 reading devices, they can simply use "Generate NCX from Nav" and "Generate Guide from Nav" epub3 tools to automatically rebuild a correct ncx and correct guide section in the opf before saving.

If we decide to go that way, for epub3 users we could in fact automatically run all 3 epub3 specific tools on any Save or SaveAs:

1. update epub3 manifest properties
2. generate NCX from Nav
3. generate OPF Guide from Nav

thereby building an epub3 epub that will be as correct as possible and as compatible as possible with epub2 readers automatically.

These proposed changes would not change anything for people creating epub2 epubs at all.

Thoughts on these proposed changes and thoughts on automating backwards epub2 compatibility when saving epub3's are welcome.

Notjohn · 07-05-2019, 02:00 PM

Sounds good to me, though to be sure I've never played about with epub3.

DiapDealer · 07-05-2019, 02:21 PM

The first thing someone will complain about is not being able opt-out of the auto-enforcement of backward compatibility. I would plan on providing a user preference as to whether or not numbers #2 and #3 are run on Save(As) for EPUB3s. As for #1: I can't think of a single reason NOT to update the manifest properties of EPUB3s automatically.

KevinH · 07-05-2019, 02:26 PM

@NotJohn ... Understood, but everything done in epub2 can be done in epub3 with some extra additions for backwards compatibility for older readers. Given how the industry is moving (or has already moved) to epub3 (Amazon kindle conversion works with it, ADE accepts it, Kobo .kepub, and more heavily used internationally), my vote is to create an epub3 that is as backwards compatible with epub2 only readers just to keep them working and alive longer.

The question is that okay with epub3 devs? Or would epub3 devs rather drop the ncx and drop the guide and make an epub3 that ignores epub2 compatibility.

KevinH · 07-05-2019, 02:30 PM

So, if we decide to go this way, we could leave 2 and 3 as epub3 tools and let epub3 devs decide to use them or not, or automate them but have to add preferences to allow epub3 devs to control running them during Save or SaveAs.

The issue is Sigil has got a lot of General Settings right now... where should/would these extra prefs go?

Quote:

Originally Posted by DiapDealer

The first thing someone will complain about is not being able opt-out of the auto-enforcement of backward compatibility. I would plan on providing a user preference as to whether or not numbers #2 and #3 are run on Save(As) for EPUB3s. As for #1: I can't think of a single reason NOT to update the manifest properties of EPUB3s automatically.

KevinH · 07-05-2019, 02:34 PM

FWIW, if we do this, we should finally make including an NCX in the epub3 optional as well.
We could default epub3 to not make an ncx and not include a guide at all, unless the user specifically enabled those backwards compatibility features.

DiapDealer · 07-05-2019, 02:52 PM

Quote:

Originally Posted by KevinH

So, if we decide to go this way, we could leave 2 and 3 as epub3 tools and let epub3 devs decide to use them or not

I'd be OK with this.

odamizu · 07-05-2019, 03:30 PM

Quote:

Originally Posted by KevinH

1. update epub3 manifest properties
2. generate NCX from Nav
3. generate OPF Guide from Nav

I very much like the addition of #3 to the epub3 tools. This will be very handy.

I would like to be able to run each of these 3 tools manually and individually at will, without having to save.

I personally do not need the option to automate these tools on Save(As), but have no objection to having automation offered to users.

Quote:

Originally Posted by KevinH

FWIW, if we do this, we should finally make including an NCX in the epub3 optional as well.
We could default epub3 to not make an ncx and not include a guide at all, unless the user specifically enabled those backwards compatibility features.

I will always include an ncx and guide in my epub3s for backwards compatibility. If these items are not included by default, I prefer to be able to add them in manually through the epub3 tools menu rather than having to do a Save(As).

Thank you!

DNSB · 07-05-2019, 04:16 PM

I would like the addition of #3 to the epub3 tools. As to whether or not those tools should run automatically on save, that is an option I would probably not use but no objections to it being present as long at the manual run option still exists.

KevinH · 07-05-2019, 04:55 PM

Okay, so it sounds like adding a "generate guide from nav" epub3 tools menu item should be added.

Then if and only if we provide preferences to enable/disable each, allow them to be automated on epub3 Save/SaveAs.

Is that pretty much what people want to see.p?

lumpynose · 07-05-2019, 11:29 PM

I like the idea of having it do all 3 when I do a save, and I agree that it would be prudent to have a user preference to control it.

DiapDealer · 07-06-2019, 06:47 AM

I don't see any point in allowing a user to decide to NOT update the manifest properties when saving. Having the manifest properties correctly set is not a question of optional backward compatibility like the other two actions. It's a question of error/not error when validating. So while I think it's fine (and wise, in fact) to continue to allow a user to manually update the manifest properties anytime they like (via a menu action), I see no point in allowing them to opt out of an automatic update of the manifest properties when saving.

As for the other two actions: I have no preference as to whether or not they're manual menu actions, or if they're applied automatically at save time, or both (though I'd suggest both menu actions be combined into a single "ensure backward compatibility" action). I'd just rather a user not have the backward compatibility actions forced upon them. Whether that's achieved by NOT automatically doing it when saving, or by offering a preference to opt out of automatically doing it when saving makes no difference to me.

elibrarian · 07-06-2019, 08:56 AM

Quote:

Originally Posted by DiapDealer

I don't see any point in allowing a user to decide to NOT update the manifest properties when saving. Having the manifest properties correctly set is not a question of optional backward compatibility like the other two actions. It's a question of error/not error when validating. So while I think it's fine (and wise, in fact) to continue to allow a user to manually update the manifest properties anytime they like (via a menu action), I see no point in allowing them to opt out of an automatic update of the manifest properties when saving.

And then again - we've been making backwards compatible epub3's for three years now, without ever using that tool. I seem to remember I tried it, right after Sigil was made epub3-savvy, got an error in some manifest properties (don't ask, I don't remember the exact error), and never touched the thing again.

My point being, if it's not enforced to day, please don't enforce it now, but leave the decision to the user.
Regards,

Kim

KevinH · 07-06-2019, 09:36 AM

Then you were a bit lucky and never used any epub3 features. Which makes sense if you want to be fully epub2 compatible.

Sigil tries hard to add the svg manifest property to the html file that shows the cover image, and the manifest property of the cover image file itself. But if you use other svg, javascript, external media resources, mathml, etc in your epub3 then the required manifest properties should be set.

The reason we did not automate this action previously is that we have to walk every single xhtml file parsing each fully and then walking the parsed tree node by node to see if you use svg, mathml, have an href that goes outside the epub, uses javascript, etc and this is really time consuming and requires all xhtml files be well formed. To top it all off, it really only needs to be done once right before saving the final epub.

It really can't break anything so using it should do no damage.

Because of how long it could take, making it automatic on *every* save, may still not be the best idea.

This is true for the other epub3 tools as well. They all really only have to be used once before the final save.

I just can't see a way to detect if the user is done editing and wants this save to be the one.

Quote:

Originally Posted by elibrarian

And then again - we've been making backwards compatible epub3's for three years now, without ever using that tool. I seem to remember I tried it, right after Sigil was made epub3-savvy, got an error in some manifest properties (don't ask, I don't remember the exact error), and never touched the thing again.

My point being, if it's not enforced to day, please don't enforce it now, but leave the decision to the user.
Regards,

Kim

Evil Overlord · 07-06-2019, 09:55 AM

I'd love to have #1-3 run automatically on save. As it is, every time I save, I do #1 and 2 manually. I've never been sure whether it's required, but better safe than sorry.

07-06-2019, 06:47 AM	#12
DiapDealer Grand Sorcerer Posts: 27,547 Karma: 193191846 Join Date: Jan 2010 Device: Nexus 7, Kindle Fire HD	I don't see any point in allowing a user to decide to NOT update the manifest properties when saving. Having the manifest properties correctly set is not a question of optional backward compatibility like the other two actions. It's a question of error/not error when validating. So while I think it's fine (and wise, in fact) to continue to allow a user to manually update the manifest properties anytime they like (via a menu action), I see no point in allowing them to opt out of an automatic update of the manifest properties when saving. As for the other two actions: I have no preference as to whether or not they're manual menu actions, or if they're applied automatically at save time, or both (though I'd suggest both menu actions be combined into a single "ensure backward compatibility" action). I'd just rather a user not have the backward compatibility actions forced upon them. Whether that's achieved by NOT automatically doing it when saving, or by offering a preference to opt out of automatically doing it when saving makes no difference to me. Last edited by DiapDealer; 07-06-2019 at 07:05 AM.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Multiple epub:type roles for a file in landmarks nav	jcsalomon	Sigil	0	02-20-2018 02:08 PM
fixed layout landmarks issue	leijoninna	ePub	11	06-14-2013 04:24 AM
Free (Kindle/Nook) A Beginner's Guide to Using Your iPad as a Business Tool	greencat	Deals and Resources (No Self-Promotion or Affiliate Links)	4	10-04-2011 09:50 PM
Free (Kindle) A Beginner's Guide to Using Your iPhone as a Business Productivity Tool	arcadata	Deals and Resources (No Self-Promotion or Affiliate Links)	0	08-29-2011 03:34 AM
Using privately owned landmarks	mr ploppy	Writers' Corner	8	08-10-2011 01:51 PM

07-05-2019, 01:49 PM	#1
KevinH Sigil Developer Posts: 7,643 Karma: 5433388 Join Date: Nov 2009 Device: many	Thoughts on new epub3 tool: generate guide from Landmarks Hi All, I am looking for some input from users on a change in how semantics are managed for epub3. Right now for epub3, Sigil properly puts and updates semantics in the nav landmarks but tries hard to keep the older (actually deprecated in epub3) guide section of the content opf in sync. Unfortunately, if guide and the nav landmarks are ever at odds, the sync is lost forever (or until the content.opf guide is manually edited). To prevent these issues for epub3 users, I would like to stop trying to keep the guide section of the opf updated at all under epub3. But then add a new epub3 tool menu "Generate Guide from Nav Landmarks". That way if a epub3 user wants to create an epub3 that is very compatible with older epub2 reading devices, they can simply use "Generate NCX from Nav" and "Generate Guide from Nav" epub3 tools to automatically rebuild a correct ncx and correct guide section in the opf before saving. If we decide to go that way, for epub3 users we could in fact automatically run all 3 epub3 specific tools on any Save or SaveAs: 1. update epub3 manifest properties 2. generate NCX from Nav 3. generate OPF Guide from Nav thereby building an epub3 epub that will be as correct as possible and as compatible as possible with epub2 readers automatically. These proposed changes would not change anything for people creating epub2 epubs at all. Thoughts on these proposed changes and thoughts on automating backwards epub2 compatibility when saving epub3's are welcome.

07-05-2019, 02:00 PM	#2
Notjohn mostly an observer Posts: 1,515 Karma: 987654 Join Date: Dec 2012 Device: Kindle	Sounds good to me, though to be sure I've never played about with epub3.

07-05-2019, 02:21 PM	#3
DiapDealer Grand Sorcerer Posts: 27,547 Karma: 193191846 Join Date: Jan 2010 Device: Nexus 7, Kindle Fire HD	The first thing someone will complain about is not being able opt-out of the auto-enforcement of backward compatibility. I would plan on providing a user preference as to whether or not numbers #2 and #3 are run on Save(As) for EPUB3s. As for #1: I can't think of a single reason NOT to update the manifest properties of EPUB3s automatically.

07-05-2019, 02:26 PM	#4
KevinH Sigil Developer Posts: 7,643 Karma: 5433388 Join Date: Nov 2009 Device: many	@NotJohn ... Understood, but everything done in epub2 can be done in epub3 with some extra additions for backwards compatibility for older readers. Given how the industry is moving (or has already moved) to epub3 (Amazon kindle conversion works with it, ADE accepts it, Kobo .kepub, and more heavily used internationally), my vote is to create an epub3 that is as backwards compatible with epub2 only readers just to keep them working and alive longer. The question is that okay with epub3 devs? Or would epub3 devs rather drop the ncx and drop the guide and make an epub3 that ignores epub2 compatibility.

07-05-2019, 02:34 PM	#6
KevinH Sigil Developer Posts: 7,643 Karma: 5433388 Join Date: Nov 2009 Device: many	FWIW, if we do this, we should finally make including an NCX in the epub3 optional as well. We could default epub3 to not make an ncx and not include a guide at all, unless the user specifically enabled those backwards compatibility features.

07-05-2019, 04:16 PM	#9
DNSB Bibliophagist Posts: 35,356 Karma: 145435140 Join Date: Jul 2010 Location: Vancouver Device: Kobo Sage, Forma, Clara HD, Lenovo M8 FHD, Paperwhite 4, Tolino epos	I would like the addition of #3 to the epub3 tools. As to whether or not those tools should run automatically on save, that is an option I would probably not use but no objections to it being present as long at the manual run option still exists.

07-05-2019, 04:55 PM	#10
KevinH Sigil Developer Posts: 7,643 Karma: 5433388 Join Date: Nov 2009 Device: many	Okay, so it sounds like adding a "generate guide from nav" epub3 tools menu item should be added. Then if and only if we provide preferences to enable/disable each, allow them to be automated on epub3 Save/SaveAs. Is that pretty much what people want to see.p?

07-05-2019, 11:29 PM	#11
lumpynose Wizard Posts: 1,086 Karma: 6719822 Join Date: Jul 2012 Device: Palm Pilot M105	I like the idea of having it do all 3 when I do a save, and I agree that it would be prudent to have a user preference to control it.

07-06-2019, 09:55 AM	#15
Evil Overlord Enthusiast Posts: 39 Karma: 972 Join Date: Jul 2011 Device: Kindle 3	I'd love to have #1-3 run automatically on save. As it is, every time I save, I do #1 and 2 manually. I've never been sure whether it's required, but better safe than sorry.