epub

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2021 License: MIT Imports: 10 Imported by: 2

README

epub3

Go Reference

The EPUB specification is a distribution and interchange format standard for digital publications and documents. EPUB defines a means of representing, packaging and encoding structured and semantically enhanced Web content — including HTML5, CSS, SVG, images, and other resources — for distribution in a single-file format.

This library describes the format of the data used in the EPUB, and offers easy writer to create publications in this format.

Documentation

Overview

Package epub describes the format of the data used in the epub, and offers easy writer to create publications in this format.

Example 
package main

import (
	"log"
	"os"

	epub "github.com/mdigger/epub3"
)

func main() {
	file, err := os.Create("test.epub")
	if err != nil {
		log.Fatal(err)
	}
	defer file.Close()

	pub, err := epub.New(file)
	if err != nil {
		log.Fatal(err)
	}
	defer pub.Close()

	pub.AddTitle("Test")
	pub.AddAuthors("Author")

	content, err := os.Open("example.html")
	if err != nil {
		log.Fatal(err)
	}
	err = pub.AddContent(content, "example.html", epub.Primary)
	content.Close()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	RootPath        = "OEBPS"       // Folder with content of publication
	PackageFilename = "package.opf" // Package description file name
)

Default file names and mime-type.

View Source 
var (
	DefaultLang  = Element{Value: "en"}
	DefaultTitle = ElementLang{Value: "Untitled"}
)

Default metadata settings.

View Source 
var MimeTypes = map[string]string{
	".gif":   "image/gif",
	".jpg":   "image/jpeg",
	".jpeg":  "image/jpeg",
	".jpe":   "image/jpeg",
	".png":   "image/png",
	".svg":   "image/svg+xml",
	".xhtm":  "application/xhtml+xml",
	".xhtml": "application/xhtml+xml",
	".ncx":   "application/x-dtbncx+xml",
	".otf":   "application/vnd.ms-opentype",
	".woff":  "application/application/font-woff",
	".smil":  "application/smil+xml",
	".smi":   "application/smil+xml",
	".sml":   "application/smil+xml",
	".pls":   "application/pls+xml",
	".mp3":   "audio/mpeg",
	".mp4":   "audio/mp4",
	".aac":   "audio/mp4",
	".m4a":   "audio/mp4",
	".m4v":   "audio/mp4",
	".m4b":   "audio/mp4",
	".m4p":   "audio/mp4",
	".m4r":   "audio/mp4",
	".css":   "text/css",
	".js":    "text/javascript",
}

MimeTypes list supported MIME types by file extension.

Functions

func NewUUID 

func NewUUID() string

NewUUID returns the canonical namespaced string representation of a UUID: 

urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Types

type Collection 

type Collection struct {
	Lang        string       `xml:"xml:lang,attr,omitempty"` // Specifies the language used in the contents and attribute values of the carrying element and its descendants
	Dir         string       `xml:"dir,attr,omitempty"`      // Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
	ID          string       `xml:"id,attr,omitempty"`       // The ID [XML] of this element, which must be unique within the document scope.
	Role        string       `xml:"role,attr"`               // Specifies the nature of the collection
	Metadata    *Metadata    `xml:"metadata,omitempty"`      // The optional metadata element child of collection is an adaptation of the package metadata element.
	Collections []Collection `xml:"collection,omitempty"`    // A collection may define sub-collections through the inclusion of one or more child collection elements.
	Links       []Link       `xml:"link,omitempty"`          // The link element child of collection is an adaptation of the metadata link element.
}

Collection element defines a related group of resources.

type Container 

type Container struct {
	XMLName   xml.Name   `xml:"urn:oasis:names:tc:opendocument:xmlns:container container"`
	Version   string     `xml:"version,attr"`
	Rootfiles []RootFile `xml:"rootfiles>rootfile"`
}

Container describes the contents of the container.

type ContentType 

type ContentType byte

ContentType describe type of content file. 

const (
	Primary   ContentType = iota // Primary content file
	Auxiliary                    // Auxiliary content file
	Media                        // Media file
)

Supported types of content file.

type Element 

type Element struct {
	Value string `xml:",chardata"`
	ID    string `xml:"id,attr,omitempty"` // The ID of this element, which must be unique within the document scope.
}

Element with optional ID.

type ElementLang 

type ElementLang struct {
	Value string `xml:",chardata"`
	ID    string `xml:"id,attr,omitempty"`       // The ID of this element, which must be unique within the document scope.
	Dir   string `xml:"dir,attr,omitempty"`      // Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
	Lang  string `xml:"xml:lang,attr,omitempty"` // Specifies the language used in the contents and attribute values of the carrying element and its descendants
}

ElementLang with optional ID, xml:lang & dir.

type Item 

type Item struct {
	ID           string `xml:"id,attr"`                      // The ID [XML] of this element, which must be unique within the document scope.
	Href         string `xml:"href,attr"`                    // An IRI [RFC3987] specifying the location of the Publication Resource described by this item.
	MediaType    string `xml:"media-type,attr"`              // A media type [RFC2046] that specifies the type and format of the Publication Resource described by this item.
	Fallback     string `xml:"fallback,attr,omitempty"`      // An IDREF [XML] that identifies the fallback for a non-Core Media Type.
	Properties   string `xml:"properties,attr,omitempty"`    // A space-separated list of property values.
	MediaOverlay string `xml:"media-overlay,attr,omitempty"` // An IDREF [XML] that identifies the Media Overlay Document for the resource described by this item.
}

Item element represents a Publication Resource.

type ItemRef 

type ItemRef struct {
	IDRef      string `xml:"idref,attr"`                // An IDREF [XML] that identifies a manifest item.
	Linear     string `xml:"linear,attr,omitempty"`     // Specifies whether the referenced content is primary. The value of the attribute must be yes or no. The default value is yes.
	ID         string `xml:"id,attr,omitempty"`         // The ID [XML] of this element, which must be unique within the document scope.
	Properties string `xml:"properties,attr,omitempty"` // A space-separated list of property values.
}

ItemRef elements of the spine represent a sequential list of Publication Resources (typically EPUB Content Documents). The order of the itemref elements defines the default reading order of the Publication. 

type Link struct {
	Refines   string `xml:"refines,attr,omitempty"`    // Identifies the expression or resource augmented by this element. The value of the attribute must be a relative IRI [RFC3987] pointing to the resource or element it describes.
	Rel       string `xml:"rel,attr"`                  // A space-separated list of property values.
	Href      string `xml:"href,attr"`                 // An absolute or relative IRI reference [RFC3987] to a resource.
	ID        string `xml:"id,attr,omitempty"`         // The ID [XML] of this element, which must be unique within the document scope.
	MediaType string `xml:"media-type,attr,omitempty"` // A media type [RFC2046] that specifies the type and format of the resource referenced by this link.
}

Link element is used to associate resources with a Publication, such as metadata records.

type Manifest 

type Manifest struct {
	ID    string `xml:"id,attr,omitempty"` // The ID [XML] of this element, which must be unique within the document scope.
	Items []Item `xml:"item"`              // List of the Publication Resources
}

Manifest element provides an exhaustive list of the Publication Resources that constitute the EPUB Publication, each represented by an item element.

type Meta 

type Meta struct {
	Refines  string `xml:"refines,attr,omitempty"`  // Identifies the expression or resource augmented by this element. The value of the attribute must be a relative IRI [RFC3987] pointing to the resource or element it describes.
	Property string `xml:"property,attr"`           // A property. Refer to Vocabulary Association Mechanisms for more information.
	Scheme   string `xml:"scheme,attr,omitempty"`   // A property data type value indicating the source the value of the element is drawn from.
	ID       string `xml:"id,attr,omitempty"`       // The ID of this element, which must be unique within the document scope.
	Dir      string `xml:"dir,attr,omitempty"`      // Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
	Lang     string `xml:"xml:lang,attr,omitempty"` // Specifies the language used in the contents and attribute values of the carrying element and its descendants
	Value    string `xml:",chardata"`
}

Meta element provides a generic means of including package metadata, allowing the expression of primary metadata about the package or content and refinement of that metadata.

type Metadata 

type Metadata struct {
	DC string `xml:"xmlns:dc,attr"` // “http://purl.org/dc/elements/1.1/”
	// Required Elements
	Identifier []Element     `xml:"dc:identifier"` // The [DCMES] identifier element contains a single identifier associated with the EPUB Publication, such as a UUID, DOI, ISBN or ISSN.
	Title      []ElementLang `xml:"dc:title"`      // The [DCMES] title element represents an instance of a name given to the EPUB Publication.
	Language   []Element     `xml:"dc:language"`   // The [DCMES] language element specifies the language of the Publication content.
	// DCMES Optional Elements
	Date        *Element      `xml:"dc:date,omitempty"`        // The date element must only be used to define the publication date of the EPUB Publication. The publication date is not the same as the last modified date (the last time the content was changed), which must be included using the [DCTERMS] modified property.
	Creator     []ElementLang `xml:"dc:creator,omitempty"`     // The creator element represents the name of a person, organization, etc. responsible for the creation of the content of a Publication. The role property can be attached to the element to indicate the function the creator played in the creation of the content.
	Contributor []ElementLang `xml:"dc:contributor,omitempty"` // The contributor element is used to represent the name of a person, organization, etc. that played a secondary role in the creation of the content of a Publication.
	Subject     []ElementLang `xml:"dc:subject,omitempty"`
	Description []ElementLang `xml:"dc:description,omitempty"`
	Type        []Element     `xml:"dc:type,omitempty"`
	Format      []Element     `xml:"dc:format,omitempty"`
	Publisher   []ElementLang `xml:"dc:publisher,omitempty"`
	Source      []Element     `xml:"dc:source,omitempty"`
	Relation    []ElementLang `xml:"dc:relation,omitempty"`
	Coverage    []ElementLang `xml:"dc:coverage,omitempty"`
	Rights      []ElementLang `xml:"dc:rights,omitempty"`
	// Meta
	Meta []Meta `xml:"meta,omitempty"` // The meta element provides a generic means of including package metadata, allowing the expression of primary metadata about the package or content and refinement of that metadata.
	Link []Link `xml:"link,omitempty"` // The link element is used to associate resources with a Publication, such as metadata records.
}

Metadata element encapsulates Publication meta information.

func (*Metadata) AddAuthors 

func (m *Metadata) AddAuthors(names ...string)

AddAuthor new publication author.

func (*Metadata) AddSubjects 

func (m *Metadata) AddSubjects(names ...string)

AddSubjects add publication subject.

func (*Metadata) AddTitle 

func (m *Metadata) AddTitle(name string)

AddTitle new publication title.

func (*Metadata) SetDate 

func (m *Metadata) SetDate(date string) (err error)

SetDate set publication date (not last modified).

func (*Metadata) SetDescription 

func (m *Metadata) SetDescription(description string)

SetDescription set publication description.

func (*Metadata) SetLang 

func (m *Metadata) SetLang(lang string)

SetLang set publication language.

func (*Metadata) SetPublisher 

func (m *Metadata) SetPublisher(name string)

SetPublisher set publication publisher.

func (*Metadata) SetRights 

func (m *Metadata) SetRights(rights string)

SetRights set publication rights description.

func (*Metadata) SetUUID 

func (m *Metadata) SetUUID(id string)

SetUUID set publication identifier as UUID.

type Package 

type Package struct {
	XMLName          xml.Name    `xml:"http://www.idpf.org/2007/opf package"`
	Version          string      `xml:"version,attr"`            // Specifies the EPUB specification version to which the Publication conforms
	UniqueIdentifier string      `xml:"unique-identifier,attr"`  // An IDREF that identifies the dc:identifier element that provides the package's preferred, or primary, identifier
	Prefix           string      `xml:"prefix,attr,omitempty"`   // Declaration mechanism for prefixes not reserved by this specification.
	Lang             string      `xml:"xml:lang,attr,omitempty"` // Specifies the language used in the contents and attribute values of the carrying element and its descendants
	Dir              string      `xml:"dir,attr,omitempty"`      // Specifies the base text direction of the content and attribute values of the carrying element and its descendants.
	ID               string      `xml:"id,attr,omitempty"`       // The ID of this element, which must be unique within the document scope
	Metadata         Metadata    `xml:"metadata"`                // The metadata element encapsulates Publication meta information
	Manifest         Manifest    `xml:"manifest"`                // The manifest element provides an exhaustive list of the Publication Resources that constitute the EPUB Publication, each represented by an item element.
	Spine            Spine       `xml:"spine"`                   // The spine element defines the default reading order of the EPUB Publication content
	Collection       *Collection `xml:"collection,omitempty"`    // The collection element defines a related group of resources. (Added in EPUB 301.)
}

Package element is the root container of the Package Document and encapsulates Publication metadata and resource information.

type RootFile 

type RootFile struct {
	FullPath  string `xml:"full-path,attr"`
	MediaType string `xml:"media-type,attr"`
}

RootFile describes the path to description of publication.

type Spine 

type Spine struct {
	ID            string    `xml:"id,attr,omitempty"`                         // The ID [XML] of this element, which must be unique within the document scope.
	Toc           string    `xml:"toc,attr,omitempty"`                        // An IDREF [XML] that identifies the manifest item that represents the superseded NCX.
	PageDirection string    `xml:"page-progression-direction,attr,omitempty"` // The global direction in which the Publication content flows. Allowed values are ltr (left-to-right), rtl (right-to-left) and default.
	ItemRefs      []ItemRef `xml:"itemref"`                                   // Ordered subset of the Publication Resources listed in the manifest
}

Spine element defines the default reading order of the EPUB Publication content by defining an ordered list of manifest item references.

type Writer 

type Writer struct {
	Metadata
	// contains filtered or unexported fields
}

Writer allows you to create publications in epub 3 format.

func New 

func New(w io.Writer) (wr *Writer, err error)

New return new epub publication Writer.

func (*Writer) AddContent 

func (w *Writer) AddContent(r io.Reader, name string, ct ContentType, properties ...string) error

AddContent adds data to the publication.

func (*Writer) Close 

func (w *Writer) Close() error

Close closes the publication and writes metadata.

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.