hpub specification

HPub Specification 1.0.1 [2011-11-21]

1. Abstract

The HPub (HTML Publication) standard is a file format designed to release rich content books in a simple and manageable package.

2. The principles

We want a digital publishing format that:

1. Allows great designs
2. Allows both pixel-perfect and flexible reflowable publications
3. Is simple for authors
4. Is simple for parsers

3. The Spec

1. An HPub publication is a normal .zip file with ".hpub" extension. You can have a non-zipped HPub.
2. The content format must be HTML5.
3. It must contain a file "book.json", lowercase, following the HPub specifications below.
4. All the assets (CSS, images, JS, ...) should be included in the package and referenced relatively from the HTML5 files.
5. Optionally it should include index.html that will be used as navigation.

4. book.json

The file book.json must be a properly formatted JSON file.

An example of the minimal form:

{
  "title": "The Study in Scarlet",
  "author": "Arthur Conan Doyle",
  "url": "book://bakerframework.com/books/arthurconandoyle-thestudyinscarlet",

  "contents": [
    "Article-Lorem.html",
    "Article-Ipsum.html",
    "Article-Gaium.html",
    "Article-Sit.html",
    "Article-Amet.html"
  ]
}

An example of the full form:

{
  "hpub": 1,
  "title": "The Study in Scarlet",
  "author": ["Arthur Conan Doyle"],
  "creator": ["D. Casali", "M. Colombo", "A. Morandi", "F. Fortes"],
  "publisher": "Baker Pubs",
  "date": "2011-08-23",
  "url": "book://bakerframework.com/books/arthurconandoyle-thestudyinscarlet",
  "cover": "assets/study-in-scarlet.png",

  "orientation": "both",
  "zoomable": false,

  "-baker-background": "#000000",
  "-baker-vertical-bounce": true,
  "-baker-index-bounce": true,
  "-baker-index-height": 150,
  "-baker-media-autoplay": true,

  "-treesaver-loopArticles": "true",

  "contents": [
    "Book Cover.html",
    "Book Index.html",
    {
        "url": "Front-Article.html",
        "title": "The Wonders of Hpub",
        "author": "The community"
    },
    "Part1-01.html",
    "Part1-02.html",
    "Part1-03.html",
    "Part1-04.html",
    "Part1-05.html",
    "Part1-06.html",
    "Part1-07.html",
    "Part2-01.html",
    "Part2-02.html",
    "Part2-03.html",
    "Part2-04.html",
    "Part2-05.html",
    "Part2-06.html",
    "Part2-07.html",
    "Colophon.html"
  ]
}

Required parameters:

• title ( string ): Title of the publication
• author ( string|array ): Author of the publication. Use an array when more than one author is required, in the defined order.
• If array, each item should be a string containing the name of the author.
• url ( string ): Unique identifier of the publication, using the book:// protocol.
• contents ( array ): List of all the pages contained in the publication, in the correct visualization order. Each item should be either a string containing the filename or a file hash.
• If file hash, it must have at least the "url" item, pointing to the file.

Optional parameters:

• hpub ( number, default: 1 ): Version of the HPub specification.
• creator ( string|array ): Creator of the publication. Person that edited and prepared the digital publication itself.
• If array, each item should be a string containing the name of the author.
• publisher ( string ): Publisher entity.
• date ( string ): Release date of the current publications. This should be updated when the content of the publication gets updated. The format must be "yyyy-mm-dd" (year, month, day: i.e. "2011-10-03").
• orientation ( string, default: both ): Since ebooks can be read on devices supporting different orientations, the publication orientation can be defined. Possible options are "both", "portrait", "landscape", all lowercase.
• zoomable ( bool, default: false ): Since ebooks can be read on touch devices supporting pinch to zoom, the author might choose to allow zoom of the page, instead of using a specific JavaScript solution.
• cover ( string ): relative path to the location of the PNG file.

Extensions:

• Proprietary extensions can be added to the file, prefixed with a "dash" character (-), the name of the platform, another "dash" and then the name of the property. For example: -baker-background, -treesaver-loop-articles, and so on. For more examples, see the Baker extensions.