ReSpec to EPUB
Convenience class, to export the internal RespecToEPUB class for the package as a whole.
(This is only useful if, for some reasons, the conversion is done starting with a DOM tree, using create_epub_from_dom. In general, convert should be used).
The top level entry in the package: convert a single Respec file, or a collection thereof, into an EPUB document.
Options provided by the user if and when the source has to be pre-processed via ReSpec.
-
config: ConfigOptions
Collection of respec config options, to be used with the spec generator (if applicable).
-
respec: boolean
Is the source in ReSpec?
Environmental variable name for the location of external copies of some css and image files
Valid Spec Status values
CLI for the ReSpec to EPUB 3.4 conversion.
Simple server for EPUB generation
Global constants used at various places.
Config options, to be used as part of the arguments in [[Options]] to overwrite the configuration options of ReSpec.
Options provided by the user if and when the source has to be pre-processed via ReSpec.
-
config: ConfigOptions
Collection of respec config options, to be used with the spec generator (if applicable).
-
respec: boolean
Is the source in ReSpec?
Acceptable endings for document URL-s. We try to avoid cases when the relative URL calculations go wrong
CORS headers to be added to the server response
Entity/code pairs: the XHTML conversion is supposed to remove the XML entities (if used) to their code alternatives.
Environmental variable name for the location of external copies of some css and image files
Flag to decide whether the code runs in a browser, in Deno, or in node.js.
Generic 'fixup' script (used for warnings for rescinded or obsolete versions).
Invalid host names (essentially "localhost" and friends); unless explicitly set in the environment, these are considered to be unsafe. This is important for server deployment: servers should never accept these host names
Default port number for the server locally.
Set to the default HTTP port number; the environment variable PORT may,
however, overwrite this for a server.
Local (relative) URL for styles and logos
Various media types used in the code.
Base URL for the W3C files (like base.css, logos in SVG format) modified for EPUB.
Cut-off date for the publication process change
Process version being used
URL of the spec generator service, used if the source has to be transformed via respec first.
Valid Spec Status values
These media types refer to textual content, no reason to bother about streaming when fetching them...
Base URL for the official W3C css files (only the non-SVG ones are used directly).
Base URL for the official W3C logos (only the non-SVG ones are used directly).
Generic ICON directory on the W3C site
Document types that are supposed to be WCAG A level due to the W3C publication check.
Main entry points
Main Processing class
-
create_epub(): Promise<ocf.OCF>url: string,options: Options
Create an EPUB 3, ie, an OCF file from the original content
-
create_epub_from_dom(): Promise<ocf.OCF>url: string,dom: jsdom.JSDOM
Create an OCF instance from DOM representing the original content.
-
generate_epub(): Promise<ocf.OCF>
Create the final epub file (ie, an OCF instance): download all resources, if applicable, add them all, as well as the generated content (package file, nav file, the original content file, etc.) to an OCF instance.
-
get_extra_resources(): Promise<ResourceRef[]>
Collect the references to the extra resources, to be added to the EPUB file as well as the package opf file. It relies on searching through the HTML source file, based on the query patterns given in [[resource_references]].
- global: Global
- global_url: string
-
resource_references: LocalLinks[]
Arrays of query/attribute pairs that may refer to a resource to be collected:
Interface of the "Global" data, to be used by various utilities
-
config: any
The initial config object, originally filled by the user (respec puts a copy of this object, as JSON, into the header of the generated content).
-
document_url: string
The URL of the document to be processed
-
dom: jsdom.JSDOM
The DOM element, as returned from parsing
-
html_element: Element
The DOM HTML element of the main document
-
opf_content: opf.PackageWrapper
The class used for the generation of the EPUB opf file
-
package: boolean
[Debug] Whether the opf instance should be should be printed to the console instead of generating an EPUB file
-
process_version: number
Process version used to generate this file. The possible values are 2016 and 2021
-
resources: ResourceRef[]
List of extra resources, to be added to the opf file and into the final EPUB file. The main role of the [[create_epub_from_dom]] function is to collect all relevant resources; once done, this array is used to generate the final
package.opffile as well as to collect the resources themselves and add them to the final epub file. -
trace: boolean
[Debug] Whether trace information should be printed to the console
Interface for the resources that, eventually, should be added to the EPUB file
-
absolute_url: string
URL of the resource in case it must be fetched
-
add_to_spine: boolean
Flag whether the resource reference should also be added to the spine with a 'linear=no' attribute
-
id: string
The item must have a fixed id, rather than a generated one
-
media_type: string
Media type of the resource; this must be added to the package manifest entry
-
properties: string
Extra properties, defined by the package specification, to be added to the entry
-
relative_url: string
The URL to be used within the EPUB; relative to the top of the file
-
text_content: string
Content of the resource in case it is generated by this program
Cover page
Create the cover image: it is an SVG file with title, the type of the document, date, and a W3C Logo.
CSS files (for the 2016 version of the Process)
Extract/add the right CSS references and gathers all resources (logo files, watermark image, etc.) to be added to the overall set of resources in the final book. Note that the HTML DOM of the main file is modified on the fly:
CSS files (for the 2021 version of the Process)
Extract/add the right CSS references and gathers all resources (logo files, watermark image, etc.) to be added to the overall set of resources in the final book. Note that the HTML DOM of the main file is modified on the fly:
Handle a nasty bug in some SVG files
Replace all occurrences of the <font> element in the SVG file by a <span>.
Fetch
Fetch an HTML file via [[fetch_resource]] and parse the result into a DOM instance.
Fetch an JSON file via [[fetch_resource]] and parse the result into an object.
Fetch the media type of the resource.
Service home page
Navigation File
OCF Package
The class representing the EPUB 3.4 OCF package.
- _container: JSZip
- _name: string
-
append(): voidcontent: string | ArrayBuffer | Blob | stream.Readable,path_name: string,trace?: boolean
Store a compressed content in the OCF file. The input can be a simple text or a Stream (the relevant
archiverfunction takes care of disambiguation). -
container(): JSZip
Returns the underlying ZIP container; this is used when creating a "collection", ie, when the the final content is generated from several zip containers.
- content: Buffer | ArrayBuffer | null
-
get_content(): Promise<Buffer | ArrayBuffer>
Return the final content of the book all packed up. If not yet done, the content is generated using the relevant
jszipfunction, packaging all content that has been added. -
name(): string
Return the name of the final file, as provided at constructor time. This is based on the short name of the document, or the name provided in the configuration file.
The OPF package
The OPF Wrapper
-
add_a11y_feature(features: string[]): void
Add accessibility feature strings to the metadata
-
add_collection(new_collection: Collection): void
Add a new OPF collection. This is used when the final EPUB is itself a collection of parts; each collection in the OPF sense collects the constituents of a specific part.
-
add_creators(creators: string[]): void
Add a list of creators (authors) to the publication.
-
add_dates(date: string): void
Set the date and the modification date of the publication.
-
add_manifest_item(): voiditem: ManifestItem,add_spine_item?: boolean
Add a manifest item, i.e., the reference to a resource that is part of the publication.
-
add_spine_item(): voididref: string,add_linear?: boolean
Add a spine item, i.e., the reference to the resource in the manifest that is a constituent of the spite (i.e., reading order) of the book
-
add_wcag_link(): void
Add an A11y link to WCAG A, to specify that the document conforms to this level
-
id: number
Id generated to the editors for cross reference
-
serialize(): string
Serialize the Package document into (pretty printed) XML.
-
thePackage: Package
The Package document content itself, stored in a JSON object for an easier manipulation
Representations of the "collections" element
The minimal metadata, used in collections
The "link" element content, as define in the spec. @rel is optional, because it is also used for OPF collections, and
@rel is indeed optional in that context.
Encoding of the XML structure of the package file in JSON; simply a wrapper around [[PackageContent]].
Generate the Overview.xhtml entry
Generate the resource entry for the Overview.xhtml item into the package; that includes setting the various manifest item
properties (see manifest item properties).
Title page
Create the cover page: it is an XHTML file with title, editors, copyright information, and a disclaimer whereby the EPUB version of the document is not authoritative.
Some common utilities
Convert an ISO formatted date to a more readable format.
Remove any XML/HTML tags from the input; <br/> tags are replaced by space and all other tags are removed.
Filter XML entities in an xhtml code, and turn them into their equivalent hexadecimal Unicode point
“Slice” a long text into lines separated by the (HTML) <br/> tag. Used as a rudimentary tool
when adding the title lines to an SVG content.
Convert an HTML5 content (in text or as a DOM) into XHTML5.