Re:VIEW Publishing Formats, Installation, and First Book

What Re:VIEW Solves for Multi-Format Book Publishing

Re:VIEW addresses the cost of maintaining the same publication in incompatible formats. A publisher can keep chapters and related material in Re:VIEW's original source format, then use separate commands to create EPUB, PDF, text, web pages, and InDesign XML. The repository presents the project as a digital publishing system for paper books and ebooks, so its intended scope is structured editorial production rather than a general-purpose Markdown renderer.

The central users are authors, technical writers, publishers, and documentation teams that need repeatable builds from source files. Ruby is the primary language, and the project is distributed as a gem. That makes the command-line and Ruby-oriented workflow more relevant to teams comfortable with gem installation, generated projects, and `rake` tasks than to users who only want to open a document in a graphical editor.

This approach has a clear trade-off. Re:VIEW adds a format layer that builders must learn, but it avoids treating each final format as the primary manuscript. For a multi-output book, that separation can be useful. For a small document that will only become one EPUB or PDF, the additional project structure may be more than the publishing problem requires.

Re:VIEW Source to EPUB, PDF, and Editorial Handoffs

The input side is Re:VIEW format, documented in `doc/format.md`. A generated project contains `*.re` files plus project configuration, including `config.yml` and `catalog.yml`. Those files form the source tree from which the publication commands operate. The catalog is particularly relevant to a book because it provides project-level document organization, while the configuration file controls settings used by the build.

Each output command targets a separate publishing stage. `review-epubmaker` generates EPUB. `review-pdfmaker` uses LaTeX and requires TeXLive, while `review-idgxmlmaker` creates InDesign XML for an editorial or layout workflow. `review-textmaker` produces text, and `review-webmaker` creates web pages. The documented supported formats also include Markdown and plain text through TOPBuilder Text Markup Language, although the command list does not map every supported format to a separate maker command.

Re:VIEW also includes utility commands with narrower jobs. `review-compile` compiles Re:VIEW files, `review-vol` calculates their size, `review-index` generates an index, `review-preproc` runs a preprocessor, `review-epub2html` turns an EPUB into a single HTML file for CSS typesetting, and `review-update` updates project files. This command separation allows a publication pipeline to stop at the format required by the next tool rather than forcing every build through one universal output.

Installing Re:VIEW with RubyGems

The shortest documented installation uses RubyGems. This installs the released gem and makes the Re:VIEW commands available through the Ruby environment.

gem install review

The repository also documents installation from a source checkout. This route is intended for contributors or users who want to work from the repository files.

git clone https://github.com/kmuto/review.git
cd review
rake install

Another documented option is to place the repository's `bin` directory on `PATH`. This keeps command lookup tied to a local checkout instead of the gem installation. The exact placeholder must be replaced with the checkout path before running the command.

echo "export PATH=PATH_OF_REVIEW/bin:$PATH" >> ~/.profile

The gem and source-checkout routes are preferable when the machine should use the installed command set. The `PATH` route is useful for development against the checkout, but it shifts responsibility for path setup and later repository updates to the user.

Creating a Re:VIEW Project and Building EPUB

The Quick Start creates a project named `hello`, changes into it, adds or edits `*.re`, `config.yml`, and `catalog.yml`, then invokes a build task. The following is the smallest documented EPUB path after the gem is installed.

review-init hello
cd hello
rake epub

`review-init hello` creates the project directory and its starting structure. After editing the source and configuration files, `rake epub` generates an EPUB. The README lists several other targets in the generated project, including `rake pdf`, `rake text`, `rake web`, and `rake idgxml`.

The documentation also exposes direct commands such as `review-epubmaker` and `review-compile`. That distinction matters when integrating Re:VIEW with automation: project tasks provide the documented project-level build entry points, while the commands offer narrower operations. The README does not describe custom `rake` task syntax, so a team should inspect the generated `Rakefile` before adding pipeline-specific behavior.

The initial build should be treated as an editorial setup task, not a one-command conversion. The Quick Start explicitly calls for adding and editing manuscript, configuration, and catalog files before invoking `rake epub`.

PDF Output and the External TeX Toolchain

PDF generation has a different dependency model from EPUB or text generation. The Quick Start identifies `rake pdf` as requiring TeXLive, and the command description assigns PDF generation to `review-pdfmaker`, which uses LaTeX. A machine without the required TeX components can therefore run part of the Re:VIEW project but cannot complete that PDF path.

The generated project also offers `rake vivliostyle` for PDF generation through Vivliostyle-CLI. That is a separate route with its own external requirement. Re:VIEW is therefore not claiming to render every PDF internally. It coordinates the document build while the documented PDF targets depend on an external typesetting stack.

The repository includes a sample `Dockerfile` for a Debian-based build environment. It installs TeX Live packages, Japanese fonts and language support, Ghostscript, Poppler utilities, Ruby packages, and the `review`, `rake`, and `bundler` gems. Its documented usage mounts the current publication directory at `/work` and runs `rake pdf`. This offers a concrete container path for teams that want a repeatable PDF dependency set, but the file is explicitly a sample rather than a complete deployment specification.

docker build -t review .

After building that image, the sample directs the user into a Re:VIEW project directory and mounts it for the build.

docker run -it --rm -v `pwd`:/work review rake pdf

The volume mount is essential because it places the manuscript files inside the container's working directory.

Direct LaTeX Compared with Re:VIEW's Multi-Format Build

The practical alternative for print-heavy work is to author LaTeX directly and use LaTeX as the manuscript format. Re:VIEW itself documents the difference: its PDF maker generates PDF through LaTeX, while Re:VIEW source remains the primary input before conversion. A direct LaTeX workflow removes the Re:VIEW format and its generator commands from the path, which can simplify a project that only targets print.

Re:VIEW earns its extra layer when the same publication must also become EPUB, text, web pages, or InDesign XML. In that case, the documented maker commands let one source tree feed several outputs. The trade-off is that the source format and generated project files become part of the publishing contract. Authors must stay within Re:VIEW syntax, and maintainers must understand how `config.yml`, `catalog.yml`, and the build tasks fit together.

Direct LaTeX also offers a different operational model. It makes layout and TeX behavior explicit from the start, while Re:VIEW delegates the final PDF stage to LaTeX through `review-pdfmaker`. For teams that need several formats, that delegation is useful. For a small team with one fixed print output and no need for the other makers, the simpler alternative may be the better fit.

Re:VIEW Maintenance, Upgrades, and License Boundaries

The repository is not archived, and its last push was on 2026-07-21. The documented release history includes v5.11.0 on 2026-03-15, v5.10.0 on 2024-10-29, and v5.9.0 on 2024-05-04. These dates indicate that the repository layout has continued to receive changes, but they do not by themselves describe upgrade compatibility for a particular manuscript. The README does not publish a migration procedure for moving an existing project between these versions.

The `review-update` command is documented as a way to update project files, which gives teams a project-level operation to investigate when upgrading. It does not guarantee that generated files or manuscript syntax can be updated without review. The `doc/quickstart.md` file is the README's stated next reference for setup, while `doc/format.md` is the stated format reference.

The main Re:VIEW code is licensed under GNU Lesser General Public License, version 2.1. The repository also lists separate terms for bundled or supporting files: `doc/*` and `samples/*` use MIT, `jumoline.sty` and `vendor/jumoline` use the LaTeX Project Public License, `plistings.sty` and `vendor/plistings` use MIT, and `jsbook.cls` and `vendor/jsclasses` use BSD. Anyone distributing a book or a derived artifact should check the relevant files rather than treating every repository component as covered by one identifier.

Editorial conclusion

Adopt Re:VIEW when a documentation or book workflow needs one Re:VIEW source tree to produce several publication formats, especially when Ruby and build tasks already fit the team. Do not choose it merely for a one-off HTML or PDF conversion unless the team can support its format conventions, generated project files, and external PDF dependencies. Verify first that your required output is supported, that TeXLive or Vivliostyle-CLI is available when needed, and that the LGPL terms and bundled asset licenses match your distribution process.

Frequently asked questions

Official sources

1. kmuto/review on GitHub
2. License: LGPL-2.1
3. Project website
4. README
5. Releases