Skip to content

README.md

Latest commit

 

History

History
118 lines (103 loc) · 6.68 KB

README.md

File metadata and controls

118 lines (103 loc) · 6.68 KB
Raw

epubQTools Release

Tools for checking, correcting and hyphenating EPUB files.

External apps used by this tool available for download:

Put both into the per-user tools folder (or point to another folder with --tools DIR):

  • Linux/macOS: ~/.local/share/epubQTools/ ($XDG_DATA_HOME/epubQTools/ if set)
  • Windows: %LOCALAPPDATA%\epubQTools\

If this folder does not exist, the folder next to the program is used (as in older versions). kindlegen is also looked up in PATH.

usage: epubQTools [-h] [-V] [--tools [DIR]] [-l [DIR]] [-i [NR]] [--author [Surname, First Name]] [--title [Title]]
                                                        [--font-dir [DIR]] [--replace-font-family [old,new]] [-a] [-n] [-t] [-q] [-p] [-w] [-u] [--list-fonts] [-m] [-e] [-s]
                                                        [-r] [-c] [--skip-justify] [--left] [--replace-font-files] [--remove-colors]
                                                        [--remove-fonts] [-k] [-d] [-f] [--fix-missing-container] [--book-margin [NUMBER]]
                                                        directory

positional arguments:
  directory             Directory with EPUB files stored

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --tools [DIR]         path to additional tools: kindlegen, epubcheck zip (default: ~/.local/share/epubQTools)
  -l, --log [DIR]       path to directory to write log file. If DIR is omitted write log to directory with epub files
  -i, --individual [NR]
                        individual file mode: without NR select files in the console (or list them if not run in a terminal), NR
                        processes the files with the given numbers, e.g. "3" or "1,3,5-7"
  --author [Surname, First Name]
                        set new author name (only with -i)
  --title [Title]       set new book title (only with -i
  --font-dir [DIR]      path to directory with user fonts stored
  --replace-font-family [old,new]
                        pair of "old_font_family,new_font_family"(only with -e and with --font-dir)
  -a, --alter           alternative output display
  -n, --rename          rename .epub files to 'author - title.epub'
  -t, --prepare-send-to-kindle
                        copy MOH files to 'title.epub' (Send to Kindle friendly)
  -q, --qcheck          validate files with qcheck internal tool
  -p, --epubcheck       validate epub files with EpubCheck 4 tool
  -w, --skip-font-mime  do not report non-standard font media types (only with -q)
  -u, --skip-css-warnings
                        do not report CSS warnings, only CSS errors (only with -q)
  --list-fonts          list all fonts in EPUB (only with -q)
  -m, --mod             validate only _moh.epub files (works only with -q or -p)
  -e, --epub            fix and hyphenate original epub files to _moh.epub files (saved in 'MOH' subfolder, in the same subfolders as the originals)
  -s, --skip-hyphenate  do not hyphenate book (only with -e)
  -r, --skip-hyphenate-headers
                        do not hyphenate headers like h1, h2, h3...(only with -e)
  -c, --skip-reset-css  skip linking a full reset CSS file to every xthml file; if the book is hyphenated,
                        a CSS with "hyphens: manual" only is linked instead (only with -e)
  --skip-justify        skip replacing "text-align: left" with "text-align: justify" in all CSS files (only with -e)
  --left                replace "text-align: justify" with "text-align: left" in all CSS files (experimental) (only with -e)
  --replace-font-files  replace font files (only with -e)
  --remove-colors       remove all color definitions from CSS files (only with -e)
  --remove-fonts        remove all embedded font files (only with -e)
  -k, --kindlegen       convert _moh.epub files to .mobi with kindlegen
  -d, --huffdic         tell kindlegen to use huffdic compression (slow conversion) (only with -k)
  -f, --force           overwrite previously generated _moh.epub or .mobi files (only with -k or -e)
  --fix-missing-container
                        Fix missing META-INF/container.xml file in original EPUB file (only with -e)
  --book-margin [NUMBER]
                        Add left and right book margin to reset CSS file (only with -e)

-m, -k and -t use only the _moh.epub files in the 'MOH' subfolder. Old results of earlier versions (next to the originals, or directly in 'MOH' for books from subfolders) are skipped and listed in a warning.

Output messages:

  • * text - information
  • ! WARNING! text - warning, the book is processed
  • ! ERROR! text - error, the book is processed with problems
  • ! CRITICAL! text - the book (or the whole run) cannot be processed
  • START ... for:, FINISH ... for:, FINISH (with PROBLEMS) ... for: - start and end of each stage

The internal check (-q) prints one finding per line (* or file: with -a), marked CRITICAL!, ERROR! or WARNING! where it applies.

CSS check (-q):

CSS files are parsed with tinycss2 (CSS Syntax Level 3) and checked for problems that matter in e-book readers (not for CSS 2.1 validity - vendor prefixes and modern properties are fine):

  • CSS ERROR! - a reader drops the declaration or rule: syntax errors, a declaration without :, an unexpected }, unknown property names (typos; list of known properties from MDN in lib/resources/css_properties.txt), a non-breaking or other unusual space in a value (outside quotes), a missing semicolon, more than 4 values in margin/padding
  • CSS WARNING! (silenced with -u) - may cause problems in some readers: !important on font-size, font-family, line-height, color or background-color, position: fixed/absolute, display: flex/grid, vh/vw/vmin/vmax units, a color on body/html, @import

Additional requirements:

  • python -m pip install lxml
  • python -m pip install css-parser
  • python -m pip install tinycss2
  • python -m pip install pyinstaller (for compilation only)

Tests:

Run from the main folder (with the requirements above installed):

python -m unittest

Compilation tips for creating standalone applications with Pyinstaller tool:

  • build on Mac (with Python 3.7.x from Homebrew):
pyinstaller -Fn epubQTools ~/github/epubQTools/__main__.py
  • build on Windows (with Python 3.7.x):
C:\Python37\Scripts\pyinstaller.exe -Fn epubQTools .\epubQTools\__main__.py