CustomOutput - JimmXinu/FanFicFare GitHub Wiki
For most users, the default output of FanFicFare is sufficient. Some users, however, want or need to change the output to suit their needs. This document describes all the ways the output can customized.
The option content shown in this document reflects the default values used the FanFicFare at the time of writing.
Each format (EPUB, MOBI, HTML AND TXT), has a different set of customizable parameters; although some are common to some or all formats.
To emphasize the appropriate section and avoid possible confusion
between similar sections, each config example block will include a
section header (eg, [epub]), but you only need one for each section
in practice.
When using multiple lines in one INI config parameter, make sure to keep at least one space at the start of each line. That's how INI indicated continuation. Also, INI uses % to indicate it's own internal substitutions, you'll need to escape % characters to %% to include them.
Config options that mention that 'metadata' is available refer to all the same entries that can appear in titlepage_entries.
As for all format-specific options, these options must appear in the
[epub] section of your personal.ini.
An EPUB is a specially constructed zip file containing (X)HTML, CSS and, optionally, image files. EPUB is the recommended output format for all users--if you use a Kindle or other device that needs another format, downloading to EPUB and then converting using Calibre is the suggested path.
Each EPUB (X)HTML file generated by FanFicFare will (by default) included a style sheet named stylesheet.css that FanFicFare will generate. You can control what stylesheet.css contains:
Unlike other output customization options, output_css does not have access to any of the story metadata.
[epub]
## output background color--only used by html and epub (and ignored in
## epub by many readers). Included below in output_css--will be
## ignored if not in output_css.
background_color: ffffff
## Allow customization of CSS. Make sure to keep at least one space
## at the start of each line and to escape % to %%. Also need
## background_color to be in the same section, if included in CSS.
## 'adobe-text-layout: optimizeSpeed;' prevents hyphenation on newer Nooks
## Only ini substs, like background_color are done.
output_css:
body { background-color: #%(background_color)s;
text-align: justify;
margin: 2%%;
adobe-text-layout: optimizeSpeed; }
pre { font-size: x-small; }
sml { font-size: small; }
h1 { text-align: center; }
h2 { text-align: center; }
h3 { text-align: center; }
h4 { text-align: center; }
h5 { text-align: center; }
h6 { text-align: center; }
.CI {
text-align:center;
margin-top:0px;
margin-bottom:0px;
padding:0px;
}
.center {text-align: center;}
.cover {text-align: center;}
.full {width: 100%%; }
.quarter {width: 25%%; }
.smcap {font-variant: small-caps;}
.u {text-decoration: underline;}
.bold {font-weight: bold;}
In addition to the story title and author, and links to the story and author URLs, the title page typically contains a collection of metadata about the story. By default, this page includes series, category, genre, language, characters, etc, etc. (See titlepage_entries in defaults.ini for more information about what can be included. This document is about how it is included.)
There are five options for the title page--the HTML that appears at
the beginning (titlepage_start) of the file, at the end of the file
(titlepage_end), and three variations that are used to display each
metadata entry value.
titlepage_entry is the typical entry value formatting.
titlepage_wide_entry can be used to provide an alternative
formatting for wider entries--useful if you've elected to use tables
to format entries.
titlepage_no_title_entry can be used to provide an alternative
formatting for entries with empty labels--useful if you've elected to
not have a visible label for description, for example.
[epub]
## metadata ${title}, etc. Make sure to keep at least one space
## at the start of each line and to escape % to %%.
titlepage_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>${title} by ${author}</title>
<link href="stylesheet.css" type="text/css" charset="UTF-8" rel="stylesheet"/>
</head>
<body class="fff_titlepage">
<h3><a href="${storyUrl}">${title}</a> by ${authorHTML}</h3>
<div>
## ${id}, ${label}, ${value}
titlepage_entry:<b>${label}:</b> ${value}<br />
## ${id}, ${label}, ${value}
## Used with entries listed in wide_titlepage_entries, typically description, storyUrl, authorUrl
titlepage_wide_entry:
## When using tables, make these span both columns.
wide_titlepage_entries: description, storyUrl, author URL
## ${id}, ${value}
## For example, if you've set description_label:
## (that is, nothing)
titlepage_no_title_entry:${value}<br />
## metadata
titlepage_end:
</div>
</body>
</html>
An explicit Table of Contents page is not typically included in EPUB,
since EPUB has that information embedded in it. But you can choose to
include one with include_tocpage: true. If you choose to, you can
configure the start and end html as well as each TOC entry.
tocpage_entry has three values passed to it, number (the chapter
number), chapter (the chapter name), and index04, (the chapter number
padded with 0's to four digits). That's the way each chapter file is
named.
[epub]
## metadata
tocpage_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>${title} by ${author}</title>
<link href="stylesheet.css" type="text/css" charset="UTF-8" rel="stylesheet"/>
</head>
<body class="fff_tocpage">
<div>
<h3>Table of Contents</h3>
## ${number}, ${index04}("%04d"%${number}), ${chapter}
tocpage_entry:<a href="file${index04}.xhtml">${chapter}</a><br />
## metadata
tocpage_end:
</div>
</body>
</html>
Since EPUBs can be updated, I find it useful to keep a log of what
metadata changed in each update. This can be turned on with
include_logpage: true or include_logpage: smart to only include a
log when the story is 'In-progress' or already has a log.
Similar to title and toc pages, there are start and end parameters--but they are only used when a new log page is created, typically when a new story is first downloaded or when story is overwritten instead of updated.
Each update consists of logpage_update_start and
logpage_update_end with one or more logpage_entrys depending on
what metadata you have listed in logpage_entries and what's changed.
[epub]
# metadata - only used when creating a new logpage from scratch
logpage_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Update Log</title>
<link href="stylesheet.css" type="text/css" charset="UTF-8" rel="stylesheet"/>
</head>
<body class="fff_logpage">
<h3>Update Log</h3>
# metadata
logpage_update_start:<p class='log_entry'>
# ${id}, ${label}, ${value}
# Must contain <span id="${id}">${value}</span> for
# log updates to work correctly.
logpage_entry:<b>${label}:</b> <span id="${id}">${value}</span>
# metadata
logpage_update_end:</p><hr />
# metadata - only used when creating a new logpage from scratch
# Must contain </body> for log updates to work correctly.
logpage_end:
</body>
</html>
The text for each chapter in the story is stored in EPUB as its own
XHTML file, so the chapter_start and chapter_end contain a full
XHTML file header and trailer.
The chapter HTML from the source site, with some processing for
consistency, is injected between the chapter_start and chapter_end
header and trailer.
Three values are passed to each, number (the chapter number),
chapter (the chapter name), and index04, (the chapter number padded
with 0's to four digits). That's the way each chapter file/section is
named.
When an epub chapter is read back in during update, everything outside
the <body> tag is discarded, as well as the first <h3>, the first
<h2> tag (for historical reasons), and any tag with class
skip_on_ffdl_update. That way you can include additional items in
chapter_start inside the <body> tag that will be replaced each
update. This is useful for sites that have additional chapter info,
like chapter word counts or chapter dates.
[epub]
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>${chapter}</title>
<link href="stylesheet.css" type="text/css" charset="UTF-8" rel="stylesheet"/>
<meta name="chapterurl" content="${url}"></meta>
<meta name="chapterorigtitle" content="${origchapter}"></meta>
<meta name="chaptertoctitle" content="${tocchapter}"></meta>
<meta name="chaptertitle" content="${chapter}"></meta>
</head>
<body class="fff_chapter">
<h3 class="fff_chapter_title">${chapter}</h3>
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_end:
</body>
</html>
While EPUB is an open and (theoretically) well defined format, what each eReader will accept for the embedded cover is rather restricted.
You can customize what FanFicFare will output for cover_content, but
I don't recommended it. You never know what will cause your eReader
to stop working with the cover.
[epub]
## metadata(title,etc) plus ${coverimg} for the cover image href.
cover_content:
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"><head><title>Cover</title><style type="text/css" title="override_css">
@page {padding: 0pt; margin:0pt}
body { text-align: center; padding:0pt; margin: 0pt; }
div { margin: 0pt; padding: 0pt; }
</style></head><body class="fff_coverpage"><div>
<img src="${coverimg}" alt="cover"/>
</div></body></html>
As for all format-specific options, these options must appear in the
[mobi] section of your personal.ini.
MOBI file format is not a published standard format. What we know about MOBI has been reverse engineered from MOBI files. The MOBI output is generated by a somewhat elderly library packaged with FanFicFare.
FanFicFare continues to generate MOBI output as a legacy feature, but there are currently no plans to update or improve FanFicFare's MOBI output. Kindle has moved on to AZW3 format.
Due to limitations in the MOBI library FanFicFare uses, neither CSS nor images are supported. I suggest you generate EPUBs and then use calibre to convert to MOBI--you'll get better MOBI files that way.
In addition to the story title and author, and links to the story and author URLs, the title page typically contains a collection of metadata about the story. By default, this page includes series, category, genre, language, characters, etc, etc. See titlepage_entries in defaults.ini for more information about what can be included. This document is about how it is included.
Config options that mention that 'metadata' is available refer to all the same entries that can appear in titlepage_entries.
There are five options for the title page--the HTML that appears at
the beginning (titlepage_start) of the file, at the end of the file
(titlepage_end), and three variations that are used to display each
metadata entry value.
titlepage_entry is the typical entry value formatting.
titlepage_wide_entry can be used to provide an alternative
formatting for wider entries--useful if you've elected to use tables
to format entries.
titlepage_no_title_entry can be used to provide an alternative
formatting for entries with empty labels--useful if you've elected to
not have a visible label for description, for example.
[mobi]
# metadata ${title}, etc.
titlepage_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>${title} by ${author}</title>
</head>
<body>
<h3><a href="${storyUrl}">${title}</a> by ${authorHTML}</h3>
<div>
# ${id}, ${label}, ${value}
titlepage_entry:
<b>${label}:</b> ${value}<br />
# ${id}, ${label}, ${value}
# Used with entries listed in wide_titlepage_entries, typically description, storyUrl, authorUrl
titlepage_wide_entry:
# ${id}, ${value}
# For example, if you've set description_label:
# (that is, nothing)
titlepage_no_title_entry:
${value}<br />
# metadata
titlepage_end:
</div>
</body>
</html>
The Table of Contents Page is not customizable in MOBI format output.
The MOBI file format uses an HTML TOC in the file as the document TOC. The MOBI conversion library FanFicFare uses places it towards the beginning. Other MOBI generators, including Amazon purchased books and Calibre Convert, typically include at the end of the ebook.
Because it is also (sorta) metadata, it's always included and generated by the MOBI conversion library, not FanFicFare directly.
The text for each chapter in the story is generated for MOBI as its
own HTML file, so the chapter_start and chapter_end contain a full
HTML file header and trailer. (However, the generation process, due
to the nature of the MOBI format, combines all of the chapters into
one 'file'.)
The chapter HTML from the source site, with some processing for
consistency and MOBI limitations, is injected between the
chapter_start and chapter_end header and trailer.
Three values are passed to each, number (the chapter number),
chapter (the chapter name), and index04, (the chapter number padded
with 0's to four digits). That's the way each chapter file/section is
named.
[mobi]
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>${chapter}</title>
</head>
<body>
<h3>${chapter}</h3>
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_end:
</body>
</html>
As for all format-specific options, these options must appear in the
[html] section of your personal.ini.
FanFicFare's html output places the entire story in one HTML file.
Because the html output is just one file, the CSS is included in it directly instead of in a separate file.
Unlike other output customization options, output_css does not have access to any of the story metadata.
[html]
## output background color--only used by html and epub (and ignored in
## epub by many readers). Included below in output_css--will be
## ignored if not in output_css.
background_color: ffffff
## Allow customization of CSS. Make sure to keep at least one space
## at the start of each line and to escape % to %%. Also need
## background_color to be in the same section, if included in CSS.
## Only ini substs, like background_color are done.
output_css:
body { background-color: #%(background_color)s; }
.CI {
text-align:center;
margin-top:0px;
margin-bottom:0px;
padding:0px;
}
.center {text-align: center;}
.cover {text-align: center;}
.full {width: 100%%; }
.quarter {width: 25%%; }
.smcap {font-variant: small-caps;}
.u {text-decoration: underline;}
.bold {font-weight: bold;}
You can customize what will appear at the beginning and end of the HTML file.
[html]
# metadata
file_start:<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>${title} by ${author}</title>
<style type="text/css">
${output_css}
</style>
</head>
<body>
<h1><a href="${storyUrl}">${title}</a> by ${authorHTML}</h1>
# metadata
file_end:
</body>
</html>
In html format, the title 'page' is just another section of HTML, but the name is kept for consistency.
In addition to the story title and author, and links to the story and author URLs, the title page typically contains a collection of metadata about the story. By default, this page includes series, category, genre, language, characters, etc, etc. (See titlepage_entries in defaults.ini for more information about what can be included. This document is about how it is included.)
There are five options for the title page--the HTML that appears at
the beginning (titlepage_start) of the title page HTML block, at the
end of the block (titlepage_end), and three variations that are used
to display each metadata entry value.
titlepage_entry is the typical entry value formatting.
titlepage_wide_entry can be used to provide an alternative
formatting for wider entries--useful if you've elected to use tables
to format entries.
titlepage_no_title_entry can be used to provide an alternative
formatting for entries with empty labels--useful if you've elected to
not have a visible label for description, for example.
[html]
# metadata ${title}, etc.
titlepage_start:<table class="full">
# ${id}, ${label}, ${value}
titlepage_entry:
<tr><td><b>${label}:</b></td><td>${value}</td></tr>
# ${id}, ${label}, ${value}
# Used with entries listed in wide_titlepage_entries, typically description, storyUrl, authorUrl
titlepage_wide_entry:
<tr><td colspan="2"><b>${label}:</b>{$value}</td></tr>
# ${id}, ${value}
# For example, if you've set description_label:
# (that is, nothing)
titlepage_no_title_entry:
<tr><td colspan="2"><b>${value}</td></tr>
# metadata
titlepage_end:
</table>
An explicit Table of Contents page is typically included in html. You can configure the start and end HTML as well as each TOC entry.
tocpage_entry has three values passed to it, number, the chapter
number, chapter, the chapter name, and index04, the chapter number
padded with 0's to four digits. That's the way each chapter file is
named.
[html]
# metadata
tocpage_start:
<a name="TOCTOP"><h2>Table of Contents</h2>
<p>
# ${number}, ${index04}("%04d"%${number}), ${chapter}
tocpage_entry:
<a href="#section${index04}">${chapter}</a><br />
# metadata
tocpage_end:
</p>
The text for each chapter in the story is included immediately after
the previous, so the chapter_start and chapter_end typically
contain an anchor for the TOC link, the chapter title and some
spacing.
The chapter HTML from the source site, with some processing for
consistency, is injected between the chapter_start and chapter_end
header and trailer.
Three values are passed to each, number (the chapter number),
chapter (the chapter name), and index04, (the chapter number padded
with 0's to four digits). That's the way each chapter file/section is
named.
[html]
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_start:
<a name="section${index04}"><h2>${chapter}</h2></a>
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_end:
You can customize what FanFicFare will output for cover_content for
HTML. FanFicFare will place this code immediately after the contents
of file_start but only when a cover image was found for the story.
[html]
## metadata(title,etc) plus ${coverimg} for the cover image href.
cover_content:
<img src="${coverimg}" alt="cover"/>
As for all format-specific options, these options must appear in the
[txt] section of your personal.ini.
While the simpliest output, plain text output is actually one of the hardest do use customized output with due to the INI file format tending to remove the whitespace we want to include to provide formatting.
First, you can choose how wide the text output should be before line wrapping as well as choose Windows/DOS end-of-line(eol) convention(CR-LF) vs Unix/Mac(LF).
[txt]
## 0 means no word wrap
wrap_width:0
windows_eol:true
The only way I've found to include newlines in customized text output
is define a newline parameter and include it in other parameters as
%(newline)s.
[txt]
# make sure to keep a single space on the line after this--it's
# one, empty newline for inclusion below.
newline:
# You can't see it, but there's a space on the line above.
Because txt format is all one file, you can customize what will appear at the beginning and end of the file.
[txt]
# metadata
file_start:
%(newline)s
%(newline)s
${title}
%(newline)s
by ${author}
%(newline)s
%(newline)s
# metadata
file_end:
In txt format, the title 'page' is just another section of text, but the name is kept for consistency.
In addition to the story title and author, the title page typically contains a collection of metadata about the story. By default, this page includes series, category, genre, language, characters, etc, etc. See titlepage_entries in defaults.ini for more information about what can be included. This document is about how it is included.
Config options that mention that 'metadata' is available refer to all the same entries that can appear in titlepage_entries.
There are five options for the title page--the text that appears at
the beginning (titlepage_start) of the title page block, at the end
of the block (titlepage_end), and three variations that are used to
display each metadata entry value.
titlepage_entry is the typical entry value formatting.
titlepage_wide_entry can be used to provide an alternative
formatting for wider entries--useful if you've elected to do more
complex formatting.
titlepage_no_title_entry can be used to provide an alternative
formatting for entries with empty labels--useful if you've elected to
not have a visible label for description, for example.
[txt]
# metadata ${title}, etc.
titlepage_start:
%(newline)s
# ${id}, ${label}, ${value}
titlepage_entry:${label}: ${value}
%(newline)s
%(newline)s
# ${id}, ${label}, ${value}
# Used with entries listed in wide_titlepage_entries, typically description, storyUrl, authorUrl
titlepage_wide_entry:
# ${id}, ${value}
# For example, if you've set description_label:
# (that is, nothing)
titlepage_no_title_entry:
# metadata
titlepage_end:
%(newline)s
%(newline)s
In txt format, the TOC 'page' is just another section of text, but the name is kept for consistency.
There are three options for the TOC page--the text that appears at the
beginning (tocpage_start) of the title page block, at the end of the
block (tocpage_end), and tocpage_entry that is used to display
each chapter.
tocpage_entry has three values passed to it, number, the chapter
number, chapter, the chapter name, and index04, the chapter number
padded with 0's to four digits. That's the way each chapter file is
named.
[txt]
# metadata
tocpage_start:
%(newline)s
TABLE OF CONTENTS
%(newline)s
%(newline)s
# ${number}, ${index04}("%04d"%${number}), ${chapter}
tocpage_entry:
${chapter}
%(newline)s
# metadata
tocpage_end:
%(newline)s
The text for each chapter in the story is included immediately after
the previous, so the chapter_start and chapter_end typically
contain just the chapter title and some spacing.
The chapter HTML from the source site, converted to text, is injected
between the chapter_start and chapter_end header and trailer.
Three values are passed to each, number (the chapter number),
chapter (the chapter name), and index04, (the chapter number padded
with 0's to four digits). That's the way each chapter file/section is
named--not really useful to txt.
[txt]
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_start:
%(newline)s
${chapter}
%(newline)s
%(newline)s
%(newline)s
## ${number}, ${index04}("%04d"%${number}), ${chapter}
chapter_end: