joseph/The Zhook format

## The Zhook format
DRAFT SPECIFICATION


# Zhook: Zip + HTML + Book.

Software that displays a Zhook file is here called a Reading System (RS).

A Zhook file is a zip file with a .zhook extension, which must contain:

* index.html (the Index)
* cover.png

It may also contain stylesheets, images and other media as referenced in
the Index.

The Index should be HTML5 or higher. The entire text content of the book
belongs in this file.

Book metadata may be defined with HTML <meta> elements in the Index, using
the name and content attributes. There is no required metadata. The RS
must document what meta names it supports.

The RS must give the <html> element an id that is unique to the RS (and
document it). The RS may support whatever CSS properties it likes. It
must document what properties are un/supported. Book designers should
provide a baseline set of CSS rules for all Reading Systems. They may
target specific Reading Systems with special CSS rules where relevant,
using the <html> id, CSS3 media queries or other viable techniques.

The RS may modify the DOM. The RS must document these modifications so that
book designers may prepare their CSS accordingly.

Specifically, the RS may split the DOM into sequential components. If it
does, it should make a separate component for every <article> element that
is a direct child of an <article> or <body> element, unless the candidate
component has a later sibling element that is not an <article>. It may do
additional splitting, if this is documented.

The RS should document what HTML microformats it supports for interaction
(such as footnotes, maps, table navigation, image zooming, video, etc).
The RS may use a documented microformat for the Table of Contents, if it
identifies it in the Index. Otherwise, it should derive the Table of
Contents from HTML elements, using the practical algorithm for HTML5[1].

The RS may disable <script> elements and event handler attributes (eg,
onclick). If so, it must document this; if not, it must document what
JavaScript operations are un/supported.


# Ochook: Offline Cache + HTML + Book.

An Ochook URI is a Zhook that has not been zipped, where the root <html>
element of the Index has a manifest attribute with the value
"ochook.manifest". The referenced ochook.manifest file must exist and
be valid.

A compliant Ochook Reading System must follow the same guidelines as a
Zhook Reading System, except:

* for the zip stuff; and
* following the Offline Cache specification in HTML5[2]


[1]: http://www.whatwg.org/specs/web-apps/current-work/multipage/sections.html#outlines
[2]: http://www.w3.org/TR/html5/offline.html
	DRAFT SPECIFICATION


	# Zhook: Zip + HTML + Book.

	Software that displays a Zhook file is here called a Reading System (RS).

	A Zhook file is a zip file with a .zhook extension, which must contain:

	* index.html (the Index)
	* cover.png

	It may also contain stylesheets, images and other media as referenced in
	the Index.

	The Index should be HTML5 or higher. The entire text content of the book
	belongs in this file.

	Book metadata may be defined with HTML <meta> elements in the Index, using
	the name and content attributes. There is no required metadata. The RS
	must document what meta names it supports.

	The RS must give the <html> element an id that is unique to the RS (and
	document it). The RS may support whatever CSS properties it likes. It
	must document what properties are un/supported. Book designers should
	provide a baseline set of CSS rules for all Reading Systems. They may
	target specific Reading Systems with special CSS rules where relevant,
	using the <html> id, CSS3 media queries or other viable techniques.

	The RS may modify the DOM. The RS must document these modifications so that
	book designers may prepare their CSS accordingly.

	Specifically, the RS may split the DOM into sequential components. If it
	does, it should make a separate component for every <article> element that
	is a direct child of an <article> or <body> element, unless the candidate
	component has a later sibling element that is not an <article>. It may do
	additional splitting, if this is documented.

	The RS should document what HTML microformats it supports for interaction
	(such as footnotes, maps, table navigation, image zooming, video, etc).
	The RS may use a documented microformat for the Table of Contents, if it
	identifies it in the Index. Otherwise, it should derive the Table of
	Contents from HTML elements, using the practical algorithm for HTML5[1].

	The RS may disable <script> elements and event handler attributes (eg,
	onclick). If so, it must document this; if not, it must document what
	JavaScript operations are un/supported.


	# Ochook: Offline Cache + HTML + Book.

	An Ochook URI is a Zhook that has not been zipped, where the root <html>
	element of the Index has a manifest attribute with the value
	"ochook.manifest". The referenced ochook.manifest file must exist and
	be valid.

	A compliant Ochook Reading System must follow the same guidelines as a
	Zhook Reading System, except:

	* for the zip stuff; and
	* following the Offline Cache specification in HTML5[2]


	[1]: http://www.whatwg.org/specs/web-apps/current-work/multipage/sections.html#outlines
	[2]: http://www.w3.org/TR/html5/offline.html