Add global --include-before option for epub format

[Samreay]

For many epub works, it is common to have sections before the Table of Contents. A foreword, acknowledgements, copyright and dedication are all fairly normal to include.

For other formats, including the -B (--include-before-body) option is normally sufficient to include content before the generated Table of Contents.

However, for the epub format, each chapter is treated as its own file (even with the -s standalone option.

This means that if you include a file with a foreword (for example) in via the -B argument, your epub output will have the foreword at the beginning of every chapter.

As far as I can tell (at least, having spent a day or two trying to find a solution), there is no way to add content before the table of contents by itself in the epub export. This would be a great feature to add to pandoc for book publishing.

[jgm]

I assume that you're talking about the table of contents encoded in nav.xhtml in the epub container?
I'm not sure, actually, how to adjust its position relative to other elements. As an experiment, I tried reordering it in the manifest in content.opf, but on ibooks this made no difference, so it may be that some readers will always put the nav first?

[Samreay]

I'm unsure if ibooks is pulling things to the front, but I dont see this behaviour on Calibre or the Kindle reader. I can provide some screenshots showing typical epub layout if that helps, or upload some example .opf manifests and spine snippets, and contrast that to the repeated behaviour of the -B flag which inserts front matter at the beginning of every chapter. Let me know what I can provide :)

[jgm]

I understand why -B won't do what you're looking for here.
But I would be interested in knowing what affects the relative position of the TOC in epubs, and whether this is reader-specific. Perhaps you could upload a sample epub that has the front matter before the TOC, or at least the snippets you describe.

[Samreay]

Sure thing. For more motivation, I am trying to set up a compilation pipeline for publishing a novel and have to conform to KDP standards which state here in Step 4 that front matter order is:

• Title page, right-facing page
• Copyright page
• Dedication – right-facing page (requires blank page after)
• Table of contents with page numbers, right-facing page (might
  require blank page after, depending on number of TOC pages)
• Foreword – right-facing page (requires blank page after)

Kings of the Wyld layout in the Kindle Viewer:

[KingsOfWyld_package.opf.txt](https://github.com/jgm/pandoc/files/6951272/KingsOfWyld_package.opf.txt)

Misborn (3 books in one epub):

[Misborn_content.opf.txt](https://github.com/jgm/pandoc/files/6951283/Misborn_content.opf.txt)

Memory of Light (calibre book viewer showing dedications similar frontmatter):

MemoryOfLight_content.opf.txt

Sword of Kaigen online epub viewer:

SwordOfKaigen_content.opf.txt

Let me know if any other parts of any of those epubs might be useful, unsure about the legality of sharing them on an open source platform

[Samreay]

Some of the opfs didnt seem to upload properly. Here are all of them zipped together.

contents.zip

[jgm]

For easy reference,

<spine page-progression-direction="ltr" toc="ncx">
<itemref idref="cover" linear="no"/>
<itemref idref="titlepage" linear="yes"/>
<itemref idref="copyright" linear="yes"/>
<itemref idref="toc" linear="yes"/>
<itemref idref="dedication" linear="yes"/>
<itemref idref="preface001" linear="yes"/>
<itemref idref="chapter001" linear="yes"/>
<itemref idref="chapter002" linear="yes"/>
<itemref idref="chapter003" linear="yes"/>

The page-progression-direction and linear attributes aren't used by pandoc; that might be the difference.

If we used them, we could introduce a way to mark chapters as pre-toc (and presumably also as not appearing in the toc)? In some writers we are sensitive to frontmatter and unlisted classes.

[jgm]

Related: #1609 #1593

[Samreay]

Being able to label chapters as pre-toc would be useful. The KDP guide doesnt seem to indicate that the pre-toc entires are required in the toc, so leaving them out seems appropriate. They explicitly state the TOCs are required for ebooks to allow users to navigate between book chapters, so all the non-chapter pre-toc content shouldnt need to appear.

As to the best way of labelling chapters, I simply have a file frontmatter.md that has all the pre-toc content, however if theres a a way of labelling files or chapters I've missed in pandoc, anything other format would work, I am very much a beginner with the software.

[jgm]

Sorry, I was being dumb. In my test, I changed the order in the manifest element, not the spine.
The spine is what's needed. linear and page-progression-direction are not relevant here.
Changing the order in the spine works.

In the academic publishing I'm most experienced with, the preface and acknowledgements come after the TOC and are listed in it (though numbered differently, with roman-numbered pages). All that comes before the TOC are the title page, half title page (copyright), dedication (if any), and series page. Maybe it's different with (some?) fiction.

[jgm]

In the PDF you linked to, it says:

• Half title page – right-facing page (requires blank page after)
• Title page, right-facing page
• Copyright page
• Dedication – right-facing page (requires blank page after)
• Table of contents with page numbers, right-facing page (might require blank page after, depending on number of TOC pages)
• Foreword – right-facing page (requires blank page after)

So, this suggests that the forward comes after the TOC.
All that comes before is the title page, copyright info, and dedication.

You can do this in pandoc using a custom epub template.
If you look at the default epub3 template, you'll see a big conditional starting $if(titlepage)$. Anything you put in this section will go before the toc. So, you could easily add your copyright info here.

In fact, the template already includes a rights variable. So, if you put this in your YAML metadata,

rights: |
  Copyright 2010 So and So.

  All rights reserved

or whatever, then it should appear on the title page automatically even with the default template.

[Samreay]

Oh, does that support more than just text? Links, images and text formatting? Or is that rich content something that could be done with a custom template instead of using the rights metadata?

[jgm]

Anything you can do in pandoc's markdown will work there.

[Samreay]

Oh, I had no idea it was rich, my apologies then, I believe that would resolve all the issues.

Just tested it and the only thing Im not sure how to do is respect their left-hand vs right-hand page rule by explicitly setting a page break or adding a new page to align the TOC. Im guessing \newpage or \pagebreak arent the right way of going about it?

[BzzBzzBzzBzz]

In the PDF you linked to, it says:

• Half title page – right-facing page (requires blank page after)
• Title page, right-facing page
• Copyright page
• Dedication – right-facing page (requires blank page after)
• Table of contents with page numbers, right-facing page (might require blank page after, depending on number of TOC pages)
• Foreword – right-facing page (requires blank page after)

So, this suggests that the forward comes after the TOC. All that comes before is the title page, copyright info, and dedication.

You can do this in pandoc using a custom epub template. If you look at the default epub3 template, you'll see a big conditional starting $if(titlepage)$. Anything you put in this section will go before the toc. So, you could easily add your copyright info here.

In fact, the template already includes a rights variable. So, if you put this in your YAML metadata,

rights: |
  Copyright 2010 So and So.

  All rights reserved

or whatever, then it should appear on the title page automatically even with the default template.

I think that i got a similar issue and since this one is still open I would try to explain it here. If needed I could open a new one.

I tried the proposed solution, but unfortunately some reading devices (i.e. Kobo) does not support page break from CSS. Currently the only way to force a page break is to split pages in different files (see specs for details).
Therefore I think that a parameter to decide where to put TOC page could be usefull.

Thanks.