Home News Docs FB 2.0 FB2.0 Scripts&Utilitites Russian page

FictionBook description

FictionBook is based on the XML standard from W3C, and FictionBook documents are well-formed XML documents, conforming to the FictionBook schema. Since the adoption of hyperlinks in FictionBook version 2.0, XML namespaces are now mandatory for all FictionBook documents. The main FictionBook namespace is “http://www.gribuser.ru/xml/fictionbook/2.0”, the version number in the namespace URL will change as new versions of the standard are developed. The other required namespace is “http://www.w3.org/1999/xlink” for XLink. It should be included if any hyperlink elements are used in the document.

The overall document structure is straightforward and resembles that of HTML. However, the main goal of this work is to design an XML based document that focuses on the document’s logical structure, and not on the presentation features. An essential characteristic of structured markup is that it explicitly distinguishes the structure and semantic content of a document. It does not mark up the way in which the document will appear to the reader, in print or otherwise. In this specification we deliberately didn’t include any direct means for specifying presentation features. The only way to influence the rendering process is by specifying styles for paragraphs and strings of characters. Instead some unique elements are provided to separate logical parts of book, like poems, citations, and epigraphs.
The complete FictionBook schema is available in FictionBook.xsd and FictionBookLinks.xsd, so I will only provide a high level description of the elements here.

All text in the document is stored in the following paragraph-type elements: p, v, and subtitle. An empty-line element that has no content is used to insert one line of vertical space. A few more complex containers are built from these basic elements: title (contains any number of p and empty-line), annotation, poem, cite, epigraph.

All documents start with the FictionBook root element, under which stylesheet, description, body and binary elements can occur. The stylesheetelements immediately below root contain stylesheets; their type attribute contains the MIME type of stylesheet. It is recommended to include one text/css stylesheet to ease conversion to other formats if any styles are used in the document. Binary elements are quite simple too and contain any base64-encoded opaque data that might be needed to render the document. They must always have the id and content-type attributes.

Description element contains all information about the book that is further divided into four main categories: title-info, document-info, publish-info, and custom-info.

Title-info holds data related to the book itself. Genre specifies the book’s genre, the match attribute is used when the genre is not exactly identified by the single genre keyword, e.g. some book might be both a detective and a science fiction story. Authors list is stored in the author element, that has traditional first-name, middle-name, last-name fields, and a couple of optional home-page and email subelements. Book-title is the book’s title. Annotation contains a free form short description of the book. Keywords field lists any relevant keywords that can be used by the search engines. Date element specifies a free format date the book was written at, the optional value attribute must have the date in computer readable format if present. Src-lang and lang elements have the original language and the document’s language if this is a translation. Translator elements have exactly the same structure as the author element above, and are used to list the translators of the book if this is a translation.

Information about this particular document is gathered in the document-info element, that contains author, program-used, date, src-url, src-ocr, version, and history elements. Author and date elements have the same type as in the title-info group. History’s type is the same as in annotation; it is intended to list major changes to the document. Version has the free format version of the document, and should be incremented when the document is changed.

Publish-info block is used when the document is created from a hardcopy edition, and has a few bibliographical fields like book-name, publisher, city, year and isbn.
Custom-info records should be used to store information that does not fit into any of the above fields. These must always have the required info-type attribute.

The next major part of FictionBook document is body that contains the actual book’s text. The first body element is always the main subdocument in the book. Subsequent bodies can be used to store footnotes, comments and other stuff that does not belong to the normal text flow in the book. Each body element can contain an optional title, optional epigraph and at least one section.

There are two distinct kinds of sections. One contains other subsections only, and the other contains actual text paragraphs. It is not possible to mix subsections and paragraphs inside the same container in the current version of FictionBook standard. Each section can have a number of optional header fields: title, epigraph, image, and annotation. After these, there must be at least one paragraph-type element for text sections or at least one subsection for others.

The FictionBook provides a few elements for hyperlinking, an essential feature for electronic documents in our modern times. Hyperlinks in FictionBook are based on the XLink specification from the W3 consortium, and are a subset of the XLink. Currently only simple links from the XLink are included in FictionBook. First is the a element, that can be included in any paragraph-type element. It has two required attributes: xlink:type with the fixed value of “simple”, and the xlink:href, that specifies the link destination in XPath/XPointer language. For link destinations within the same document, a simple form of XPointer expression can be used: “#<id>”. The optional type attribute can be used to further specify the meaning of the link. At this time only one possible value for this attribute is defined, “note” for footnotes. The second hyperlinking element is image that has the same mandatory XLink attributes, and is used for inserting inline images into the text flow. Link destinations are marked with the id attribute that can occur on all paragraph-type elements, on most high-level containers, and on the binary elements.


To illustrate the description there is a short FictionBook example, first few paragraphs from "A study in scarlet", taken from Project Gutenberg:


<?xml version="1.0" encoding="iso-8859-1"?>

<FictionBook xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns="http://www.gribuser.ru/xml/fictionbook/2.0">
  <description>
    <title-info>
      <genre match="100">detective</genre>
      <author>
        <first-name>Arthur</first-name>
        <middle-name>Conan</middle-name>
        <last-name>Doyle</last-name>
      </author>
      <book-title>A Study in Scarlet</book-title>
      <annotation>
      </annotation>
      <date value="1887-01-01">1887</date>
    </title-info>
    <document-info>
      <author>
        <first-name/>
        <last-name/>
        <nickname>Haali</nickname>
      </author>
      <program-used>vim, perl</program-used>
      <date value="2002-06-01">2002-06-01</date>
      <src-ocr>
        Project Gutenberg, file: study10.txt

        This etext is prepared directly from an 1887 edition, and care has
        been taken to duplicate the original exactly, including typographical
        and punctuation vagaries. Additions to the text include adding the
        underscore character (_) to indicate italics, and textual end-notes
        in curly braces ({}). Thanks to Randolph Cox for providing the book
        for etexting. Etext prepared by Roger Squires rsquires@unm.edu
      </src-ocr>
      <version>1.0</version>
      <history>
        <p>2002-06-01 Initial version</p>
      </history>
    </document-info>
  </description>
  <body>
    <section>
      <p>Frontispiece, with the caption: "He examined with his glass the word
        upon the wall, going over every letter of it with the most minute
        exactness." (<emphasis>Page</emphasis> 23.)</p>
    </section>
    <section>
      <title><p>PART I.</p></title>
      <section>
        <p>(<emphasis>Being a reprint from the reminiscences of</emphasis> JOHN
          H. WATSON, M.D.,<emphasis> late of the Army Medical
            Department.</emphasis>) <a xlink:href="#N2" type="note">2</a></p>
      </section>
      <section>
        <title><p>CHAPTER I. MR. SHERLOCK HOLMES.</p></title>
        <p>IN the year 1878 I took my degree of Doctor of Medicine of the
          University of London, and proceeded to Netley to go through the
          course prescribed for surgeons in the army. Having completed my
          studies there, I was duly attached to the Fifth Northumberland
          Fusiliers as Assistant Surgeon. The regiment was stationed in India
          at the time, and before I could join it, the second Afghan war had
          broken out. On landing at Bombay, I learned that my corps had
          advanced through the passes, and was already deep in the enemy's
          country. I followed, however, with many other officers who were in
          the same situation as myself, and succeeded in reaching Candahar in
          safety, where I found my regiment, and at once entered upon my new
          duties.</p>
        <p>The campaign brought honours and promotion to many, but for me it
          had nothing but misfortune and disaster. I was removed from my
          brigade and attached to the Berkshires, with whom I served at the
          fatal battle of Maiwand. There I was struck on the shoulder by a
          Jezail bullet, which shattered the bone and grazed the subclavian
          artery. I should have fallen into the hands of the murderous Ghazis
          had it not been for the devotion and courage shown by Murray, my
          orderly, who threw me across a pack-horse, and succeeded in bringing
          me safely to the British lines.</p>
      </section>
    </section>
  </body>
  <body name="footnotes">
    <section>
      <subtitle id="N2">2</subtitle>
      <p>"JOHN H. WATSON, M.D.": the initial letters in the name are
        capitalized, the other letters in small caps. All chapter titles are in
        small caps. The initial words of chapters are in small caps with first
        letter capitalized.</p>
    </section>
  </body>
</FictionBook>

Last modified: (none)
Author: Mike Matsnev, mike@haali.net