# FB2EPUB readme

## Description

This program suite is intended for conversion of from FB2 (Fiction Book 2) format files into EPUB format files

It consists of the

- Command line converter utility
- GUI Utility converter
- Windows shell extension
- Fiction Book Editor (FBE) export plugin
- COM interface to the converter for external programs

The program also optionally embed fonts with Cyrillic UNICODE support to allow reading resulting files on readers without Cyrillic support. But it can embed any font for any purpose

## Command line utility

### Description

This utility perform FB2 to ePub files conversion using command line "DOS" syntax

### Usage

The command line for the utility has following structure:

fb2epub <input_fb2_file_path> [-options]
or optional
fb2epub <input_fb2_file_name> <output_epub_file_name> [-options]
The input file can be either .FB2 file or RAR archive or ZIP archive containing FB2 files inside. In case archive containing more than one FB2 file all files in archive are converted. Also it is possible to specify path or/and mask to convert to convert entire folders

#### The currently valid options are:

-t:[0/1/2/3/4/5]
  where -t:0 (default) means no transliteration, while -t:1 applies transliteration to book title, authors names, chapters etc to improve the display on readers without Cyrillic support (Sony non-russified readers etc). -t:2 apply transliteration to output file name , -t:3 transliterate both output file name and book content, -t:4 (Kindle mode) transliterates book metadata without TOC, -t:5 transliterates book metadata and filename but not TOC
-o:<path>
  Set output path in case no output file name supplied.
-fix:[0/1/2/3]
  where -fix:0 means "do not attempt to fix", -fix:1 means "try to apply minimal internal corrections only", -fix:2 (default) means "use Fb2Fix to fix the files" - fixes most problems, -fix:3 instruct the system to use Fb2Fix on every file even if it does not contain errors
-f2i:[0/1]
  Enable (-f2i:1) or disable (-f2i:0) generation of additional FB2 information page
-seqadd:[0/1]
  Enable (-secadd:1) (default) or disable (-secadd:0) adding sequences abbreviations to book title name
-seqformat:[format_string]
  - Format book title description info (thanks wserg) , This allows to define what will be displayed on book description page. The following format options are allowed:
  %bt% - BookTitle from FB2 header
  %sf% - Series full name from FB2 header
  %sa% - Series abbviarated name from FB2 header
  %sn% - book number in the series
  Also following modifiers specified after '.' (dot) are allowed for %bt%, %sf% and %sa%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  additionally for parameter %sn% numeric modifier can be used to specify 0-prefix of the number
  The default format is same as in prev versions: "%bt% %sa.l%-%sn%"
  Examples:
  Series: Star Wars
  %sf.u% - STAR WARS
  Number: 1
  %sn.3% - 001
  do not forget to double quote the format string if it contain spaces
-nseqformat:[format_string]
  - Format book title description info (thanks wserg) , This allows to define what will be displayed on book description page if book is not part of the sequence (no seq. number). The following format options are allowed:
  %bt% - BookTitle from FB2 header
  %sf% - Series full name from FB2 header
  %sa% - Series abbviarated name from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %bt%, %sf% and %sa%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  The default format is : "%bt% (%sf.l%)"
  Examples:
  Serie: Star Wars
  %sf.u% - STAR WARS
  do not forget to double quote the format string if it contain spaces
-nnseqformat:[format_string]
  - Format book title description info (thanks wserg) , This allows to define what will be displayed on book description page if book has no series name defined. The following format options are allowed:
  %bt% - BookTitle from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %bt%, %sf% and %sa%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  The default format is : "%bt%"
  do not forget to double quote the format string if it contain spaces
-aformat:[format_string]
  - Format author name , This allows to define what will be displayed on book description page. The following format options are allowed:
  %f% - First name from FB2 header
  %m% - Middle name from FB2 header
  %l% - last name from FB2 header
  %n% - Nick name from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %f%, %m%, %l% and %n%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  additionally another subformat :b can be added to take name in brackets
  The default format is : "%f.c%%m.c%%l.c%%n.c:b%"
-svformat:[format_string]
  - Format "File As" author name , This allows to define what will be displayed on book description page. The following format options are allowed:
  %f% - First name from FB2 header
  %m% - Middle name from FB2 header
  %l% - last name from FB2 header
  %n% - Nick name from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %f%, %m%, %l% and %n%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  additionally another subformat :b can be added to take name in brackets
  The default format is : "%l.c%f.c"
-s
  Enable search for files in subfolders in case path or mask specified
-m:[0/1/2/3]
  Search for *.fb2 files only(-m:0) or all .fb2 files and *.fb2.zip/*.fb2.rar files(-m:1 - default) or
  for all *.fb2;*.zip;*.rar files (-m:2) or just all files *.* (-m:3)when looking for files in folder(s).
  Providing search mask in input string override this parameter.
  Specifying file mask in input parameter overrides this option.
-DELETESOURCE
  Deletes the source FictionBook file upon successful conversion
-flat:[0/1]
  Invokes (1) "flat structure mode" that prohibits creation of subfolders inside ePub archive, workaround for some buggy readers. -flat:0 - default
-emstyles:[0/1]
  - Invokes "embeding styles mode" that, instead of adding CCS files to the ePub and referencing them, in xHTML injects the relevant style code directly into the xHTML files. Values are: 0 - disabled (default) , 1 - enabled. The feature is for buggy readers that do not support reading styles from referenced files -flat:0 - default
-apng:[0/1]
  Enable/disable conversion of PNG files with palette that contain alpha channel into 32bit format. Many readers (especially Adobe based)can't show paletterized alpha channel PNGs. The possible values are 0 (disable) and -apng:1 - default
-cap:[0/1]
  Enable (1) /disable (0)"capitalization" of section first character making it big and appear on several lines.-cap:1 - default
-xpgt:[0/1]
  Enable (1) or disable (0, default) embedding of Adobe XPGT template into resulting ePub File. -xpgt:0 - default
-xpgtPath:[file_path]
  Forces converter to use Adobe XPGT template file specified by this parameter instead of default XPGT template "template.xpgt" located in "Template" subfolder
-settings
  Calling with this parameter (should be the only parameter) will bring up settings configuration window UI to ease setting up the defaults
-ignoretitle:[0/1/2/3/4/5/6]
  Controls if one or more FB2 titles should be ignored, -ignoretitle:0 - default Possible options are
  - 0 - nothing ignored
  - 1 - Main FB2 title ignored
  - 2 - Source info title ignored
  - 3 - Publish info title ignored
  - 4 - Main and Source info titles are ignored
  - 5 - Main and Publish info titles are ignored
  - 6 - Source and Publish info titles are ignored
-cfg:<path>
  Allows to specify different settings file path to use for conversion
-calibremeta:[0/1]
  Enable/Disable Calibre metadata injection into output file, used by some programs to sort, display series etc. Default: 1(Enabled)
-log:file_path
  Redirect logger to a new file or path (can be either, in case of path uses "fb2epub.log" file name)

## GUI Utility

### Description

This utility provides Windows style User Interface for the Fb2 to ePub file conversion. Files can be either "dragged" into it by mouse or selected by browsing to file. The resulting ePub file(s) will be placed into the user selected output folder

The utility can be used with English language UI and also has Russian language localization

## Windows shell extension

### Description

The converter provides and register a Windows Shell Extension mechanism that allow to perform conversion of FB2 files or archives containing FB2 files in Windows Explorer

### Usage

The conversion into ePub performed by mouse right-clicking on the source file in Windows Explorer and selecting conversion from the context menu. Conversion output can be generated in same folder ("Here" option) or (if configured by FB2EPUBExt.INI) into some preconfigured path.

## Fiction Book Editor (FBE) export plugin

### Description

This plugin (in case FBE installed on the computer) allows exporting edited FB2 files directly into ePub file format

### Usage

From "File" menu select "Export" , then "toEPUB"

## COM interface to the converter for external programs

### Description

We provide COM interface in order to allow external programs to be able to use (call) converter functionality

### Usage

The IEPubConverterInterface interface (GUID 9B6D89BC-0C32-46E0-B06C-360DA401FE9A) declare following functions

- HRESULT ConvertPath(BSTR inputPath, BSTR outputFolder, IProgressUpdateInterface progress) - convert files in path into output folder
- HRESULT ConvertList(SAFEARRAY* files, BSTR outputFolder, IProgressUpdateInterface progress) - convert list of files to output folder
- HRESULT ConvertXml(IUnknown * doc, BSTR outFileName, IProgressUpdateInterface progress) convert IXHTMLDocument into file name
- HRESULT ConvertSingleFile(BSTR inputPath, BSTR outputName, IProgressUpdateInterface progress) - convert single file provided to the output name
- HRESULT AbortConversion() - aborts conversion in progress

The IProgressUpdateInterface pointer used there (interface GUID 255293F1-ECB5-4218-8797-1068B915BEC5) can be NULL, otherwise it should be an object implementing this interface and containing following functions:

- HRESULT ConvertStarted (/*[in]*/ long total )
- HRESULT ConvertFinished (/*[in]*/ long total )
- HRESULT ProcessingStarted (/*[in]*/ BSTR fileName )
- HRESULT ProcessingSaving (/*[in]*/ BSTR fileName )
- HRESULT Processed (/*[in]*/ BSTR fileName )
- HRESULT SkippedDueError (/*[in]*/ BSTR fileName )
- HRESULT ShowSettingsDialog (/*[in] , can be 0*/ HWND parent,/*[out,retval]*/ VARIANT_BOOL * pRetVal )

The converter object itself can be created using GUID 0FF011AD-18A5-4CF2-8AB1-011AA9AA2BDF.

## Fonts:

The program currently uses only two fonts located in FONTS subfolder: LiberationSerif-Regular.ttf for normal text and LiberationSerif-Italic.ttf for italic (emphasized) text. You can replace them by any font file (keeping the name) and this fonts will be used in resulting EPUB.
Or, alternatively, you can edit the Fb2ePub.exe.config file to change any font used.

## CSS styles:

EPUB books use CSS styles to change the way book presented to the reader. The default default.css located in CSS subfolder is embeded in every EPUB file produced. By changing this file before conversion you can affect the way resulting book will be displayed. See styles_??.txt files in CSS subfolder for more details on elements specific for FB2EPUB conversion. See http://www.w3schools.com/Css/default.asp for detailed tutorial on CSS standard.

## Transliteration:

The transliterating conversion mapping of the items that displayed without using embedded fonts (book title, authors, chapter navigation points, etc) can be customized. To customize transliteration open the translit.xml file and change (or add) mapping.
Each <map> element has two required attributes: "in" - Russian character on input, and "out" - string to substitute in character with. You can modify either one of them or both. The supplied translit.xsd file provides tool to validate resulting file in case needed,

## Configuration defaults ( defsettings.xml ):

Some default setting used by converter are stored in defsettings.xml file.

### Currently user can change following settings:

TransliterateBook
  - enable/disable transliteration of metadata by default, values: "False" (Default), "True"
TransliterateTOC
  - enable/disable transliteration of TOC if transliteration of metadata enabled by default, values: "False", "True" (Default)
TransliterateFileName
  - enable/disable transliteration of output file name by default, values: "False" (Default), "True"
AddFB2Info
  - Enable/disable generation of additional FB2 info page at the end of the resulting EPUB. Values are: "True" (default) and "False"
AddSequenceNameToTitle
  - Enable/disable addition of abbreviated sequence names to the book title name Values are: "True" (default) and "False"
FormatWithSequenceName
  - Format book title description info (thanks wserg) , This allows to define what will be displayed on book description page. The following format options are allowed:
  %bt% - BookTitle from FB2 header
  %sf% - Serie full name from FB2 header
  %sa% - Serie abbviarated name from FB2 header
  %sn% - book number in the series
  Also following modifiers specified after '.' (dot) are allowed for %bt%, $sf% and %sa%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  additionally for parameter %sn% numeric modifier can be used to specify 0-prefix of the number
  The default format is same as in prev versions: "%bt% %sa.l%-%sn%"
  Examples:
  Serie: Star Wars
  %sf.u% - STAR WARS
  Number: 1
  %sn.3% - 001
FormatWithOutSequenceName
  - Format book title description info (thanks wserg) , This allows to define what will be displayed on book description page if book is part of series but does not have series number. The following format options are allowed:
  %bt% - BookTitle from FB2 header
  %sf% - Series full name from FB2 header
  %sa% - Series abbviarated name from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %bt%, $sf% and %sa%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  The default format is: "%bt% (%sf.l%)"
  Examples:
  Series: Star Wars
  %sf.u% - STAR WARS
FormatWithOutSeriesName
  - Format book title description info (thanks wserg) , This allows to define what will be displayed on book description page if book is not part of series. The following format options are allowed:
  %bt% - BookTitle from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %bt%, $sf% and %sa%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  The default format is: "%bt%"
AuthorNameFormat
  - Format author name , This allows to define what will be displayed on book description page. The following format options are allowed:
  %f% - First name from FB2 header
  %m% - Middle name from FB2 header
  %l% - last name from FB2 header
  %n% - Nick name from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %f%, %m%, %l% and %n%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  additionally another sub format :b can be added to take name in brackets
  The default format is : "%f.c%%m.c%%l.c%%n.c:b%"
FileAsFormat
  - Format "File As" author name , This allows to define what will be displayed on book description page. The following format options are allowed:
  %f% - First name from FB2 header
  %m% - Middle name from FB2 header
  %l% - last name from FB2 header
  %n% - Nick name from FB2 header
  Also following modifiers specified after '.' (dot) are allowed for %f%, %m%, %l% and %n%:
  c - Capitalize, l - lowercase, u -UPPERCASE
  additionally another sub format :b can be added to take name in brackets
  The default format is : "%l.c%f.c"
Fb2FixMode
  - Controls invoking of Fb2Fix to fix input files Values are: "0" - never try to fix , "1" - try to fix using internal algorithms only , "2" (default) - if internal algorithms fail try to apply FB2Fix, "3" - allways apply FB2Fix
ConvertAlphaPNG
  - Controls conversion of palatalized PNG files with alpha channel to 32 bit files. Many readers (especially Adobe based)can't show palatalized alpha channel PNGs. Values are: "False" - do not convert , "True" - always convert (default)
FlatStructure
  - Invokes "flat structure mode" that prohibits creation of subfolders inside ePub archive, workaround for some buggy. Values are: "False" - disabled (default) , "True" - enabled
EmbedStyles
  - Invokes "embedding styles mode" that, instead of adding CCS files to the ePub and referencing them, in xHTML injects the relevant style code directly into the xHTML files. Values are: "False" - disabled (default) , "True" - enabled. The feature is for buggy readers that do not support reading styles from referenced files
GenerateDropCharacters
  - Invokes "capitalization" of section first (drop) character making it appear big and take several lines. Values are: "False" - disabled , "True" - enabled (default).
EnableAdobeTemplateUsage
  - Controls if Adobe XPGT template is to be added to the resulting ePub file. Values: "True" and "False" (default). Please see http://wiki.mobileread.com/wiki/XPGT for details on XPGT templates.
AdobeTemplatePath
  - Specifies non-default path to the XPGT template to use in case enabled (in case of empty - default""Template" folder "template.xpgt" file used.
IgnoreTitleOption
  - Controls if one or more FB2 titles should be ignored when generating ePub. Values: "IgnoreNothing"(default) , "IgnoreMainTitle" , "IgnoreSourceTitle", "IgnorePublishTitle", "IgnoreMainAndSource", "IgnoreMainAndPublish" , "IgnoreSourceAndPublish" .
  Enable/Disable Calibre metadata injection into output file, used by some programs to sort, display series etc. Default: "true"(Enabled)
DecorateFontNames
  -Controls if font names should be "decorated" using random characters to work around font cacke bug present on some Adobe based readers. Values: "true"(default) , "false"
Fonts
  Fonts settings section , see format bellow

### Fonts settings

Fonts section can be empty, this means no fonts are to be embedded and device internal fonts will be used always

#### Format of the Fonts Section:

FontFamilies - list of the fonts families to embed CSSElements - list of the CSS/XHTML elements to assign fonts families to

##### Format of the FontFamilies section

Each FontFamilies section can contain up to several FontFamily elements. that in turn consist of Font sections listing specific fonts with their properties and sources (locations)

Each font can have following styles(attributes):

- style
- variant
- width
- stretch
- format

Each Font can also contain several Source elements defining font location with attributes:

- type
- format

and Location defining path to the font file

## Installation

1. Unpack into any location on your hard drive

2. Make sure that you have .Net 4.0 installed

3. If you wish to register right mouse click shell extension please either execute FB2EPUB /R from that folder or run RegisterFB2EPub.EXE. Please note that you have to be administrator or have admenistrative access on your computer to register right click shell extension.

## Upgrading from previous version

1. Unregister previously registered shell extension using either FB2EPUB /U from that folder or running RegisterFB2EPub.EXE and selecting unregistration option (Please note that you have to be administrator or have admenistrative access on your computer to unregister right click shell extension.)

2. Reboot your computer

3. Unpack new version either into a new folder (in this case you can delete old one) or overwriting into an old folder

4. If you wish to register right mouse click shell extension please either execute FB2EPUB /R from that folder or run RegisterFB2EPub.EXE. Please note that you have to be administrator or have admenistrative access on your computer to register right click shell extension.