Troubleshooting Common Issues with CB’s JNovel FormatterCB’s JNovel Formatter is a popular tool among light novel translators and editors for converting raw translated text into polished, publication-ready files (EPUB, MOBI, PDF, or plain HTML). Despite its utility, users sometimes encounter problems ranging from minor formatting glitches to conversion failures. This article covers common issues, diagnostic steps, and practical fixes so you can get back to producing clean releases quickly.
1. Installation and Environment Problems
Symptoms:
- Formatter crashes on startup.
- Command-line scripts return “command not found” or similar errors.
- Plugins or optional features don’t load.
Causes & Fixes:
- Ensure you have the correct runtime environment installed. CB’s JNovel Formatter typically requires a recent version of Node.js and Python for some tooling; check the project README for exact versions.
- Verify PATH variables: if command-line tools aren’t recognized, add the formatter’s bin folder (or Node/Python install paths) to your PATH.
- If using a packaged release (Windows executable or macOS app), confirm that required dependencies bundled with the release aren’t blocked by antivirus or Gatekeeper. Temporarily disable antivirus or allow the app in system security settings and retry.
- Reinstall: sometimes leftover files from prior installs cause conflicts. Back up configuration files, remove the formatter, and reinstall cleanly.
2. Configuration and Template Issues
Symptoms:
- Output ignores custom CSS or template changes.
- Chapter headings, page breaks, or metadata aren’t applied as expected.
Causes & Fixes:
- Wrong config file used: the formatter looks for a specific config filename (e.g., config.json or jnovelformatter.yml). Confirm you’ve edited the file the formatter actually reads. Run with a verbose flag (if available) to see which config is loaded.
- Template inheritance: many formatters allow templates to extend base templates. If your changes are in a child template but a base template is overriding them, either edit the base or ensure your child template is loaded last.
- Syntax errors: a single misplaced comma or incorrect field name in JSON/YAML can cause the formatter to silently ignore parts of the config. Validate config with a linter or online validator.
- CSS specificity: if your CSS changes aren’t visible, check for specificity conflicts or important rules in bundled CSS. Use more specific selectors or !important sparingly to override defaults.
3. Character Encoding and Garbled Text
Symptoms:
- Non-ASCII characters (Japanese, punctuation, accented letters) appear as question marks, boxes, or mojibake.
- EPUB displays correctly in one reader but not in another.
Causes & Fixes:
- Ensure all input files are encoded in UTF-8 without BOM. Convert files using iconv or a text editor (e.g., Visual Studio Code: Save with Encoding → UTF-8).
- Verify the formatter declares UTF-8 in the EPUB/HTML headers or meta tags. If not, add the appropriate meta tag: in templates.
- Embedded fonts: some readers fall back to fonts lacking glyphs for certain scripts. Embed appropriate fonts (e.g., Noto Sans CJK for Japanese) in your EPUB or instruct readers to use a compatible font.
- Normalize line endings (LF vs CRLF) if the formatter or tools around it expect a specific style.
4. Broken EPUB / MOBI / PDF Output
Symptoms:
- EPUB fails validation (e.g., via epubcheck).
- Kindle devices reject MOBI or conversions yield missing images or styling.
- PDF renders with misaligned pages, missing margins, or truncated content.
Causes & Fixes:
- Run epubcheck or similar validators to get exact error messages. Fix issues such as duplicate IDs, missing manifest entries, or malformed XHTML.
- Image issues: confirm images are present in the expected folder and referenced with correct relative paths. Large images may be rejected or cause conversion slowdowns—resize and compress them.
- For MOBI/Kindle: use KindleGen or Kindle Previewer to convert EPUBs; they perform checks and produce Kindle-friendly packages. Some CSS features in EPUB aren’t supported on Kindle; simplify styling when targeting MOBI.
- For PDFs: PDF generation is often controlled by a separate engine (PrinceXML, wkhtmltopdf, or WeasyPrint). Make sure the engine is installed and configured. If page breaks are wrong, add explicit page-break CSS rules (e.g., page-break-after: always; or CSS paged media rules).
- Verify the EPUB’s spine and manifest order reflect the intended reading order. Incorrect spine order causes chapters to appear out of sequence.
5. Strange Spacing, Indentation, and Line Breaks
Symptoms:
- Extra blank lines between paragraphs.
- Indents missing or inconsistent across chapters.
- Forced line breaks inside sentences.
Causes & Fixes:
- Source formatting: many raw translation files contain manual line breaks intended for editing rather than final output. Use a preprocess step (line-join script) to reflow paragraphs while preserving paragraph breaks. Regular expressions can convert single newlines into spaces while keeping double newlines as paragraph separators.
- CSS resets: default user-agent styles differ across readers. Define consistent paragraph margins and text-indent in your stylesheet:
- p { margin: 0 0 1em; text-indent: 1em; }
- Multiple whitespace: collapse redundant whitespace during processing or ensure output HTML/CSS use white-space: normal.
- Nonbreaking spaces: stray nonbreaking spaces (U+00A0) can cause wrapping issues—replace them if unintended.
6. Metadata and Table of Contents Problems
Symptoms:
- Reader shows incorrect title, author, or cover.
- TOC missing entries or links don’t work.
Causes & Fixes:
- Metadata fields must be present in the package opf file. Confirm that title, creator, language, and identifiers are filled. If you rely on automatic metadata extraction from filenames or folder structure, check those rules.
- Cover: ensure the cover image is declared in metadata and included in the manifest with the correct properties (e.g., properties=“cover-image” for EPUB 3).
- TOC: EPUB 2 uses NCX; EPUB 3 uses a navigation document. Modern readers expect a nav.xhtml for EPUB 3. Ensure your formatter generates the correct TOC format for your target EPUB version.
- Anchor targets: broken TOC links often result from mismatched IDs or file names. Run a link-checker or validate the nav file to find missing/hit targets.
7. CSS and Styling Differences Across Readers
Symptoms:
- Formatting looks perfect in one reader but breaks in others (e.g., Calibre vs iBooks vs Kindle).
- Web fonts not applied on certain devices.
Causes & Fixes:
- Different readers support different CSS features and have their own default style sheets. Target the least common denominator when formatting for multiple readers: avoid experimental CSS, and rely on simple selectors and basic typographic rules.
- Font embedding: not all readers allow embedded fonts (some Kindle apps ignore them). Provide fallback fonts and test on real devices or official previewers.
- Media queries: avoid complex print/screen media query logic unless you’re sure the target reader supports it.
- Test early and often on the widest variety of readers you expect users to use.
8. Automation and Batch Processing Failures
Symptoms:
- Batch conversions stop midway or skip files.
- Scripted runs behave differently than manual runs.
Causes & Fixes:
- Race conditions: ensure your automation scripts wait for I/O operations to complete (use proper async handling or sequential processing).
- File locking: antivirus or other processes may lock files—introduce retries with delays or ensure exclusive file access.
- Environment differences: CI runners or servers may have different versions of tools. Pin versions in your automation environment and use containerization (Docker) for consistency.
- Logging: add detailed logs to your scripts to capture command outputs and errors when running unattended.
9. Plugin and Extension Conflicts
Symptoms:
- A plugin causes the formatter to crash or output malformed files.
- Certain features stop working after installing an extension.
Causes & Fixes:
- Disable plugins and re-enable one-by-one to isolate the offending plugin.
- Check plugin compatibility with your formatter version. Many community plugins lag behind the core project.
- Review plugin configuration options; some require additional dependencies or settings.
10. Performance and Large File Handling
Symptoms:
- Formatter runs extremely slowly on big projects.
- Memory exhaustion or out-of-memory crashes.
Causes & Fixes:
- Split very large projects into smaller batches during processing, then combine outputs.
- Increase memory limits where possible (Node.js: use –max-old-space-size).
- Optimize images and remove unnecessary high-resolution assets.
- Profile the formatter if possible to find bottlenecks (CPU-bound vs I/O-bound).
Quick Troubleshooting Checklist
- Is the input UTF-8 encoded? Convert if not.
- Does the config file have syntax errors? Validate JSON/YAML.
- Are images and assets referenced with correct relative paths?
- Run epubcheck or Kindle Previewer to get actionable errors.
- Test on multiple readers to isolate device-specific issues.
- Disable plugins/extensions to rule out conflicts.
- Use a clean reinstall if behavior is inexplicably broken.
If you want, provide a sample input file (or the formatter’s error log) and I’ll help pinpoint the issue and suggest exact config or code fixes.
Leave a Reply