The Sigil plugin interface is being expanded and updated for Sigil 1.0 and later.
Starting with version 1.0, Sigil will no longer force ebook developers to follow Sigil's standard epub structure. This means that Sigil will no longer force epubs into standard form when first opened. This should allow more advanced developers to create layouts specific to their customer's or reader's needs and prevent breakage of javascript code that depended on the current epub layout.
Therefore a new way of uniquely identifying a file must be used as the filename alone may not be unique.
A book path (aka "bookpath" aka "book_href" aka "bookhref") is a unique relative path from the ebook root to a specific file.
As a relative path meant to be used in an href or src "link", it only uses forward slashes "/" as path separators.
Since all files must exist inside the epub root (the folder the epub was unzipped into), bookpaths will NEVER have or use "./" or "../" ie. they are always in canonical form.
For example under Sigil-0.9.XX all epubs were put into a standard structure. Under this standard structure book paths would look like the following:
Code:
# OEBPS/content.opf
# OEBPS/toc.ncx
# OEBPS/Text/Section0001.xhtml
# OEBPS/Images/cover.jpg
# ...
and src and hrefs always looked like the following:
Code:
# from Section0001.xhtml to Section0002.xhtml: ../Text/Section0002.xhtml
# from Section0001.xhtml to cover.jpg: ../Images/cover.jpg
# from content.opf to Section0001.xhtml: Text/Section0001.xhtml
# from toc.ncx to Section0001.xhtml: Text/Section0001.xhtml
Under Sigil 1.0 and later, the original epub structure will be preserved meaning that file names like "content.opf" could be named "package.opf", and be placed almost anyplace inside the epub. This is true for almost all files.
So to uniquely identify a file, you need to know either the bookpath of the OPF file itself and the manifest href to the specific file from the OPF, or the direct path from the epub root to the file (ie. its bookpath)
Therefore the Sigil plugin interface for Sigil 1.0 and later has been extended to allow the plugin developer to more easily work with bookpaths, create links between bookpaths, etc.
We will use the terms book_href (or bookhref) interchangeably with bookpath with the following conventions:
Code:
# - use book_href or bookhref when working with "other" files outside the manifest
# - use bookpath when working with files in the opf manifest
# - use either when working with the OPF file as it is at the intersection
Please note, that the old plugin interface will continue to work for all epubs that are in the pre Sigil 1.0 standard form. Sigil will contain a tool to standardize the epub layout if the ebook developer so chooses.
Changes to your plugin code should only be needed if you build links, or access the complete OPF using fixed paths.
Help will be provided to any plugin developer if requested.
Here are the new interface functions:
Code:
# returns the bookpath/book_href to the opf file
#
def get_opfbookpath(self)
# returns the book path of the folder containing this bookpath
#
def get_startingdir(self, bookpath)
# return a bookpath for the file pointed to by the href
# from the specified bookpath starting directory
#
def build_bookpath(self, href, starting_dir)
# returns the href relative path from source bookpath to the target bookpath
#
def get_relativepath(self, from_bookpath, to_bookpath)
# adds a new file to the *manifest* with the stated bookpath with the provided
# uniqueid, data, (and mediatype if specified)
#
def addbookpath(self, uniqueid, bookpath, data, mime=None)
# functions for converting from manifest id to bookpath and back
#
def bookpath_to_id(self, bookpath, ow=None)
def id_to_bookpath(self, id, ow=None)
# returns a sorted folder list for that group
# valid groups: Text, Styles, Images, Fonts, Audio, Video, ncx, opf, Misc
#
def map_group_to_folders(self, group, ow)
# get file group from its mediatype
#
def map_mediatype_to_group(self, mtype, ow)
# returns true if epub is in Sigil standard format
#
def epub_is_standard(self)