booki-zip-standard.txt

   1 Booki-zip format
   2 ================
   3
   4 This describes the booki-zip format that Booki, Espri, and Objavi use
   5 to communicate with each other.
   6
   7 Zip container format.
   8 =====================
   9
  10 A booki-zip file is a zip file[1], with certain restrictions.  The
  11 ultimate test of whether a zip is correctly encoded is whether its
  12 contents can be extracted by the zipfile modules in Python 2.5 and
  13 2.6.  This means the contents must be either uncompressed or
  14 deflate-compressed.  ZIP64 extensions are OK (though unnecessary in
  15 practical terms), but encryption and comments are not.
  16
  17 The first file in the zip should be uncompressed and named "mimetype".
  18 It should contain only the 23 characters "application/x-booki+zip".
  19 This string will end up in the first few bytes of the zip file,
  20 allowing it to be identified without unzipping.
  21
  22 Directory structure.
  23 ====================
  24
  25 As well as the just mentioned "mimetype", the booki-zip must have a
  26 file called "info.json" in its root directory, the contents of which
  27 will be described shortly.  Any other files in the root directory
  28 should be html files intended for editing with Booki.  Any associated
  29 files that are not directly editable by Booki should be in a
  30 subdirectory named 'static'.   Here is an example structure:
  31
  32 /
  33   mimetype
  34   Introduction.html
  35   UseCases.html
  36   AdamsTips.html
  37   Credits.html
  38   info.json
  39 static/
  40     BookSprints-ott-adam-en.jpg
  41     Blog-writers-en.png
  42     Floss-100-en.gif
  43     example.css
  44
  45 All references from the html to the files in 'static' should use
  46 relative addresses.  For example, an image should be linked thus:
  47
  48 <img src="static/BookSprints-ott-adam-en.jpg" alt="" />
  49
  50 It is recommended but not required that the file names have
  51 conventional extensions (".html", ".jpg", etc).  File names should not
  52 contain spaces, and must meet the restrictions imposed by the zip
  53 format.
  54
  55 There should be nothing in the root directory other than "mimetype",
  56 "info.json", and the html files, and there should be no other
  57 subdirectories other than "static".  Apart from starting with
  58 "mimetype", there is no required order to the arrangement of entries
  59 within the zip file itself.  Other than "mimetype", files should be
  60 deflated-compressed.
  61
  62 character encoding
  63 ==================
  64
  65 All html files, and info.json, should be encoded as utf-8.
  66
  67 info.json
  68 =========
  69
  70 The "info.json" file describes the structure of the document and
  71 carries metadata.  It is a JSON file [3], containing a single JSON
  72 object with 5 members, as shown here:
  73
  74 {
  75   "version": 1,
  76   "spine": [ ... ],
  77   "TOC": [ ... ],
  78   "manifest": { ... },
  79   "metadata": { ... }
  80 }
  81
  82 Being JSON object members, the ordering of these elements is not
  83 significant.  The following order is for narrative purposes only.
  84
  85 info.json version
  86 =================
  87
  88 This indicates which version of the booki-zip standard is being used.
  89 This document describes version 1.  If the version is not 1, nothing
  90 else here necessarily applies.
  91
  92 info.json manifest
  93 ==================
  94
  95 The manifest is a mapping of identifiers to file names and mime-types.
  96 Each entry looks like:
  97
  98  identifier: {
  99     "filename": filename,
 100     "mimetype": mimetype,
 101     "contributors": contributors,
 102     "rightsholders": rightsHolders,
 103     "license": license
 104 }
 105
 106 The constraints on *identifier* match the XML name specification[4]
 107 (in short, avoid spaces and most punctuation).  In practise, the
 108 *identifier* is often related to the *filename*.
 109
 110 *filename* locates the file within the zip, and must match a path in
 111 the zip index.
 112
 113 *mimetype* is the IANA media type [5] of the file.  Booki-editable
 114  html files must be of type 'text/html', and other files should be
 115  correctly identified.
 116
 117 *contributors* is a list of names of people who have contributed to this
 118  file.  It can be empty.
 119
 120 *rightsHolders* is a list of the people or organisation that manages
 121  the rights for the chapter
 122
 123 *license* - a list of licenses applicable to the chapter.  If more
 124  than one license is listed, the disjunction of these licenses
 125  applies.  For the common licenses which have abbreviations listed in
 126  the license section below, the abbreviation should be used.  Other
 127  licenses should be listed as an url, which could be a relative url to
 128  a file in the booki-zip.  Copyrighted files with no sharing license
 129  should have an empty list ("[]"), and files out of copyright should
 130  have "public domain" as their single member.
 131
 132 The manifest shouldn't list the 'mimetype' or 'info.json' files, just
 133 the editable html and associated static files.
 134
 135 An example manifest, containing two html files and an image, is shown
 136 here:
 137
 138   "manifest": {
 139     "Introduction": [
 140       "url":           "Introduction.html",
 141       "mimetype":      "text/html",
 142       "contributors":  ["Adam Hyde", "Aleksander Erkalovic"]
 143       "rightsholders": ["Adam Hyde"],
 144       "license":       ["CC-BY-SA"]
 145     ],
 146     "arbitrary-identifier_0005": [
 147       "url":          "UseCases.html",
 148       "mimetype":      "text/html",
 149       "contributors":  [],
 150       "rightsholders": ["Wikimedia Foundation"],
 151       "license":       ["FDL","CC-BY-SA"],
 152     ],
 153     "BookSprints-ott-adam-en.jpg": [
 154       "url":           "static/BookSprints-ott-adam-en.jpg",
 155       "mimetype":      "image/jpeg",
 156       "contributors":  ["Ansell Adams"],
 157       "rightsholders": ["Ansell Adams"],
 158       "license":       []
 159     ]
 160   }
 161
 162
 163 info.json spine
 164 ===============
 165
 166 The spine lists the identifiers of all the html files in the order
 167 they appear in the book.  It looks like:
 168
 169  "spine": [ identifier, identifier,... ]
 170
 171 where each *identifier* is the manifest identifier for an editable
 172 html page.
 173
 174 Here is a possible spine for the manifest used in the previous
 175 example:
 176
 177   "spine": ["Introduction", "arbitrary-identifier_0005"]
 178
 179 info.json TOC
 180 =============
 181
 182 The TOC (Table of Contents) specifies navigation points with the book.
 183 It uses a nested structure, with less significant divisions being
 184 contained within the "children" attribute of the greater division.
 185
 186 The "TOC" element itself is a list of objects with the following
 187 structure:
 188
 189  {
 190    "title":    division title (optional),
 191    "url":      filename and possible fragment ID,
 192    "type":     string indicating division type (optional),
 193    "role":     epub guide type (optional),
 194    "children": list of TOC structures (optional)
 195  }
 196
 197 *title* is a free string giving the divisions title. It may be omitted.
 198
 199 *url* points to the start of the division.  It should consist of a
 200  filename as found in the manifest, optionally followed by a '#' and a
 201  fragment identifier.
 202
 203 *type* is a string indicating what kind of navigation point it is.
 204  This might be used to determine text styles.
 205
 206 *role*, if present, indicates the navigation point has a particular
 207  structural role.  It must be a keyword for "reference type" as
 208  defined in the guide section of the epub OPF specification[6].
 209
 210 *children*, if present, contains a list of objects following this same
 211  specification.  These are subsections of this section.
 212
 213 An example:
 214
 215 "TOC": [
 216    {
 217     "title": "INTRODUCTION",
 218     "url": "Introduction.html",
 219     "type": "booki-section",
 220     "children": [
 221         {
 222          "title": "WHAT IS GSoC?",
 223          "url": "Introduction.html",
 224          "type": "chapter",
 225          "role": "text"
 226          },
 227         {
 228          "title": "WHY GSOC MATTERS",
 229          "url": "Testimonials.html",
 230          "type": "chapter",
 231          "children" [ ... ]
 232          }
 233       ]
 234    }
 235 ]
 236
 237 info.json metadata
 238 ==================
 239
 240 The names in the metadata object are "namespaces" in which "keywords"
 241 are defined.  The objects referred to by keywords are further divided
 242 by "scheme".  Each scheme points to a list of values.  If the keyword
 243 is indivisible, there should be a single scheme identified by an empty
 244 string ("").  Further, if a scheme is the primary default for that
 245 keyword, it may be identified by an empty string as well as by its
 246 scheme name.
 247
 248   Here's the diagram:
 249
 250  "metadata": {
 251      namespace: {
 252         keyword: {
 253            scheme: [value, value,...],
 254            scheme: [value],...
 255         },...
 256      },...
 257   }
 258
 259 Booki uses Dublin Core[7] metadata keywords wherever possible, which are
 260 stored under the namespace "http://purl.org/dc/elements/1.1/".
 261
 262 An example metadata section is shown below:
 263
 264   "metadata": {
 265     "http://purl.org/dc/elements/1.1/": {
 266       "publisher": {
 267         "": ["FLOSS Manuals http://flossmanuals.net"]
 268       },
 269       "language": {
 270         "": ["en"]
 271       },
 272       "creator": {
 273         "": ["The Contributors"]
 274       },
 275       "contributor": {
 276         "": ["Jennifer Redman", "Bart Massey", "Alexander Pico",
 277              "selena deckelmann", "Anne Gentle", "adam hyde", "Olly Betts",
 278              "Jonathan Leto", "Google Inc And The Contributors",
 279              "Leslie Hawthorn"]
 280       },
 281       "title": {
 282         "": ["GSoC Mentoring"]
 283       },
 284       "date": {
 285         "start": ["2009-10-23"],
 286         "last-modified": ["2009-10-30"]
 287       },
 288       "identifier": {
 289         "flossmanuals.net": ["http://en.flossmanuals.net/epub/GSoCMentoring/2009.10.23-19.49.01"],
 290         "archive.org": ["gsocmentoring00fm"]
 291       },
 292       "rights":{
 293         "": ["Copyright The Contributors.  Licensed under the GPLv2.  See Appendix.html in this zip file or http://www.gnu.org/licenses/gpl-2.0.txt for details"]
 294       }
 295    },
 296    "http://booki.cc/": {
 297       "server": {
 298         "": ["en.flossmanuals.net"]
 299       },
 300       "book": {
 301          "": ["GSoCMentoring"]
 302       },
 303       "dir": {
 304          "": ["LTR"]
 305       },
 306       "license": {
 307          "": ["GPL"]
 308       }
 309   }
 310
 311 There must be "language", "creator", "identifier", and "title" Dublin
 312 Core elements present.  The "contributor" Dublin Core element should
 313 list all contributors to individual files, as listed in the manifest,
 314 unless those contributors are already identified in the "creator"
 315 field.
 316
 317 The Dublin Core "rights" element should contain a human readable
 318 summary of the book's copyright and license.
 319
 320 The "http://booki.cc/" namespace can contain the following elements:
 321
 322 *server* the Booki or FLOSS Manuals server on which the book is
 323  edited.
 324
 325 *book* the book's identifier on that server.
 326
 327 *dir* the primary text direction ('LTR' or 'RTL').  If unspecified,
 328  'LTR' is assumed, though software may determine the text direction
 329  by inspecting the contents.
 330
 331 *license* licenses used in the book, using if possible the
 332  abbreviations in the next section.  Multiple licenses listed here do
 333  not necessarily indicate a disjunction of these licenses applies to
 334  each file; rather it might mean each license applies to a different
 335  subset of the files.  All licenses used should be included in the
 336  text of the book.
 337
 338 Other namespaces are permitted but will not be used by Booki.  They
 339 will, as far as possible, be preserved through Booki edits and be
 340 exported to other formats.
 341
 342 license abbreviations
 343 =====================
 344
 345 The following abbreviated license identifiers should be used for the
 346 licenses defined at the corresponding URLs.
 347
 348   GPL        http://www.gnu.org/licenses/gpl.txt
 349   GPLv2      http://www.gnu.org/licenses/gpl-2.0.txt
 350   GPLv2+     http://www.gnu.org/licenses/gpl-2.0.txt [or greater version]
 351   GPLv3      http://www.gnu.org/licenses/gpl-3.0.txt
 352   GPLv3+     http://www.gnu.org/licenses/gpl-3.0.txt [or greater version]
 353   LGPL       http://www.gnu.org/licenses/lgpl.txt
 354   LGPLv2.1   http://www.gnu.org/licenses/lgpl-2.1.txt
 355   LGPLv2.1+  http://www.gnu.org/licenses/lgpl-2.1.txt [or greater version]
 356   LGPLv3     http://www.gnu.org/licenses/lgpl-3.0.txt
 357   BSD        http://www.debian.org/misc/bsd.license
 358   MIT        http://www.opensource.org/licenses/mit-license.html
 359   Artistic   http://dev.perl.org/licenses/artistic.html
 360   CC-BY      http://creativecommons.org/licenses/by/3.0/
 361   CC-BY-SA   http://creativecommons.org/licenses/by-sa/3.0/
 362   public domain  [no copyright]
 363
 364 Licenses not shown here should be listed as a URL that points to their
 365 text.  It is possible for the URL to point to a local file within the
 366 booki-zip, but it is preferable to use a stable external link if one
 367 exists.
 368
 369 references
 370 ==========
 371
 372 [1] Zip specification: http://www.pkware.com/documents/casestudies/APPNOTE.TXT
 373 [2] zipfile module: http://docs.python.org/library/zipfile.html
 374 [3] JSON specification: http://json.org/
 375 [4] XML name specification http://www.w3.org/TR/REC-xml/#NT-Name
 376 [5] Media types http://www.iana.org/assignments/media-types/
 377 [6] Guides in epub http://www.idpf.org/2007/opf/OPF_2.0_final_spec.html#Section2.6
 378 [7] Dublin Core metadata elements http://dublincore.org/documents/2004/12/20/dces/
 379
 380