epub

package module
v0.0.0-...-6d47f48 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 31, 2020 License: BSD-3-Clause Imports: 18 Imported by: 0

README

epub

A Go library for the creation of ePub ebook files.

This package creates basic ePub v2.0 or V3.0 format files, suitable for creating books. By default books are tagged and written out as V2, but you can write V3 format books either by calling the WriteV3 method directly or by setting the ePub version to 3 via SetVersion(3) and then calling Write().

An ePub file consists of one or more XHTML files that represent the text of your book, the resources those files reference, and the optional structured metadata (such as author and publisher) for the book.

This library doesn't do validity testing of the book file, so it's possible to create invalid books. Testing the output with external ePub validators such as ePubCheck (https://github.com/IDPF/epubcheck) is advisable.

Structure notes

All files in an ePub should be reachable, directly or indirectly, from the spine of the book. Books with unreferenced files are technically illegally formatted.

It doesn't matter what order your code calls AddImage, AddXHTML, AddFont, AddJavaScript, or AddStylesheet to put files in the ePub book. Nor does it matter what order your code calls AddNavpoints to add files to the book spine.

ePub files are specially formatted zip archives. You can unzip the resulting .epub file and inspect the contents if needed.

Limitations

Currently this package doesn't support encrypted or DRM'd books or content.

Fonts are not obscured when writing V3 format files.

None of the interesting bits of the V3 format are currently supported; v3 books are basically identical to v2 books only using the updated metadata file formats.

License

epub is made available under the terms of the New BSD License

Documentation

Overview

Package epub creates ePub v2.0 format ebooks.

An ePub file consists of one or more XHTML files that represent the text of your book, the resources those files reference, and the optional structured metadata (such as author and publisher) for the book.

This library doesn't do validity testing of the book file, so it's possible to create invalid books. Testing the output with external ePub validators such as ePubCheck (https://github.com/IDPF/epubcheck) is advisable.

Structure notes

All files in an ePub should be reachable, directly or indirectly, from the spine of the book. Books with unreferenced files are technically illegally formatted.

It doesn't matter what order your code calls AddImage, AddXHTML, AddJavascript, or AddStylesheet to put files in the ePub book. Nor does it matter what order your code calls AddNavpoints to add files to the book spine.

ePub files are specially formatted zip archives. You can unzip the resulting .epub file and inspect the contents if needed.

Limitations

Currently this package doesn't support adding fonts or JavaScript files, nor does it support encrypted or DRM'd books.

By default this package writes out ePub v2.0 format files. You can write V3 files either by calling the WriteV3 method directly, or setting the epub object's version to v3 by e.SetVersion(3).

Index

Examples

Constants

This section is empty.

Variables

View Source 
var NamespaceUUID = uuid.Must(uuid.FromString("443ed275-966f-4099-8bee-5a6e1e474bb4"))

NamespaceUUID is the namespace we're using for all V5 UUIDs

Functions

This section is empty.

Types

type EPub 

type EPub struct {
	// contains filtered or unexported fields
}

EPub holds the contents of the ePub book.

func New 

func New() *EPub

New creates a new empty ePub file.

Example 
package main

import (
	"fmt"

	"github.com/writingtoole/epub"
)

func main() {
	b := epub.New()
	b.AddAuthor("me")
	b.AddLanguage("en")
	b.SetTitle("My Book")

	// Put our cover into the file, with a path in the book of
	// "images/cover.jpg".
	coverId, _ := b.AddImageFile("source/mycover.jpg", "images/cover.jpg")
	b.SetCoverImage(coverId)

	// Add our pre-formatted cover file. The path in the book will be
	// "xhtml/cover.xhtml". It's noted as file 0 in the book since we'll
	// be adding files in a different order than we want them to appear.
	//
	// We don't add the cover to the book's TOC.
	b.AddXHTMLFile("source/cover_file", "xhtml/cover.xhtml", 1)

	// Add chapter 1. We start numbering chapter files with 10.
	b.AddXHTMLFile("source/file1.xhtml", "xhtml/file1.xhtml", 10)
	np1 := b.AddNavpoint("Chapter 1", "xhtml/file1.xhtml", 10)
	// Chapter 1 has 10 fragments that each get a spine entry.
	for i := 1; i <= 10; i++ {
		// Add these section fragments to the spine.
		np1.AddNavpoint(fmt.Sprintf("Section %v", i), fmt.Sprintf("xhtml/file1.xhtml#%v", i), i)
	}

	// Add chapter 2.
	b.AddXHTMLFile("source/file2.xhtml", "xhtml/file2.xhtml", 11)
	b.AddNavpoint("Chapter 2", "xhtml/file2.xhtml", 11)

	// Add an actual table of contents. This appears inline in the book,
	// an dis is different than (and unrelated to) the one built from
	// navpoints.
	b.AddXHTMLFile("source/toc.xhtml", "xhtml/toc.xhtml", 2)

	b.Write("mybook.epub")
}

Output:

func (*EPub) AddArtist 

func (e *EPub) AddArtist(artist string)

func (*EPub) AddAuthor 

func (e *EPub) AddAuthor(author string)

AddAuthor adds an author's name to the list of authors for the book.

func (*EPub) AddContributor 

func (e *EPub) AddContributor(creator string, role string) error

AddContributor adds a creator entry to the epub file. The contributor type must come from the list of valid roles at http://www.loc.gov/marc/relators/relaterm.html and will return an error if an invalid entry is passed.

func (*EPub) AddCreator 

func (e *EPub) AddCreator(creator string, role string) error

AddCreator adds a creator entry to the epub file. The creator type must come from the list of valid creators at http://www.loc.gov/marc/relators/relaterm.html and will return an error if an invalid entry is passed.

func (*EPub) AddDescription 

func (e *EPub) AddDescription(desc string)

AddDescripton adds a description entry for the book.

func (*EPub) AddFont 

func (e *EPub) AddFont(path string, contents []byte) (Id, error)

AddFont adds a font to the ePub book. Path is the relative path in the book to the font, and contents is the contents of the font.

Returns the ID of the added file, or an error if something went wrong.

func (*EPub) AddFontFile 

func (e *EPub) AddFontFile(source, dest string) (Id, error)

AddFontFile adds the named font to the epub book. Source is the name of the file to be added while dest is the name the file should have in the ePub book.

Returns the ID of the added file, or an error if something went wrong.

func (*EPub) AddImage 

func (e *EPub) AddImage(path string, contents []byte) (Id, error)

AddImage adds an image to the ePub book. Path is the relative path in the book to the image, and contents is the image itself.

The library will autodetect the filetype for the image from the contents. Some ebook reading software infers filetype from the filename, so while it isn't required it is prudent to have the file extension match the filetype.

func (*EPub) AddImageFile 

func (e *EPub) AddImageFile(source, dest string) (Id, error)

AddImageFile adds an image file to the ePub book. source is the name of the file to be added while dest is the name the file should have in the ePub book.

Returns the ID of the added file, or an error if something went wrong reading the file.

func (*EPub) AddJavaScript 

func (e *EPub) AddJavaScript(path, contents string) (Id, error)

AddJavaScript adds a JavaScript file to the ePub book. Path is the relative path in the book to the javascript file, and contents is the JavaScript itself.

Returns the ID of the added file, or an error if something went wrong.

func (*EPub) AddJavaScriptFile 

func (e *EPub) AddJavaScriptFile(source, dest string) (Id, error)

AddJavaScriptFile adds the named JavaScript file to the ePub book. source is the name of the file to be added while dest is the name the file should have in the ePub book.

Returns the ID of the added file, or an error if something went wrong reading the file.

func (*EPub) AddLanguage 

func (e *EPub) AddLanguage(l string) error

AddLanguage adds a language for the book. This should be an RFC3066 language code.

func (*EPub) AddNavpoint 

func (e *EPub) AddNavpoint(label string, name string, order int) *Navpoint

AddNavpoint adds a top-level navpoint.

Navpoints are part of the book's table of contents. The label is the string that will be shown in the TOC (note that many ereaders do *not* do HTML unescaping). Name is the URI of the point in the book this navpoint points to. Not every file in a book needs a navpoint that points to it -- all navpoints are optional.

Some ereaders do not permit fragment IDs in the URI for top-level navpoints.

The order parameter is used to sort the navpoints when building the book's TOC. Navpoints do not need to be added to the book in the order they appear in the TOC, the order numbers do not have to start from 1, and there may be gaps in the order.

Note that the order that entries appear in the table of contents, and the order that files appear in the book, don't have to be related.

Also note that some ereader software will elide entries from the book's TOC. (iBooks 1.15 on OS X, for example, won't display entries labeled "Cover" or "Table of Contents")

func (*EPub) AddPublisher 

func (e *EPub) AddPublisher(pub string)

AddPublisher adds a publisher entry for the book.

func (*EPub) AddStylesheet 

func (e *EPub) AddStylesheet(path, contents string) (Id, error)

AddStylesheet adds a CSS stylesheet to the ePub book. Path is the relative path to the CSS file in the book, while contents is the contents of the stylesheet.

func (*EPub) AddStylesheetFile 

func (e *EPub) AddStylesheetFile(source, dest string) (Id, error)

AddStylesheetFile adds the named file to the ePub as a CSS stylesheet. source is the name of the file on disk, while dest is the name the stylesheet has in the ePub file.

func (*EPub) AddSubject 

func (e *EPub) AddSubject(subj string)

AddSubject adds a subject entry for the book.

func (*EPub) AddXHTML 

func (e *EPub) AddXHTML(path string, contents string, order ...int) (Id, error)

AddXHTML adds an xhtml file to the ePub book. Path is the relative path to this file in the book, and contents is the contents of the xhtml file.

By default each file appears in the book's spine in the order they were added. You may, if you wish, optionally specify the ordering. (Note that all files without an order specified get an implicit order of '0') If multiple files are given the same order then they're sub-sorted by the order they were added.

func (*EPub) AddXHTMLFile 

func (e *EPub) AddXHTMLFile(source, dest string, order ...int) (Id, error)

AddXHTMLFile adds an xhtml file currently on-disk to the ePub book. source is the name of the file to add, while dest is the name the file should have in the ePub book.

Returns the ID of the added file, or an error if something went wrong.

func (*EPub) SerializeV2 

func (e *EPub) SerializeV2() ([]byte, error)

SerializeV2 returns a byteslice containing the built epub.

func (*EPub) SerializeV3 

func (e *EPub) SerializeV3() ([]byte, error)

func (*EPub) SetCoverImage 

func (e *EPub) SetCoverImage(id Id)

SetCoverImage notes which image is the cover.

ePub readers will generally use this as the image displayed in the bookshelf. They generally will not display this image when the book is read; if you want the first page of your book to have this cover image it's best to generate an XHTML file that references the image and set it to be the first entry in your spine.

func (*EPub) SetEntryNumber 

func (e *EPub) SetEntryNumber(n string) error

Set the entry number in the set or series of this book. This is optional, but if specified it must be a repeating dotted decimal number. (like 1.2.3.4.5.6 or 2) This is only valid to set for books that have a series or set name attached to them.

func (*EPub) SetSeries 

func (e *EPub) SetSeries(s string) error

SetSeries sets the name of the series this book belongs to. A book may be in a set or a series, but not both. Note that this is only valid for V3 epub books and won't be written out for V2 books.

func (*EPub) SetSet 

func (e *EPub) SetSet(s string) error

SetSet sets the name of the set this book belongs to. A book may be in a set or a series, but not both. Note that this is only valid for V3 epub books and won't be written out for v2 books.

func (*EPub) SetTitle 

func (e *EPub) SetTitle(title string)

SetTitle sets the title of the book.

func (*EPub) SetUUID 

func (e *EPub) SetUUID(uu string) error

SetUUID overrides the default UUID assigned to this epub. Since many ebook readers use the UUID to identify a book it's usually wise to assign the same UUID to different revisions of a book.

func (*EPub) SetVersion 

func (e *EPub) SetVersion(version float64) error

SetVersion sets the default version of the ePub file. Throws an error if an unrecognized version is specified; currently only 2 and 3 are recognized.

func (*EPub) UUID 

func (e *EPub) UUID() string

UUID returns the currently assigned UUID for this epub.

func (*EPub) Version 

func (e *EPub) Version() float64

func (*EPub) Write 

func (e *EPub) Write(name string) error

Write out the book to the named file. The book will be written in whichever version the epub object is tagged with. By default this is V2.

func (*EPub) WriteV2 

func (e *EPub) WriteV2(name string) error

Write emits an epub V2 format the epub to the named file.

func (*EPub) WriteV3 

func (e *EPub) WriteV3(name string) error

type Id 

type Id string

Id holds an identifier for an item that's been added to the book. 

type Navpoint struct {
	// contains filtered or unexported fields
}

Navpoint represents an entry in the book's spine. 

func (n *Navpoint) AddNavpoint(label string, name string, order int) *Navpoint

AddNavpoint adds a child navpoint. Label is the name that will be shown in the TOC, name is the URI of the point in the book this navpoint points to, and order is the order of the navpoint in the TOC.

Child URIs typically refer to a point in the parent Navpoint's file and, indeed, some ereaders require this. That is, if the parent navpoint has a file of "foo/bar.xhtml" the child navpoints must be fragments inside that file (such as "foo/bar.xhtml#Point3").

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.