Описание формата FB2 от Sclex

Материал из FictionBook
Перейти к: навигация, поиск

Общая структура документа

FB2-документ состоит из стандартной строки, формат которой описан в следующей главе данного описания, и раздела <FictionBook>.

Раздел FictionBook состоит из таких подразделов в указанном ниже порядке:

  1. <description> ? который описывает заголовок документа. Одно и только одно вхождение. (фразы вроде "одно и только одно вхождение" говорят, сколько раз подряд может идти данный тэг в данном месте документа)
  2. <body> ? описывает тело документа. Одно или более вхождений.
  3. <binary> ? содержит приложенные к файлу двоичные объекты ? картинки и прочее. Любое число вхождений.

Иными словами, присутствуют как минимум разделы <description> с <body>, а остальное ? по необходимости.

Пример: 

<?xml version="1.0" encoding="windows-1251"?>
<FictionBook xmlns="http://www.gribuser.ru/xml/fictionbook/2.0"
  xmlns:l="http://www.w3.org/1999/xlink">
<description>
  ...
</description>
<body>
  ...
</body>
  ...
<body name="notes">
  ...
</body>
<binary id="cover.jpg" content-type="image/jpeg">/9j/4AAQSkZJRgABAgAAZABkAAD/
  ...
</binary>
</FictionBook>


Первая строка документа

Первая строка FB2-документа имеет следующий стандартный вид: 

<?xml version="1.0" encoding="windows-1251"?>

Свойство encoding задает кодировку документа, в нашем случае это windows-1251. А может быть, например, utf-8.

Раздел FictionBook

Этот раздел начинается сразу за первой строкой и открывается таким образом: 

<FictionBook xmlns="http://www.gribuser.ru/xml/fictionbook/2.0"
  xmlns:l="http://www.w3.org/1999/xlink">

В xmlns:l вместо l может быть написано и другое имя, главное, чтобы потом оно использовалось в ссылках по всему документу. То есть, если объявлено xmlns:l="http://www.w3.org/1999/xlink", то ссылки надо оформлять как <a l:href=...>...</a>, а если объявлено xmlns:xlink="http://www.w3.org/1999/xlink", то надо так: <a xlink:href=...>...</a>. Аналогично и для ссылок в тэгах <image/>.


Поля раздела description

Раздел <description> состоит из перечисленных ниже частей в указанном порядке:

  1. <title-info> ? данные о книге. Одно и только одно вхождение.
  2. <src-title-info> ? данные об исходнике книги (до перевода). От нуля до одного вхождений.
  3. <document-info> ? информация об FB2-документе. Одно и только одно вхождение.
  4. <publish-info> ? сведения об издании книги, которая была использована как источник при подготовке документа. От нуля до одного вхождений.
  5. <custom-info> ? произвольная информация. Любое число вхождений.

То есть обязательны разделы <title-info> и <document-info>, а остальные добавляются по необходимости.

Рассмотрим пример заполнения его полей (они должны следовать в указанном порядке): 

  <description>
  <title-info>
   <genre>sci_medicine</genre>
   <genre>science</genre>
   <author>
    <first-name>Борис</first-name>
    <last-name>Сергеев</last-name>
   </author>
   <book-title>Ум хорошо?</book-title>
   <annotation>
    <p>Об организации высших психических функций.</p>
   </annotation>
   <date value="1984-01-01">1984</date>
   <coverpage><image l:href="#cover.jpg"/></coverpage>
   <lang>ru</lang>
   <src-lang>ru</src-lang>
   <sequence name="Раскрывая тайны психики" number="2"/>
  </title-info>
  <document-info>
   <author>
    <nickname>Sclex</nickname>
    <email>sclex_at_inbox.ru</email>
   </author>
   <program-used>Dn/2, Opera 8.50, Bred3</program-used>
   <date value="2006-05-21">2006-05-21</date>
   <id>91824ABE-EEF7-48C3-AAAA-A719EFC4824A</id>
   <version>1.1</version>
   <history>
     <p>1.0 - подготовка fb2 by Sclex</p>
     <p>1.1 - вычитка ошибок by Sclex</p>
   </version>
  </document-info>
  <publish-info>
   <book-name>Борис Федорович Сергеев. Ум хорошо?</book-name>
   <publisher>Молодая гвардия</publisher>
   <city>М.</city>
   <year>1984</year>
  </publish-info>
 </description>

Рассмотрим последовательно смысл значений тэгов заголовка. (Некоторые из тэгов отсутствуют в примере, но описаны ниже).

Внутри раздела <title-info>:

<genre> ? указывает жанр книги. Список возможных значений приведен в соответствующем разделе данного описания. Любое число вхождений, то есть книга может относиться к нескольким жанрам одновременно. В нашем примере это sci_medicine и science, то есть книга относится к жанрам "Медицина" и "Научно-образовательная: Прочее".

<author> ? содержит информацию об авторе книги. Возможны такие вложенные тэги как <first-name> ? имя, <last-name> ? фамилия, <middle-name> ? отчество, <nick> ? ник, и <email> ? адрес электронной почты. Одно или более вхождений, так как может быть несколько авторов у одной книги. В нашем примере определены имя Борис и фамилия Сергеев.

<book-title> ? описывает название книги. Одно и только одно вхождение. В нашем примере книга называется "Ум хорошо?".

<annotation> ? аннотация книги. Возможны в любом количестве и порядке следующие вложенные тэги: <p>, <poem>, <cite>, <subtitle>, <table>, <empty-line/> с соответствующим содержанием. От нуля до одного вхождения.

<keywords> ? содержит ключевые слова к данной книге для поисковых систем. Слова должны быть в виде неформатированного текста. От нуля до одного вхождения.

<date> ? хранит дату написания книги. В свойстве value дата описывается в формате ГГГГ-ММ-ДД, а внутри тэга дата задается в текстовом виде. От нуля до одного вхождения. В нашем примере свойство value имеет значение 1984-01-01, то есть первое января 1984-го года, а внутри тэга прописано значение 1984.

<coverpage> ? обложка книги. Внутри может содержать только тэг <image/>. От нуля до одного вхождения. В нашем примере ссылка указывает на картинку cover.jpg, приложенную к документу (значок # говорит, что эта ссылка локальная, то есть адресует в пределах документа).

<lang> ? сообщает язык книги в документе, то есть язык после перевода. Одно и только одно вхождение. В нашем примере это ru, то есть русский язык. Полный список кодов приведен в соответствующем разделе данного описания.

<src-lang> ? определяет язык, на котором исходно написана книга, то есть язык до перевода. От нуля до одного вхождений. Те же коды, что для тэга <lang>. В нашем примере это ru, то есть русский язык. Английскому языку соответствует код en.

<translator> ? информация о переводчике книги. Возможны такие вложенные тэги как <first-name> ? имя, <last-name> ? фамилия, <middle-name> ? отчество, <nick> ? ник, и <email> ? адрес электронной почты. Любое число вхождений.

<sequence> ? сведения о том, к каким сериям относится книга. Имеет такие свойства, как name (текстовая строка) ? название серии, и number (целое число) ? порядковый номер книги в серии. Любое число вхождений. В нашем примере описана серия "Раскрывая тайны психики", и указан номер книги в серии ? вторая.

Внутри раздела <document-info>:

<author> ? содержит информацию об авторе документа. Возможны такие вложенные тэги как <first-name> ? имя, <last-name> ? фамилия, <middle-name> ? отчество, <nick> ? ник, и <email> ? адрес электронной почты. Одно или более вхождений. В нашем примере определены ник Sclex и адрес электронной почты sclex_at_inbox.ru.

<program-used> ? в виде простого перечисляет программы, использованные при создании FB2-документа. От нуля до одного вхождений. В нашем примере это Dn/2, Opera 8.50 и Bred3.

<date> ? хранит дату создания документа. В свойстве value дата описывается в формате ГГГГ-ММ-ДД, а внутри тэга дата задается в текстовом виде. Одно и только одно вхождение. В нашем примере свойство value имеет значение 2006-05-21, то есть 21-е мая 2006-го года, и такое же значение прописано внутри тэга.

<src-url> ? URL страницы, откуда взят текст для подготовки документа. Любое число вхождений.

<src-ocr> ? автор (но не писатель) текста, который был использован при подготовке документа. От нуля до одного вхождений.

<id> ? уникальный идентификатор документа FB2. Одно и только одно вхождение.

<version> ? версия документа в текстовом виде. Описывается дробным числом. Одно и только одно вхождение. В нашем случае ? 1.1.

<history> ? история создания и изменения документа. Содержит форматированный текст. Возможны в любом количестве и порядке следующие вложенные тэги: <p>, <poem>, <cite>, <subtitle>, <table>, <empty-line/> с соответствующим содержанием. От нуля до одного вхождений.

Внутри тэга <publish-info>:

<book-name> ? название оригинальной (бумажной) книги. От нуля до одного вхождений. В примере это "Борис Федорович Сергеев. Ум хорошо?".

<publisher> ? название издательства. От нуля до одного вхождений. В примере ? Молодая гвардия.

<city> ? город, в котором издана книга. От нуля до одного вхождений. В нашем случае это М., то есть Москва.

<year> ? год издания книги. От нуля до одного вхождений. В нашем случае ? 1984.

Структура разделов <body> и <section>

Тэг <body> предназначен для описания собственно тела документа. Этот тэг может иметь свойство name, которое описывает имя раздела. Например: 

<body name="notes">

Внутри раздела <body> могут идти в указанном порядке:

  1. Картинка <image/>, которая будет отображаться вверху раздела. От нуля до одного вхождений.
  2. Заголовок <title>. От нуля до одного вхождений.
  3. Эпиграф <epigraph>. Любое число вхождений.
  4. Раздел <section>. Любое число вхождений.

Откуда видно, что ни один подраздел не является обязательным.

Для раздела <section> имя описывается свойством id. Например так: 

<section id="note33">

Раздел <section> состоит из следующих частей в указанном порядке:

  1. Заголовок <title>. От нуля до одного вхождений.
  2. Эпиграф <epigraph>. Любое число вхождений.
  3. Картинка <image/>, которая будет отображаться вверху раздела. От нуля до одного вхождений.
  4. Аннотация <annotation>, описывающая раздел. От нуля до одного вхождений.
  5. Либо подраздел <section> (любое число вхождений), либо форматированный текст с картинками (любое число вхождений).

Следовательно ни один подраздел не является обязательным.

Разделов <body> в документе может быть несколько. Это используется, например, для оформления примечаний (footnotes). По умолчанию пользователю показывается первый раздел <body>, а содержание остальных должно быть доступно по гиперссылкам. Имя раздела должно отражать смысл его содержания, но для основного раздела это необязательно.

Разделы <section> должны иметь вложенную структуру согласно иерархии оглавления. Например, если документ делится на части, которые в свою очередь делятся на главы, то части будут будут описаны в разделе <section> первого уровня, а главы ? в подразделе второго уровня. Проще понять это на примере: 

<body>
  <title><p>Борис Сергеев</p><p>Парадоксы мозга</p></title>
  <section>
    <title><p>Часть 1. Великие невежды.</p></title>
    <section>
      <title><p>Глава 1. Во тьме веков.</p></title>
      <p>Когда люди стали о себе задумываться? ...</p>
      ...
    </section>
  </section>
</body>

Принято названия глав писать маленькими буквами, начиная с большой.

Еще принято кроме того, что указано в заголовке, давать имя автора и название книги в тексте документа до того, как открывается <section> первого уровня, то есть в <title>, относящемся к <body>. Это видно из вышеприведенного примера.


Форматированный текст

Форматированный текст представляет собой последовательность фрагментов, ограниченных тэгами <p>, <poem>, <subtitle>, <cite>, <table>. Также могут входить пустые строки ? <empty-line/>.

Тэг <p> предназначен для описания одного абзаца текста книги.

Например: 

<p>Вот абзац текста.</p>
<p>Еще один абзац текста.</p>


Пустые строки

Если нужно в форматированном тексте вставить пустую строку, это делается с помощью тэга <empty-line/>. Один такой тэг ? одна пустая строка. Закрывающий тэг в данном случае не требуется.

Например: 

<p>Абзац до пустой строки.</p>
<empty-line/>
<p>А вот это уже абзац после пустой строки.</p>

Жирный и курсивный

Для форматированного текста, то есть внутри тэгов <p>, <poem>, <subtitle>, <table> возможно описать текст как жирный или курсивный. Жирный текст следует выделить тэгом <strong>, а курсивный ? тэгом <emphasis>.

Например: 

<p>Вот это слово выведем <strong>жирным</strong>,
а вот это ? <emphasis>курсивным</emphasis>.</p>


Описание заголовков

Заголовки описываются тэгом <title>, который содержит в себе форматированный текст. Тэг <title> может быть вложенным в тэги <body> и <section>, причем более одного заголовка в разделе не допускается, а может его и не быть вовсе.

Пример: 

<title>
 <p>От Александрии до Лондона</p>
</title>


Подзаголовки

Подзаголовки описываются тэгом <subtitle>, который содержит простой (неформатированный) текст. Тэг <subtitle> может быть вложенным в тэги <body> и <section>.

Обычно описание подзаголовка выглядит так: 

<subtitle>* * *<subtitle>

Подзгаловком, в отличие от нормального заголовка, оформляется элемент оглавления, незначимый для структуры документа. Обычно это те самые три звездочки или x x x.


Оформление стихов

Чтобы разместить стихотворение в тексте документа, используют тэг <poem>. Он может нести внутри себя следующие части в указанном порядке:

  1. Заголовок <title>. От нуля до одного вхождений.
  2. Эпиграф <epigraph>. Любое число вхождений.
  3. Строфы <stanza>. Одно или более вхождений. Строфа <stanza> ? это группа строк стихотворения, отделенная пустым промежутком от остальных строк. Отдельная строка стихотворения помечается тэгом <v>, который должен быть вложен в <stanza>.
  4. Автор стихотворения <text-author>. Любое число вхождений.
  5. Дата написания <date>. От нуля до одного вхождений.

Например, стихотворение из двух строф:


Наша Таня громко плачет,

Уронила в речку мячик.


Тише, Танечка, не плачь,

Не утонет в речке мяч.


Следует разметить таким образом: 


<poem><stanza><v>Наша Таня громко плачет,</v>

<v>Уронила в речку мячик.</v></stanza>

<stanza><v>Тише, Танечка, не плачь,</v>

<v>Не утонет в речке мяч.</v></stanza></poem>


Эпиграфы

Для оформления эпиграфов предусмотрен тэг <epigraph>, который должен содержать внутри себя форматированный текст (любое число вхождений), а затем автора текста (тоже любое число вхождений).

Пример: 

<epigraph>
   <p>Читателям, которые станут доискиваться, какие реальные
   люди и места описаны здесь под вымышленными именами и названиями,
   я бы посоветовал посмотреть вокруг себя и заглянуть в собственную душу,
   так как в этом романе рассказано о том, что происходит сегодня почти
   во всей Америке.</p>
</epigraph>


Цитированный текст

Для разметки цитированного текста существует тэг <cite>, который может содержать форматированный текст (любое число вхождений), а затем автора цитаты (любое число вхождений).

Пример: 

<cite>
  <p>Время ? деньги.<p>
  <text-author>Бенджамин Франклин</text-author>
</cite>


Автор цитаты

Внутри тэгов <poem>, <cite> и <epigraph> возможно указать автора соответственно стихотворения, цитаты или эпиграфа. Для этого служит тэг <text-author>. Этот тэг должен стоять в самом конце родительского тэга, то есть непосредственно перед его закрытием. Допускается любое число вхождений тэга <text-author>.

Вот пример: 

<epigraph>
  <p>Кажется, знаешь о себе все, так нет.
  Находятся люди, которые знают о тебе больше.</p>
  <text-author>В. Андреев</text-author>
</epigraph>


Картинки

Картинки вставляются с помощью тэга <image/> (закрывающий тэг не требуется). Свойство href указывает на адрес картинки. Если адрес картинки начинается с символа # (решетка), то картинка находится внутри документа.

Пример: 

<image l:href="#cover.jpg"/>

В этом примере в текст вставляется картинка cover.jpg, приложенная к документу (на что указывает символ решетки перед именем).


Ссылки

Ссылки вставляются с помощью тэга <a>. Свойство href определяет адрес ссылки. Адреса с символа # (решетка) задают расположение внутри документа.

Примеры: 

<a l:href="#n1" type="note">[1]</a>

В этом примере текстом ссылки будет [1], а указывать она будет на раздел с идентификатором n1 внутри документа.

В l:href вместо l может быть и другой идентификатор, подробнее это описано в разделе "Раздел FictionBook".


Оформление примечаний (footnotes)

Примечания должны находиться в специальном разделе <body>, поименнованном notes, то есть описан он должен быть как <body name="notes">. Каждое примечание должно находиться в отдельном разделе <section> и иметь уникальный id, по которому оно будет доступно в ссылках. Вот типичный пример оформления тела примечаний: 

 <body name="notes">
  <title><p>Примечания</p></title>
  <section id="note1">
   <title>
    <p>1</p>
   </title>
   <p>Известный английский архитектор XVIII века, испытавший в
   своем творчестве сильное влияние античной архитектуры. (Здесь и
   далее прим. ред.)</p>
  </section>
  <section id="note2">
   <title>
    <p>2</p>
   </title>
   <p>Американский просветитель, живший в XVIII веке</p>
  </section>
 </body>

Ссылка на примечание должна иметь свойство type, равное значению "note". Соответствующая размещенному выше примеру ссылка на первое примечание будет выглядеть таким образом: 

в стиле Роберта Адама <a l:href="#note1" type="note">[1]</a>


Вложения

К документу FB2 могут быть приложены файлы, например картинки или что-нибудь другое. (Библиотека, правда, не примет файлы с иными вложениями, чем картинки).

Вот пример вложения: 

<binary id="cover.jpg" content-type="image/jpeg">
AQMAEAMDBgkAAA/tAAAe7gAANHz/2wCEAAgGBgYGBggGBggMCAcIDA4KCAgKDhANDQ4NDRAR
DA4NDQ4MEQ8SExQTEg8YGBoaGBgjIiIiIycnJycnJycnJycBCQgICQoJCwkJCw4LDQsOEQ4O
...
h9x8OJ/B/c+gfbXM/wDQ/qcPZ9HHjqaPi17zZ4+6deEYNxtP+H1v8Opsec//2Q==</binary>

Свойство id описывает идентификатор (имя) двоичного объекта, а свойство content-type ? MIME-тип вложения. Внутри тэга <binary> находится файл, закодированный по методу BASE64.

Чтобы библиотека приняла файл, нужно чтобы в документе не было приложенных объектов, на которые нет ссылки, и чтобы не было ссылок, которые указывают на двоичные объекты, не приложенные к файлу.

Из картинок поддерживаются форматы JPG (тип image/jpeg) и PNG (тип image/png). Поддержка формата GIF отсутствует. Файл обложки обычно принято называть cover.jpg.


Юникодные символы

В текст можно вставлять символы по их коду таблице Unicode. Для этого нужно написать значок &, потом значок #, потом десятичный код символа, потом точку с запятой.

Например для значка ? (не равно) ? код 8800, надо написать так: 

≠


Значения жанров книги

Здесь перечислены значения, которые принимает поле <genre> в заголовке FB2-документа.

Источник — «http://fictionbook.org/index.php?title=Описание_формата_FB2_от_Sclex&oldid=2139»