# vRain for building vertical Chinese eBooks from Perl

> vRain converts Chinese source text into vertically typeset PDFs styled after traditional woodblock editions. It suits editors and readers who need searchable text, configurable page decoration, and automatic font fallback for uncommon characters.

**shanleiguang/vRain** — 中文古籍刻本風格直排電子書製作工具 Chinese Ancient eBooks Generator

- Repository: https://github.com/shanleiguang/vRain
- Stars: 1,676 · Forks: 190
- Language: Perl
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/shanleiguang-vrain

## Why vRain replaces scans with editable vertical text

vRain addresses a specific gap between scanned ancient books and ordinary electronic text. The project notes that scanned pages can contain distortion, physical defects, and large image files, while their text cannot be selected for searching. Its stated goal is to reconstruct that printed appearance in text-based PDF form so readers can search characters and words, consult glosses, and place the result in an ebook reader.

The tool is intended for people preparing Chinese books from prepared text. That distinction matters. vRain is not described as OCR software and does not claim to clean a scanned file into source text. Text editing is deliberately separated from automatic typesetting: the editor prepares numbered text files, then vRain handles placement and PDF generation. The repository also identifies related projects for other parts of a publication workflow, including vYinn for seals, vQi for classical chess manuals, and vModou for scan distortion correction. Those separate tools make the division of work explicit.

The result retains the visual conventions of a traditional edition rather than treating them as a skin applied after generation. Page leaves can imitate woodblock pages or bamboo slips. Columns run from top to bottom and from right to left, while PDF bookmarks can be derived from chapter markers. Searchable output depends on the input being real text, not reconstructed by vRain itself.

## How vRain maps characters onto vrain.pl pages

The core program is `vrain.pl`, written in Perl. Its documented model begins with a generated book-leaf background. Based on the configured number of columns and characters per column, the program builds a coordinate array, then prints each character into its assigned position. When a leaf fills, it creates the next one until the selected source range has been processed.

Each book lives under `books/<ID>/`. Its main entry point is `books/<ID>/book.cfg`, which connects the title and author metadata to a canvas through `canvas_id`. Source files are sorted from `books/<ID>/text/`, including optional material in `000.txt` and `999.txt`. Generated PDFs are written into the same book directory. This fixed mapping makes a book self-contained at the configuration and asset level, although it also means that setup involves more than passing text on a command line.

Typography is controlled separately from page construction. Up to five font files can be registered, with `text_fonts_array` and `comment_fonts_array` defining lookup order. `Font::FreeType` checks glyph support and measures glyphs. If the first font lacks a character, vRain tries configured fallback fonts and may attempt Simplified-to-Traditional or reverse conversion when that improves coverage. The README warns that conversion can conflict with context, so automatic fallback must not be treated as linguistic validation.

The renderer also understands special source characters. `@` denotes a space, `%` a leaf break, and `$` a page or half-leaf break. Bracketed sections can represent double-column comments, while other delimiters produce waves, boxes, circles, notes, scaling, indentation, or top-positioned paragraph openings. `【】` reserves text for double-column annotations. These conventions provide fine typographic control, but they also place parsing responsibilities on whoever prepares the source.

## Canvas and book.cfg settings in the vRain layout

vRain uses two configuration levels. The canvas configuration defines the physical page. `canvas_width`, `canvas_height`, and the four margin keys establish dimensions. `leaf_col` controls the number of columns, while `leaf_center_width` defines the center strip. Outer and inner frames use their width and color keys. Optional settings cover multiple rows and center text such as `logo_text`. Background generators can create aged-paper woodblock pages or bamboo-slip pages, depending on the selected script and configuration.

The book configuration defines the text layer. Core keys include `title`, `author`, `canvas_id`, `row_num`, and `row_delta_y`. Cover and center-strip titles have separate font sizes, positions, and colors. `title_directory` enables PDF bookmarks, and `title_postfix` can append a chapter number, with `X` replaced by the converted numeric marker.

Punctuation deserves separate review because it directly changes page density. `exp_replace_comma` and `exp_delete_comma` transform or remove marks. `if_onlyperiod` enables normalization to periods, while `exp_onlyperiod` defines the applicable rule. `text_comma_nop` lists punctuation that does not consume a character cell. Per-character or punctuation offsets can then be adjusted through the documented `_x`, `_y`, and related keys. Font rotation is configurable per font.

The separation is useful when a visual template is reused across books, but it increases configuration effort. A visually wrong book may depend on canvas dimensions, column counts, glyph metrics, punctuation occupancy, or offsets rather than on one obvious switch. The documented `-v` option is the appropriate starting point when diagnosing those interactions because it exposes font selection and scaling information.

## Generating a first vRain test PDF with five pages

The README gives no package installation or dependency installation commands, so it does not document a one-command setup for macOS or Linux. It states that a Perl 5 environment is required, together with `PDF::Builder`, `Font::FreeType`, `Image::Magick`, and Ghostscript for optional PDF compression. Background scripts use Image::Magick. The repository does not document a specific operating-system package manager or module installation procedure.

After placing source files in `books/00/text/` and configuring `books/00/book.cfg`, the documented full-range invocation is shown below. The `-f` and `-t` values are positions after sorting the filenames, not the numeric labels embedded in those filenames.

```bash
perl vrain.pl -b 00 -f 1 -t 80
```

For initial layout work, use the documented test mode rather than processing the entire range. It limits output to five pages and adds `_test` to the generated PDF name.

```bash
perl vrain.pl -b 00 -f 1 -t 80 -z 5
```

If the configured leaf style is not already present, the README shows background generation from the `canvas/` directory. The configuration names must match files available there.

```bash
cd canvas && perl vintage.pl -c vintage
cd canvas && perl bamboo.pl -c bamboo
```

The first useful output is therefore a short PDF for checking glyph choice, punctuation, notes, margins, and vertical placement. Optional verbose output is enabled with `-v`:

The reader should expect the output under `books/00/`, with `_test` present when test mode is enabled. Optional compression uses `-c` on macOS and requires Ghostscript.

## vRain font fallback limits searchable glyph coverage

The font system is the most useful answer to rare Chinese characters and also the clearest boundary on output quality. A primary font can be supplemented by up to four fallback fonts. vRain checks glyph availability rather than assuming that a visually similar font contains every required character. It can also measure differences in glyph height and adjust font size when `if_font_metric_adjust` is enabled. Characters rendered with a fallback font may receive a simulated bold stroke through `if_fallback_bold`, with width controlled by `fallback_bold_stroke_width`.

This mechanism reduces missing-glyph failures, but it does not guarantee correct typography. Different fonts can have incompatible shapes, weights, proportions, or historical character forms. The optional Simplified-to-Traditional conversion may produce a glyph that is technically supported but wrong for the passage. Search and copying can therefore work while visual or linguistic accuracy still requires review.

vRain is also the wrong tool for repairing a scan. A warped or damaged source image remains outside the core generator's documented role. Users would need another process or the separately listed vModou before they had clean text to prepare. Likewise, vRain does not document automatic recognition of chapter structure from arbitrary prose. Its directory uses automatic bookmarks, but source markers such as `第x回` or `卷x` remain part of the prepared input.

Compared with laying out each page in a general graphics or PDF application, vRain automates repeated character placement, pagination, font selection, annotations, and bookmarks. Compared with a conventional word-processing workflow, it preserves vertical and right-to-left column order with source-level layout controls. The trade-off is that this is a specialized Perl toolchain rather than a general ebook authoring interface.

## vRain release artifacts, platform constraints, and MIT use

The repository is not archived, and its last push was on 2026-06-14. The release history lists v1.4 for macOS on 2025-09-02 and v1.3 for macOS on 2025-07-27. At the same time, the README badge says v1.5 while the listed releases stop at v1.4. That discrepancy should be resolved against the repository before adoption, particularly because release assets may differ from the current `main` branch layout.

Platform documentation lists macOS and Linux, but PDF compression is explicitly described as a macOS feature enabled by `-c`, with Ghostscript required. The repository provides several completed example PDFs, including woodblock, aged-paper, bamboo-slip, self-commentary, compressed, and phone-wallpaper outputs. Those examples can help users compare presentation choices, but the README does not document a migration guide, automated compatibility matrix, or rollback procedure.

Upgrade cost depends on the book data. Fonts, canvas scripts, images, `book.cfg`, source-text markers, and the Perl environment all participate in output. A release change could therefore require regenerated backgrounds and regression checks on representative pages. The short test mode reduces the cost of this review because it limits generation before a complete book is rendered.

The repository identifies the license as MIT. That generally indicates permission to use, copy, modify, and distribute the software under the license terms, subject to its conditions, but this review does not provide legal advice. Users should retain the license text and review font licensing separately because bundled TTF files can carry their own distribution terms.

## Conclusion

Adopt vRain when the source is prepared Chinese text and the goal is a configurable, searchable vertical PDF with traditional page styling. Do not choose it when OCR, scan correction, or automatic source-text preparation is required. Verify first that the intended fonts contain the required glyphs, that the canvas and book settings produce an acceptable test page, and that the local Perl and PDF toolchain matches the target system.

## FAQ

### What operating systems and runtime dependencies does vRain require?

The README lists macOS and Linux as supported platforms. It requires Perl 5, `PDF::Builder`, `Font::FreeType`, and `Image::Magick`; Ghostscript is required when using the documented PDF compression option.

### How do I generate a small vRain PDF before processing an entire book?

Use `-z` with a page count. For example, `perl vrain.pl -b 00 -f 1 -t 80 -z 5` limits output to five pages and adds a `_test` marker to the PDF name.

### Does vRain perform OCR or correct distorted ancient-book scans?

No such capability is documented. vRain lays out prepared Chinese text into PDFs, while scan distortion correction is associated with the separate vModou project.

## Sources

- [Issues](https://github.com/shanleiguang/vRain/issues)
- [License: MIT](https://github.com/shanleiguang/vRain/blob/main/LICENSE)
- [README](https://github.com/shanleiguang/vRain/blob/main/README.md)
- [Releases](https://github.com/shanleiguang/vRain/releases)
- [shanleiguang/vRain on GitHub](https://github.com/shanleiguang/vRain)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/shanleiguang-vrain