Minimal and ideal EPUB3 testcase?

ibu · 02-27-2017, 04:29 AM

I have a good knowledge in HTML and CSS and some experience with EPUB2 (created with Sigil).

Now I like to start to create EPUB3 files instead of EPUB2 (not as a publisher, just for my own purpose and joy in good source code).

I prefer it, when the code is minimal/puristic and tries to strive to an ideal.

Is there anyone who created an "ideal" and "minimal" EPUB3 to show how consise good source code can be?

I would love to take a look as an inspiration.
Of course attributes like "ideal" and "minimalistic" are highly subjective.

Thank you.

Edit:
Thanks to all, who posted their helpful hints in this thread. A really nice discussion.

As a result I can proudly present a validated minimal epub3 file in the attachement.
It is not perfect, but near

If there will be improvements in the future, I will update the attachement and the code citations.

Attention please!

If you like to look into the source code of the epub, please do not use Sigil to open it, because Sigil will change the file structure automatically.

If you like to test the file on a Kobo, please replace the extension ".epub" by ".kepub.epub".

content.opf

Code:

<?xml 
  version= "1.0" 
  encoding="utf-8"?>
<package 
  version=          "3.0" 
  unique-identifier="book-id" 
  xmlns:dc=         "http://purl.org/dc/elements/1.1/" 
  xmlns=            "http://www.idpf.org/2007/opf">
  <metadata>
    <dc:identifier id="book-id">      urn:ISBN:978-3-908778-02-8</dc:identifier>
    <meta property="dcterms:modified">2017-03-07T12:12:12Z      </meta>
    <dc:language>                     de                        </dc:language>
    <dc:title>                        Tanz der seligen Geister  </dc:title>
    <dc:creator>                      Alice Munro               </dc:creator>   <!-- optional -->
    <dc:publisher>                    Dörlemann                 </dc:publisher> <!-- optional -->
    <dc:date>                         2012                      </dc:date>      <!-- optional -->
  </metadata>
  <manifest>
    <item id="content" href="content.xhtml" media-type="application/xhtml+xml"/>
    <item id="nav"     href="nav.xhtml"     media-type="application/xhtml+xml" properties="nav"/>
    <item id="cover"   href="cover.jpg"     media-type="image/jpeg"            properties="cover-image"/>
  </manifest>
  <spine>
    <itemref idref="content"/>
  </spine>
</package>

nav.xhtml

Code:

<?xml 
  version= "1.0" 
  encoding="utf-8"?>
<!DOCTYPE html>
<html 
  xmlns=     "http://www.w3.org/1999/xhtml" 
  xmlns:epub="http://www.idpf.org/2007/ops" 
  xml:lang=  "de">
<head />
<body>
<h2>Inhaltsverzeichnis</h2>
<nav epub:type="toc">
  <ol>
    <li><a href="content.xhtml#t1">Der Walker Brothers-Cowboy</a></li>
    <li><a href="content.xhtml#t2">Die leuchtenden Häuser</a></li>
    <li><a href="content.xhtml#t3">Bilder</a></li>
    <li><a href="content.xhtml#t4">Danke für die Schlittenfahrt</a>
      <ol>
        <li><a href="content.xhtml#t4_1">Das Büro</a></li>
        <li><a href="content.xhtml#t4_2">Ein Gläschen Medizin</a></li>
      </ol>
    </li>
    <li><a href="content.xhtml#t5">Zur Autorin und zu ihrer Übersetzerin</a></li>
    <li><a href="content.xhtml#t6">Zum Buch</a></li>
    <li><a href="content.xhtml#t7">Impressum</a></li>
  </ol>
</nav>
</body>
</html>

patrik · 02-27-2017, 06:09 AM

Until you get a better response my suggestion would be to take a look at some of the files by Doitsu. (https://www.mobileread.com/forums/asearch.php and add Doitsu in the field "Attached by".)

Toxaris · 02-27-2017, 10:00 AM

It is very subjective... It depends a lot on what you want to have in the ePUB. Just text, multimedia, footnotes, media queries, javascript, etc.

Doitsu · 02-27-2017, 10:15 AM

Quote:

Originally Posted by patrik

Until you get a better response my suggestion would be to take a look at some of the files by Doitsu. (https://www.mobileread.com/forums/asearch.php and add Doitsu in the field "Attached by".)

Thanks for the plug, however, most of my epub3 books are far from being ideal test cases.

@ibu: Check out the official IDPF epub3 sample files, the EPUB 3 Test Suite and the free Azardi epub3 sample books. (Note that some of the features in Azardi epub3 books will only work with the Azardi app.)

Also, as others will undoubtedly point out, unless you plan to implement specific epub3-only features (e.g. JavaScript, page numbers, popup footnotes etc.) and your favorite ebook app has excellent epub3 support, you might want to stick with epub2 books for the time being, because very few apps have epub3 support and even apps with epub3 support rarely support all features.

If you're still not deterred, simply create an epub2 book and convert it to an epub3 book with the Sigil epub3 output plugin.

ibu · 03-06-2017, 03:00 AM

Thanks for your hints

Sorry for my late reply, I didn't get a message about new posts in this thread after the first reply arrived.

No, I'm not deterred. The official sample files are no focussed on beeing "minimal".

Bad luck for me, that "minimal valid code" is not a popular start point. I like it "bottom up" in other situations too.

Independent of this search for a minimal testcase:

As well I'm looking for a good public valid testcase for my Kobo H2O which demonstrates, where the software of the reader still has bugs/faults.
Nice, if it is an ebpub3 one.

In general about ebub3:
Would you disadvise to use it with Kobo?
I do only talk of manipulated code by myself.

Toxaris · 03-06-2017, 04:41 AM

Quote:

Originally Posted by ibu

Thanks for your hints

Sorry for my late reply, I didn't get a message about new posts in this thread after the first reply arrived.

No, I'm not deterred. The official sample files are no focussed on beeing "minimal".

Bad luck for me, that "minimal valid code" is not a popular start point. I like it "bottom up" in other situations too.

Independent of this search for a minimal testcase:

As well I'm looking for a good public valid testcase for my Kobo H2O which demonstrates, where the software of the reader still has bugs/faults.
Nice, if it is an ebpub3 one.

In general about ebub3:
Would you disadvise to use it with Kobo?
I do only talk of manipulated code by myself.

Minimal valid code is a popular start point, but you need to specify it more. The problem is that ePUB3 has a lot of features and there is no example of all the features in use. So, hence the questions what features are you looking for. Then, perhaps, a minimal valid code can be found.

Now, only a portion of the ePUB3 standard is supported in the Kobo. That makes sense though, as it is an e-ink reader and not everything can work on those screens. Whether you need/want to use ePUB3 is up to you. If you need features that are only in ePUB3, then the case is simple. If the features you want/need are also in ePUB2, why not go for ePUB2 for compatibility.

ibu · 03-06-2017, 06:21 AM

My main focus is an epub3 book for a usage on a Kobo.

Therefore any features, which are not supported on a Kobo, must not exist in the minimal epub.

Maybe you like to see my (older) valid minimal testcase for epub2:
https://www.dropbox.com/s/t47l4dlpc3....testcase.epub

Note: For the NCX I'm not really sure, if/how it can be minimalized. Same for the OPF

I'm looking for a comparable testcase for epub3.
In the best, with a minimalized NCX and OPF.

Doitsu · 03-06-2017, 06:44 AM

Quote:

Originally Posted by ibu

In general about ebub3:
Would you disadvise to use it with Kobo?
I do only talk of manipulated code by myself.

AFAIK, the Kobo supports epub3 features, but only in kepub books and you'll probably need to use the Calibre kepub plugin or a similar tool to get started.

For more information on the epub3 features supported in kepub books check out the official website.

ibu · 03-06-2017, 07:13 AM

Do you know a minimal NCX and OPF, which is good as a pattern?

Doitsu · 03-06-2017, 07:51 AM

Quote:

Originally Posted by ibu

Do you know a minimal NCX and OPF, which is good as a pattern?

According to the epub 3.1 standard, NCX files are deprecated, but you might want to still include them, since there are no epub 3.1. compliant readers out there.

As for minimal NCX and OPF files, simply convert a minimal epub2 file with the Sigl epub3 output plugin.

ibu · 03-06-2017, 10:15 AM

@Doitsu
Do I understand it correctly, that Kobo does not support an EPUB3 which has only a nav.xhtml and no NCX?

My own NCX and OPF are not completely minimal. Therefor I'm looking for inspiration, how others has created these files in a minimal form.

Doitsu · 03-06-2017, 11:05 AM

Quote:

Originally Posted by ibu

Do I understand it correctly, that Kobo does not support an EPUB3 which has only a nav.xhtml and no NCX?

No, you misunderstood me. Kobo devices have two rendering engines:

ACCESS NetFront™ (epub3)
RMSDK (=Adobe Digital Edtions) (epub2)

Kobo devices do support epub3 books, but only if they:

a) have been formatted according to Kobo's guidelines and
b) have a .kepub.epub file extension.

You might want to search the MR Kobo forum for more information about the kepub format.

(If a book contains both NCX and NAV files, most epub3 apps ignore the NCX file.)

Quote:

Originally Posted by ibu

My own NCX and OPF are not completely minimal. Therefore I'm looking for inspiration, how others has created these files in a minimal form.

Try this very simple single-page epub2 compatible epub3 book. It contains NCX/NAV files with physical page number references (pagelist) and an .opf file with the required attributes to indicate cover image, toc and srl (start reading location).

ibu · 03-06-2017, 04:26 PM

@Doitsu
Thanks for the helpful explanations about the engines and the way Kobo treats epub3.

I looked at the nav.xhtml of the book "The forerunner" of the link you posted in the last #12. It's a bit far from minimal.

I started to convert my own testcase with the sigil plugin into epub3.

The nav.xhtml result is:

Code:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="de-DE" xml:lang="de-DE">
<head>
    <meta charset="utf-8"/>
    <style type="text/css">
    nav#landmarks, nav#page-list { display:none; }
    ol { list-style-type: none; }
    </style>
  <title></title>
</head>
  <body epub:type="frontmatter">
    <nav epub:type="toc" id="toc">
      <h1>Table of Contents</h1>
      <ol>
        <li>
          <a href="../Text/content.xhtml#toc-1">Der Walker Brothers-Cowboy</a>
        </li>
        <li>
          <a href="../Text/content.xhtml#toc-2">Die leuchtenden Häuser</a>
        </li>
        <li>
          <a href="../Text/content.xhtml#toc-3">Bilder</a>
        </li>
        <li>
          <a href="../Text/content.xhtml#toc-4">Danke für die Schlittenfahrt</a>
        </li>
        <li>
          <a href="../Text/content.xhtml#toc-5">Das Büro</a>
        </li>
        <li>
          <a href="../Text/content.xhtml#toc-6">Ein Gläschen Medizin</a>
        </li>
        <li>
          <a href="../Text/about.xhtml#toc-7">Zur Autorin und zu ihrer Übersetzerin</a>
        </li>
        <li>
          <a href="../Text/about.xhtml#toc-8">Zum Buch</a>
        </li>
        <li>
          <a href="../Text/imprint.xhtml#toc-9">Impressum</a>
        </li>
      </ol>
    </nav>
    <nav epub:type="landmarks" id="landmarks" hidden="">
      <h2>Guide</h2>
      <ol>
      </ol>
    </nav>
</body>
</html>

I have to find out, which of the part I marked bold, are really necessary.

Some notes:

1 When the charset is declared in the xml element, is necessary to declare it a second time in the meta element

2 Do we need two language declarations?

3 Do we need the CSS styles? Are the ebook devices not able to show a nice TOC without it?

4 Should we place the heading "Table of content" inside the title element or in a h1?

5 For what are the attributes in the body and nav element useful?

ibu · 03-06-2017, 04:31 PM

And the same for content.opf.

Code:

<?xml version="1.0" encoding="utf-8"?>
<package 
version="3.0" 
unique-identifier="book-id" 
xmlns="http://www.idpf.org/2007/opf"
xmlns:opf="http://www.idpf.org/2007/opf"
xmlns:dc="http://purl.org/dc/elements/1.1/"
prefix="rendition: http://www.idpf.org/vocab/rendition/#">
  <metadata 
xmlns:opf="http://www.idpf.org/2007/opf"
xmlns:dc="http://purl.org/dc/elements/1.1/" 
xmlns:dcterms="http://purl.org/dc/terms/">
    <dc:title id="t1">Tanz der seligen Geister</dc:title>
    <meta refines="#t1" property="title-type">main</meta>
    <dc:creator id="create1">Alice Munro</dc:creator>
    <meta refines="#create1" scheme="marc:relators" property="role">aut</meta>
    <meta refines="#create1" property="file-as">Munro, Alice</meta>
    <dc:language>de-DE</dc:language>
    <dc:publisher>Dörlemann</dc:publisher>
    <dc:date>2012</dc:date>
    <dc:identifier id="book-id">urn:isbn:978-3-908778-02-8</dc:identifier>
    <meta name="Sigil version" content="0.9.7" />
    <meta property="dcterms:modified">2017-03-06T19:19:53Z</meta>
  </metadata>
  <manifest>
    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>
    <item id="title.xhtml" href="Text/title.xhtml" media-type="application/xhtml+xml"/>
    <item id="content.xhtml" href="Text/content.xhtml" media-type="application/xhtml+xml"/>
    <item id="about.xhtml" href="Text/about.xhtml" media-type="application/xhtml+xml"/>
    <item id="about.jpg" href="Images/about.jpg" media-type="image/jpeg"/>
    <item id="cover.jpg" href="Images/cover.jpg" media-type="image/jpeg"/>
    <item id="imprint.xhtml" href="Text/imprint.xhtml" media-type="application/xhtml+xml"/>
    <item id="default.css" href="Styles/default.css" media-type="text/css"/>
    <item id="navid" href="Text/nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
  </manifest>
  <spine toc="ncx">
    <itemref idref="title.xhtml"/>
    <itemref idref="content.xhtml"/>
    <itemref idref="about.xhtml"/>
    <itemref idref="imprint.xhtml"/>
    <itemref idref="navid"/>
  </spine>
</package>

I will edit the post later to comment the passages which are marked as bold.

Edit:

1 Are both, "xmlns" and "xmlns:opf" useful, even if in the metadata no "opf:*" exist?
The page "http://www.idpf.org/2007/opf" cannot be found, by the way.

2 Do we really need so many "systems" to declare metadata "opf:" "dc:" "dcterms:" and "rendition"?

3 Is <meta refines="#t1" property="title-type">main</meta> useful?

4 Is id="create1" in dc:creator useful?

...

I really hope, there is someone out there, with a deeper knowledge in those things than me, who created a minimal OPF for EPUB3.

BetterRed · 03-06-2017, 05:29 PM

Quote:

Originally Posted by ibu

I will edit the post later to comment the passages which are marked as bold.

fyi - you can eliminate the

smileys by wrapping the text in [noparse][/noparse] tags.

BR

03-06-2017, 06:21 AM	#7
ibu Addict Posts: 264 Karma: 9246 Join Date: Feb 2010 Location: Berlin, Germany Device: Kobo H20, iPhone 6+, Macbook Pro	My main focus is an epub3 book for a usage on a Kobo. Therefore any features, which are not supported on a Kobo, must not exist in the minimal epub. Maybe you like to see my (older) valid minimal testcase for epub2: https://www.dropbox.com/s/t47l4dlpc3....testcase.epub Note: For the NCX I'm not really sure, if/how it can be minimalized. Same for the OPF I'm looking for a comparable testcase for epub3. In the best, with a minimalized NCX and OPF. Last edited by ibu; 03-06-2017 at 07:07 AM.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
[Plugin] ePub3-itizer - epub3 output plugin for Sigil	KevinH	Plugins	435	01-19-2023 09:46 PM
epub3 app with epub3 dictionary support	Doitsu	ePub	0	01-21-2017 09:38 AM
Epub3 XHTML Validation epub3	Ramesh Arpitha	ePub	5	06-30-2014 08:32 PM
New Errors Converting epub3 -> zip -> epub3	Lola25	ePub	2	11-12-2013 09:37 PM
PRS-T2 Difference jailbreak.zip/rupor-jailbreak.7z & minimal-root-zeam.zip/rupor-minimal.7z?	hyperstruct	Sony Reader Dev Corner	9	01-06-2013 02:05 PM

02-27-2017, 06:09 AM	#2
patrik Guru Posts: 657 Karma: 4568205 Join Date: Jan 2010 Location: Sweden Device: Kobo Forma	Until you get a better response my suggestion would be to take a look at some of the files by Doitsu. (https://www.mobileread.com/forums/asearch.php and add Doitsu in the field "Attached by".)

02-27-2017, 10:00 AM	#3
Toxaris Wizard Posts: 4,520 Karma: 121692313 Join Date: Oct 2009 Location: Heemskerk, NL Device: PRS-T1, Kobo Touch, Kobo Aura	It is very subjective... It depends a lot on what you want to have in the ePUB. Just text, multimedia, footnotes, media queries, javascript, etc.

03-06-2017, 03:00 AM	#5
ibu Addict Posts: 264 Karma: 9246 Join Date: Feb 2010 Location: Berlin, Germany Device: Kobo H20, iPhone 6+, Macbook Pro	Thanks for your hints Sorry for my late reply, I didn't get a message about new posts in this thread after the first reply arrived. No, I'm not deterred. The official sample files are no focussed on beeing "minimal". Bad luck for me, that "minimal valid code" is not a popular start point. I like it "bottom up" in other situations too. Independent of this search for a minimal testcase: As well I'm looking for a good public valid testcase for my Kobo H2O which demonstrates, where the software of the reader still has bugs/faults. Nice, if it is an ebpub3 one. In general about ebub3: Would you disadvise to use it with Kobo? I do only talk of manipulated code by myself.

03-06-2017, 07:13 AM	#9
ibu Addict Posts: 264 Karma: 9246 Join Date: Feb 2010 Location: Berlin, Germany Device: Kobo H20, iPhone 6+, Macbook Pro	Do you know a minimal NCX and OPF, which is good as a pattern?

03-06-2017, 10:15 AM	#11
ibu Addict Posts: 264 Karma: 9246 Join Date: Feb 2010 Location: Berlin, Germany Device: Kobo H20, iPhone 6+, Macbook Pro	@Doitsu Do I understand it correctly, that Kobo does not support an EPUB3 which has only a nav.xhtml and no NCX? My own NCX and OPF are not completely minimal. Therefor I'm looking for inspiration, how others has created these files in a minimal form.