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

[philja]

To test DNSB's theory that even an internal link from a non-linear resource (the nav) back to itself is enough to fool the epubcheck test (why a link from a non-linear resource to itself would make any difference is beyond me).

I changed the Sigil User's Guide nav landmarks section to to add an internal back link (see the last li I added below):


Code:

<nav epub:type="landmarks" id="landmarks" hidden="">
<h1>Landmarks</h1>
<ol>
<li>
<a epub:type="cover" href="Text/cover.xhtml">Cover</a>
</li>
<li>
<a epub:type="bodymatter" href="Text/introduction.xhtml">Text</a>
</li>
<li>
<a epub:type="toc" href="Text/toc.xhtml">Table of Contents</a>
</li>
<li>
<a epub:type="toc" href="#toc">Nav Table Of Contents</a>
</li>
</ol>
</nav>

And I removed the link from the xhtml toc to the nav I had added just to make it pass, and sure enough, it passes epubcheck!

So DNSB's theory is right! We can prevent the whole epubcheck bug from hitting by just adding an internal link from the nav landmarks back to the nav table of contents and that fools the code into thinking that all non-linear resources are reachable from some linear resource.

So that looks like the most simple answer for the moment. Are there any adverse consequences from having two toc type references in the landmarks?

----------

I had been trying to make a link from the HTML toc to the nav but got the error that the nav.xhtml could not be found.

The answer to that was remembering what Kevin had said back in post #17 -- that nav.xhtml was not in the Text folder. It requires referencing in the link as ../nav.xhtml. This I verified by opening the User Guide in Sigil.

Strangely, though, Sigil shows the nav.xhtml in the Book Browser window as being the last entry in the Text folder. Closing the Text folder makes the nav file disappear from the Book Browser listing.

Wouldn't it be less misleading for the Book Browser to display the nav.xhtml file below the Misc folder and next to the content.opf?

[KevinH]

Please note:

1. epub3 does not specify a normalized layout for an epub unlike the old epub2 recomendations.

2. The BookBrowser is *not* a file browser. It shows "virtual folders" that are groups files of similar type to make working with files possible no matter the actual internal layout used in the epub.

3. To see the actual full path for each file inside the book folder, you have to enable that in Sigil Preferences.

4. The nav xhtml file may be inside the Text folder or someplace else as long as the opf manifest is correct. Sigil will default to creating it beside the opf unless otherwise informed.

5. Use Sigil to select images to insert, or insert links, and it will create the proper relative paths for you.

6. If you want to craft and enter links by hand, you should enable BookBrowser to show the full book paths for all files so you can create the proper links.

[philja]

[QUOTE by KevinH]2. The BookBrowser is *not* a file browser. It shows "virtual folders" that are groups files of similar type to make working with files possible no matter the actual internal layout used in the epub.

3. To see the actual full path for each file inside the book folder, you have to enable that in Sigil Preferences.

4. The nav xhtml file may be inside the Text folder or someplace else as long as the opf manifest is correct. Sigil will default to creating it beside the opf unless otherwise informed.[/QUOTE]

Thanks for clarifying #2. For #3, I had overlooked that setting in Preferences. It certainly makes it easier.

For #4: epub3-itizer created the nav at OEBPS/nav.xhtml and BookBrowser displays it inside the Text folder which I find misleading.

Sigil (in my linux and MacBook) defaults to creating new epub3 files with the path OEBPS/Text/nav.xhtml so clearly within the Text folder. I don't see a preference setting for informing Sigil otherwise.

The manifest displays are coherent in each case so no real problem as far as functioning is concerned.

[KevinH]

For #4: epub3-itizer created the nav at OEBPS/nav.xhtml and BookBrowser displays it inside the Text folder which I find misleading.

No, as I tried to explain. Each folder in BookBrowser shows virtual groupings of files. So no matter where nav.xhtml is physically located in the epub, it will always show up in BookBrowser in the "virtual folder" that represents Text (application/xhtml+xml media types).

Again there is no recommended or constraints on epub3 layout. There need not be a physical folder called Text at all or there could be multiple physical folders called book1 and book2 or ...

So to work with all files of a single type by multi-selecting, the files must appear as "contiguous" in BookBrowser no matter how they physically laid out.

That is the role of BookBrowser. Real book paths can be enabled if you care. Or you can move things around to make physical folders to match the virual folders (standardize it like old Sigil did).

[DNSB]

Minor nit. There are some constraints on the structure of an ePub3 file. The mimetype file must be in the root of the zip container and be stored uncompressed while the META-INF directory must exist and must contain the container.xml file.

Other than that, as you say, it's a free for all.

[AlanHK]

Originally Posted by KevinH

2. create the css necessary and link it to the nav so that the nav appears just like a desired xhtml toc in appearance and remove the linear="no" associated with the nav so that the nav itself functions like a directly linked user xhtml toc file (ie it plays 2 roles - both machinereadable nav and user toc). But not everyone wants a user xhtml toc.

If I'm working on an epub3, and the nav has (or can be made to have) all the links I want to display as a TOC, I delete the HTML TOC if there is one and paste the below CSS into the header of the NAV, and set its semantics to be also "Table of Contents". Less hassle then if I add, delete, move things about.

If on the other hand the visible TOC needs things that can't be put in the NAV, I delete it from the spine and make a HTML toc. This omits it from the Kindle conversion so I don't need to worry about how it looks. (If that's going to alarm ePubCheck, I'll have to rethink, as many publishers insist on no EpubCheck errors.)

<style type="text/css">
body {font-family: serif; }
h1 {font-style: italic;  text-align: center;  font-weight: normal;  font-size: 1.8em;}
ol { list-style-type: none;}
li {font-weight: normal; text-align: left;  margin-left: 0;  font-size: 1rem; text-indent: -2em;  margin-top:.5em;}
li li {margin-top:0;}
a {  text-decoration: none;}
    </style>

Originally Posted by philja

To do this, replacing the author HTML toc, would, in my case involve serious editing effort to add loads of anchors to the entries because all my chapters have links back to the HTML toc.

I don't know why headings need a link back to the toc. I remove such links if there are any. Simplifies the code. Every ebook reader has direct buttons to the toc.

[JSWolf]

Originally Posted by AlanHK

If I'm working on an epub3, and the nav has (or can be made to have) all the links I want to display as a TOC, I delete the HTML TOC if there is one and paste the below CSS into the header of the NAV, and set its semantics to be also "Table of Contents". Less hassle then if I add, delete, move things about.

If on the other hand the visible TOC needs things that can't be put in the NAV, I delete it from the spine and make a HTML toc. This omits it from the Kindle conversion so I don't need to worry about how it looks. (If that's going to alarm ePubCheck, I'll have to rethink, as many publishers insist on no EpubCheck errors.)

<style type="text/css">
body {font-family: serif; }
h1 {font-style: italic;  text-align: center;  font-weight: normal;  font-size: 1.8em;}
ol { list-style-type: none;}
li {font-weight: normal; text-align: left;  margin-left: 0;  font-size: 1rem; text-indent: -2em;  margin-top:.5em;}
li li {margin-top:0;}
a {  text-decoration: none;}
    </style>

I don't know why headings need a link back to the toc. I remove such links if there are any. Simplifies the code. Every ebook reader has direct buttons to the toc.

It's a leftover from when there was no easy access to the ToC. I guess it just stick. I find it rather annoying and I also clear these useless links.

[KevinH]

Posted a new version of ePub3-itizer (v060) that better supports Sigil 2.0.0 and later users by using the PySide6 gui toolkit instead of Tk.

There are no functional changes since the prior version (v058) that used the Tk gui.