FB2 Backend to AsciiDoc

Background

My relations with the FictionBook 2 format were initially complicated: at first I did not recognize it, then I admitted it as the source material for the formation of my books, later, with the development of the format and related tools, it became the basis of my library.

Naturally, one of the first tasks was the problem of converting to this format. Of all the existing tools, not one suited me, and for ordinary works of art it was easier and faster for me to do in my usual text editor (jEdit or VIM).

Some minor difficulties for me were: a) a description of the document — this was solved by using a template; b) images - usually it was a cover and it could be added using the FB Editor (the first one); c) footnotes - they were not often met, little by little, and, in principle, knowing the format, they were added without much difficulty.

Some time ago, there was a converter from FB2 to PDF from KiR, in addition to being a wonderful tool for obtaining pdfs of good, almost publishing quality, it was an example of using the DocBook format, which I heard a lot about, but could not start and put all the necessary tools together.

DocBook, like FictionBook, is an XML-based format. And as for FictionBook, it’s not very convenient to edit it in its natural format, but, fortunately, there is such a utility as asciidoc , which allows you to create an appropriate document in a DocBook, html or other format from a text file with fairly simple markup.

Creating fb2 backend

As already mentioned, the current situation completely satisfied me: I do not read very often, and the process of preparing the book also brings me pleasure. But, when I wanted to transform not a fiction, but a popular science book with many illustrations and footnotes, the little difficulties b) and c) turned out to be quite significant. And the thought crept into my head to adapt asciidoc to the formation of books in the FictionBook format.



In a way, I succeeded. The resulting tool made it possible to issue the book “Why We Don't Fall Through the Floor” by James Gordon in just a day (not counting proofreading) with quite a lot of comfort and ease.

Positive qualities (IMHO):

1. Text file as a source: ease of reading, lack of unnecessary markup, compactness, familiarity;
2. Convenient addition of footnotes: the text of the footnotes is located at the place that he explains;
3. Convenient addition of images: the file name is indicated, and the addition of the appropriate sections to the fb2-file falls on the backend.

Negative qualities:

1. Asciidoc is designed to form a DobBook, which is richer in a set of tags: this, in particular, leads to the fact that sometimes asciidoc detects formatting that is not in FictionBook and creates the wrong fb2 file. In such situations, you need to know the asciidoc markup language and how to disable it;
2. There is no direct support for poetry and other lyrics: I was not able to make such a setting, I think it is possible, but they are not often found with me, and you can do it by direct insertion (see the attached example);
3. Images can only be in jpg and png formats : this is an arbitrary restriction and can be easily expanded;
4. Images should be in the same place as the source text: it was easier;
5. It is necessary to personally monitor that the sections are either with text or with other sections: DobBook does not have this limitation, and therefore there is no automatic control;
6. Links to parts of the text are not implemented: at this point, DocBook and FictionBook are similar, so if there is a need, this can easily be organized, but so far there has been no need;
7. The source text must be in utf-8 encoding;
8. The names of the images in the text and on the disk must match up to case.

Approximate scheme of the fb2-backend

The application was thrown “hastily”, as an auxiliary, to achieve the goal: the collection of one book - this implies all the inflexibility that is inherent in it.

The entire application is compiled as a set of simple scripts, united by the txt2fb2.bat batch file .

So what happens after calling txt2fb2.bat SourceFile.txt:

1. Asciidoc is called with the fb2 backend. Its result is something similar in structure to FictionBook 2, but requiring further refinement: adding images, removing footnotes at the end;
2. Image preparation in progress. A companion file with the extension .b64 is created for all jpg and png images (this is actually an element, which can be placed in the resulting fb2 file). It is at this stage that an arbitrary restriction arises on the formats of graphic files.
3. The finalization of FictionBook 2 is carried out by the xslt-script adjust_fb2.xsl . At this stage, the sections "Abstract" and "Document History" fall into the right places in the header. Footnotes are highlighted and placed at the end. Images from the files obtained in step 2 are added.

The resulting fb2 file must be checked with a validator.

Additional formatting

I recommend that you look at the asciidoc documentation to familiarize yourself with the valid markup, as well as take a look at the book that I am attaching as a sample.

For ease of conversion to fb2 format, some asciidoc markup extensions have been introduced, which I will describe here.

Document title

Many parameters are defined using the attributes of the document: An annotation is any text that is between the heading and the first section. The history of the document is described in a special section of the top level:
:genre:                 sf -- жанр

:firstname:             Имя автора книги

:middlename:            Отчество автора книги

:lastname:              Фамилия автора книги

:nickname:              Прозвище автора книги

:date:                  2009 -- дата издания книги

:lang:                  ru -- язык книги

:src-lang:              en -- язык оригинала

:coverpage-image:       Cover.png -- изображение обложки

:sequence-name:         Malazan Book of the Fallen -- Имя серии

:sequence-number:       6 -- номер в серии

:translator-firstname:  Иван -- имя переводчика

:translator-middlename: Иванович -- отчество переводчика

:translator-lastname:   Толмович -- фамилия переводчика

:document-firstname:    Stas -- имя создателя документа

:document-lastname:     Bushuev -- фамилия создателя документа

:document-nickname:     Xitsa -- прозвище создателя документа

:document-date:         2009-05-07 -- дата создания документа

:document-id:           Xitsa-7AD2-4B5F-92E5-892DEA3AE559 -- идентификатор документа

:document-version:      1.01 -- версия документа

:program-used:          FB Tools, sed, VIM, Far, asciidoc+fb2 backend -- использованные при создании документы программы






Document History
----------------


Footnotes

AsciiDoc supports two types of footnotes: footnote and footnoteref , for footnotes to be correctly generated using fb2-backend, only footnoteref is required and only with numbers (since it is used to form the footnote header, you could do the opposite by disabling footnoteref and organizing automatic footnote numbering, but I preferred to leave the possibility of re-linking).

Example: In asciidoc 8.4.5, for some reason, it was made so that the footnoteref macro before which there is no space and a significant character does not work, therefore, in the example I posted, asciidoc.conf is fixed and does not correspond to the original.
Основной текстfootnoteref:[3,"Текст сноски, обратите \"внимание\", что кавычки необходимо экранировать"]

Текст с повторной ссылкой на ту же сноскуfootnoteref:[3]


Additional macros

An additional author can be added using the author macro, unnecessary attributes can be omitted. For example: There is a subtitle tag in FictionBook , to which I did not find an analogue in DocBook, therefore I implemented it using a macro: Tag

author::[Семёнов,Сергей,Анатольевич,Nickname]
author::[Семёнов,Серёжа]




subtitle::[* * *]


if necessary, you can insert using the following macro, which should be a separate paragraph:

empty::[]


Quotes and Epigraphs

Both quotes and epigraphs are distinguished from the text by underlining. Attributes must either be in quotation marks together, or they must not contain commas.

Examples:
["quote","Автор цитаты","произведение"]
____________________________________________________________
Цитата с полной атрибутикой
____________________________________________________________

____________________________________________________________
Простое цитирование без лишних изысков
____________________________________________________________

[epigraph,А. С. Пушкин, Я помню...]
____________________________________________________________
++++++++++++++++++++++++++++++++++++++++


Я помню чудное мгновенье,

Передо мной явилась ты...



++++++++++++++++++++++++++++++++++++++++
Это пример того, как можно вставить стихи в текст.
____________________________________________________________


How to try

I have assembled a separate application that does not require installation, you can get it here

. You can immediately try to run txt2fb2.bat materials.txt - this is a demo book that uses most of the asciidoc fb2 extensions.

The doc directory contains asciidoc documentation that you would like to read.

Linux users can take this file and modify it with a file:

1. Install asciidoc 8.4.5 (and replace asciidoc.conf with mine (or take it from the trunk));
2. Set python binding to libxml, or use xsltproc directly;
3. Rewrite txt2fb2.bat in terms of the shell used.

Further development

The project is at the alpha stage and is laid out in the hope that someone else will be interested or useful. In this case, it will be possible to think about how to bring it in a decent form: with documentation, examples and modify it.