FB2 Backend to AsciiDoc

Prehistory

I initially had a complex relationship with the FictionBook 2 format: at first I did not recognize it, then I allowed 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, none of them suited me, and for ordinary works of art it was easier and faster for me to do it in my usual text editor (jEdit or VIM).
')
Small difficulties for me were: a) document description - this was solved by using a template; b) images - it was usually a cover and could be added using FB Editor (first); c) footnotes - they met infrequently, little by little, and, in principle, knowing the format, they were added without any particular difficulty.

Some time ago, a converter from FB2 to PDF from KiR appeared, besides being a great tool for getting pdf of good, almost publishing quality, it was an example of using the DocBook format, which I heard a lot about, but could not start Collect all the necessary tools together.

DocBook, like FictionBook, is an XML-based format. And as for FictionBook, it is not very convenient to edit in its natural format, but, fortunately, there is a utility such as asciidoc , which allows you to create a corresponding DocBook, html or other document 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 a non-fiction, but a popular science book with a lot of illustrations and footnotes, some difficulties (b) and c) were 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 managed it. The resulting tool allowed us to draw up the book "Why we do not fall through the floor" by James Gordon in just a day (not counting proofreading) with a sufficiently large comfort and ease.

Positive qualities (IMHO):

1. Text file as a source: ease of reading, no markup, compactness, familiarity;
2. Convenient addition of footnotes: the text of the footnotes is at the place which he explains;
3. Convenient addition of images: the file name is indicated, and the addition of the corresponding sections in the fb2 file rests on the backend.

Negative qualities:

1. Asciidoc is intended to form a DobBook, which is richer in terms of a set of tags: this, in particular, leads to the fact that asciidoc sometimes detects formatting that is not in FictionBook and creates an incorrect fb2 file. In such situations, it is necessary to know the asciidoc markup language and how to disable it;
2. There is no direct support for poems and other lyrics: I did not manage to make such a setting, I think it is possible, but they are not often met with me, and you can get by with a direct insertion (see the attached example);
3. Images can only be 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 this way;
5. You need to personally make sure that the sections are either with text or with other sections: DobBook does not have this restriction, and therefore there is no automatic control;
6. References to parts of the text are not implemented: in this place DocBook and FictionBook are similar, so if there is a need, it can be easily organized, but so far there is no need;
7. The source text must be utf-8 encoded;
8. The names of the images in the text and on the disk must match up to the register.

Approximate scheme of fb2-backend

The application was scammed "hastily" as an auxiliary, to achieve the goal: a set of one book - from this follows all the inflexibility that is inherent in it.

The entire application is assembled as a set of simple scripts combined by the txt2fb2.bat command file.

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

1. Called asciidoc with fb2 backend. Its result is something similar in structure to FictionBook 2, but requiring further refinement: adding images, bringing footnotes to the end;
2. There is a preparation of images. For all images in jpg and png formats, a companion file with the .b64 extension is created (this is actually the <binary> element that can be placed in the resulting fb2 file). It is at this stage that an arbitrary restriction on graphic file formats arises.
3. FictionBook 2 is debugged with the xslt-script adjust_fb2.xsl . At this stage, the “Abstract” and “Document History” sections fall into the right places of the title. Footnotes are highlighted and taken to 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 reviewing the documentation on asciidoc to familiarize yourself with the permissible markup, and also to look at the book that I attach as a sample.

For convenience of converting to the fb2 format, some asciidoc markup extensions have been introduced, which I will describe here.

Document title

Many parameters are defined using document attributes:
:genre: sf -- <br>
:firstname: <br>
:middlename: <br>
:lastname: <br>
:nickname: <br>
:date: 2009 -- <br>
:lang: ru -- <br>
:src-lang: en -- <br>
:coverpage-image: Cover.png -- <br>
:sequence-name: Malazan Book of the Fallen -- <br>
:sequence-number: 6 -- <br>
:translator-firstname: -- <br>
:translator-middlename: -- <br>
:translator-lastname: -- <br>
:document-firstname: Stas -- <br>
:document-lastname: Bushuev -- <br>
:document-nickname: Xitsa -- <br>
:document-date: 2009-05-07 -- <br>
:document-id: Xitsa-7AD2-4B5F-92E5-892DEA3AE559 -- <br>
:document-version: 1.01 -- <br>
:program-used: FB Tools, sed, VIM, Far, asciidoc+fb2 backend -- <br>


An annotation is any text that is between the title and the first section.

Document history is described in the special section of the upper level:
Document History
----------------


Footnotes

AsciiDoc supports two types of footnotes: footnote and footnoteref , for correct formation of footnotes using fb2-backend, you only need to use footnoteref and only with numbers footnote numbering, but I chose to leave the possibility of repeated reference).

Example:
footnoteref:[3," , \"\", "]

footnoteref:[3]


In asciidoc 8.4.5 for some reason they made it so that the footnoteref macro in front of which is not a space, but a significant character does not work, therefore in the example I posted, asciidoc.conf is fixed and does not match the original.

Additional macros

An additional author can be added using the macro macro author, unnecessary attributes can be omitted. For example:

author::[,,,Nickname]
author::[,]


In FictionBook there is a subtitle tag, which I did not find a counterpart in DocBook, so I implemented it using a macro:

subtitle::[* * *]


The <empty-line /> tag can be inserted, if necessary, using the following macro, which should be a separate paragraph:

empty::[]


Quotes and epigraphs

Both quotes and epigraphs are distinguished from the text with underscores. Attributes must either be in quotes or must not contain commas.

Examples:
["quote"," ",""]
____________________________________________________________

____________________________________________________________

____________________________________________________________

____________________________________________________________

[epigraph,. . , ...]
____________________________________________________________
++++++++++++++++++++++++++++++++++++++++
<poem><stanza><br>
<v> ,</v><br>
<v> ...</v><br>
</stanza></poem><br>
++++++++++++++++++++++++++++++++++++++++
, .
____________________________________________________________


How to try

I have built a separate application that does not require installation, you can take it here.

Immediately you can try running txt2fb2.bat materials.txt - this is a demo book that uses most of the asciidoc fb2 extensions.

In the doc directory is the documentation for asciidoc, which is desirable 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 the 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 into a decent look: with documentation, examples and refine.