Описание формата FB2 от Sclex — различия между версиями
FBAdmin (обсуждение | вклад) |
FBAdmin (обсуждение | вклад) (→Оформление стихов) |
||
Строка 289: | Строка 289: | ||
− | ''Наша Таня громко плачет, | + | ''Наша Таня громко плачет,'' |
− | Уронила в речку мячик. | + | ''Уронила в речку мячик.'' |
+ | ''Тише, Танечка, не плачь,'' | ||
− | + | ''Не утонет в речке мяч.'' | |
− | + | ||
− | Не утонет в речке мяч.'' | + | |
Строка 312: | Строка 311: | ||
<v>Не утонет в речке мяч.</v></stanza></poem></pre> | <v>Не утонет в речке мяч.</v></stanza></poem></pre> | ||
− | |||
=== Эпиграфы === | === Эпиграфы === |
Версия 10:35, 25 мая 2006
Содержание
- 1 Общая структура документа
- 2 Первая строка документа
- 3 Раздел FictionBook
- 4 Поля раздела description
- 5 Структура разделов <body> и <section>
- 6 Форматированный текст
- 7 Пустые строки
- 8 Жирный и курсивный
- 9 Описание заголовков
- 10 Подзаголовки
- 11 Оформление стихов
- 12 Эпиграфы
- 13 Цитированный текст
- 14 Автор цитаты
- 15 Картинки
- 16 Ссылки
- 17 Оформление примечаний (footnotes)
- 18 Вложения
- 19 Юникодные символы
- 20 Значения жанров книги
Общая структура документа
FB2-документ состоит из стандартной строки, формат которой описан в следующей главе данного описания, и раздела <FictionBook>.
Раздел FictionBook состоит из таких подразделов в указанном ниже порядке:
- <description> ? который описывает заголовок документа. Одно и только одно вхождение. (фразы вроде "одно и только одно вхождение" говорят, сколько раз подряд может идти данный тэг в данном месте документа)
- <body> ? описывает тело документа. Одно или более вхождений.
- <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> состоит из перечисленных ниже частей в указанном порядке:
- <title-info> ? данные о книге. Одно и только одно вхождение.
- <src-title-info> ? данные об исходнике книги (до перевода). От нуля до одного вхождений.
- <document-info> ? информация об FB2-документе. Одно и только одно вхождение.
- <publish-info> ? сведения об издании книги, которая была использована как источник при подготовке документа. От нуля до одного вхождений.
- <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> могут идти в указанном порядке:
- Картинка <image/>, которая будет отображаться вверху раздела. От нуля до одного вхождений.
- Заголовок <title>. От нуля до одного вхождений.
- Эпиграф <epigraph>. Любое число вхождений.
- Раздел <section>. Любое число вхождений.
Откуда видно, что ни один подраздел не является обязательным.
Для раздела <section> имя описывается свойством id. Например так:
<section id="note33">
Раздел <section> состоит из следующих частей в указанном порядке:
- Заголовок <title>. От нуля до одного вхождений.
- Эпиграф <epigraph>. Любое число вхождений.
- Картинка <image/>, которая будет отображаться вверху раздела. От нуля до одного вхождений.
- Аннотация <annotation>, описывающая раздел. От нуля до одного вхождений.
- Либо подраздел <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>. Он может нести внутри себя следующие части в указанном порядке:
- Заголовок <title>. От нуля до одного вхождений.
- Эпиграф <epigraph>. Любое число вхождений.
- Строфы <stanza>. Одно или более вхождений. Строфа <stanza> ? это группа строк стихотворения, отделенная пустым промежутком от остальных строк. Отдельная строка стихотворения помечается тэгом <v>, который должен быть вложен в <stanza>.
- Автор стихотворения <text-author>. Любое число вхождений.
- Дата написания <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-документа.