Re:VIEW & publishing workflows

Re:VIEW sells itself on not making you write LaTeX. Open its config.yml, though, and there is a key called dvicommand whose value is dvipdfmx; open the class file it uses for PDF and it declares \DeclareOptionX{bleed_margin}[3mm] and an option named tombopaper for crop marks. LaTeX has not gone anywhere. It has been demoted to the department that talks to the printing press. This page looks at that publishing system — one lightweight .re markup, PDF and EPUB out of the same source — from the side of its LaTeX backend.

What Re:VIEW is, and what it can output

Re:VIEW is a book-oriented conversion system written in Ruby; the manuscript is a lightweight markup in files with the extension .re. From that one manuscript it converts to EPUB, LaTeX, InDesign (IDGXML), Markdown, plain text and web HTML. It was created by Minero Aoki and is maintained by Kenshi Muto (kmuto), with Masayoshi Takahashi and Masanori Kado also on the copyright line (2006–2024). The licence is LGPL. It became the de facto choice in the Japanese technical self-publishing world for one reason: getting a print-ready PDF and an e-book out of a single manuscript is exactly what that world needs.

= Getting started

Ordinary body text. Inline emphasis is written @<b>{like this},
and a cross-reference to a listing is @<list>{hello}.

//list[hello][A first program]{
puts "hello"
//}

//image[diagram][The system, in outline]{
//}

A project is the .re files, one per chapter, plus two YAML files. config.yml carries the metadata — title, author, trim size, the LaTeX settings — and catalog.yml carries the order of the chapters across front matter, body and back matter. The manuscript files themselves hold no ordering information, so rearranging chapters means moving lines in catalog.yml. The idea is the same as reordering a list of \include lines in LaTeX, except that this list is a catalogue rather than a typesetting instruction, so it governs the EPUB table of contents just as directly.

Installing and building it: this is not in TeX Live

Re:VIEW is a Ruby gem, not a TeX Live package. On a machine with a full TeX Live 2024 installation there is still no review-pdfmaker anywhere; you install it separately with gem install review. The requirement runs the other way too: the documentation says “To generate PDF, you should install TeXLive 2012 or later.”, so a TeX Live installation is needed on top. The system only works once two independent toolchains are in place, and running rake pdf without noticing that leaves you staring at an error without knowing which half is missing.

gem install review          # the Ruby side
# TeX Live is a separate prerequisite for the PDF route

review-init hello           # create a project skeleton
cd hello

rake pdf                    # PDF, through LaTeX
rake epub                   # EPUB
rake web                    # HTML
rake text                   # plain text
rake idgxml                 # InDesign

# the same jobs without rake:
review-pdfmaker config.yml
review-epubmaker config.yml

review-jsbook.cls is not in TeX Live: where File not found comes from

Take the .tex that Re:VIEW generated out of its project directory, compile it, and TeX Live 2024 stops at ! LaTeX Error: File ‘review-jsbook.cls’ not found. followed by ! Emergency stop. The reason is simple: that class ships inside the gem and is not part of TeX Live. Ask for kpsewhich jsbook.cls or kpsewhich jlreq.cls and you get a real path back; ask for review-jsbook.cls or review-jlreq.cls and you get nothing. The parents are in TeX Live; the children are not. Those two classes arrived in Re:VIEW 3.0; before that the system used jsbook.cls as it came.

$ uplatex rv.tex
! LaTeX Error: File `review-jsbook.cls' not found.
! Emergency stop.

$ kpsewhich jsbook.cls
/usr/local/texlive/2024/texmf-dist/tex/platex/jsclasses/jsbook.cls
$ kpsewhich jlreq.cls
/usr/local/texlive/2024/texmf-dist/tex/latex/jlreq/jlreq.cls
$ kpsewhich review-jsbook.cls
$                                  # nothing: it lives in the gem

Look inside the class and it is obvious which way this family faces. The \ProvidesClass identification line reads “Re:VIEW pLaTeX class modified for jsbook.cls” — a pLaTeX class, which together with dvicommand being dvipdfmx makes the print route (u)pLaTeX → DVI → dvipdfmx. And the options it declares are simply the vocabulary of a print shop: \DeclareOptionX{tombopaper} for paper sized to carry crop marks, \DeclareOptionX{bleed_margin}[3mm] for the bleed, defaulting to 3mm, \DeclareOptionX{hiddenfolio} for a folio the finished book conceals, and \DeclareOptionX{media}[print] — whose default value of print says more about where this family stands than any documentation could. For the electronic edition you switch it to media=ebook.

A second PDF route that is not LaTeX: Vivliostyle, added in 5.1

Version 5.1.0 added a second road, this one paved with CSS typesetting. rake vivliostyle:build calls the Vivliostyle CLI and makes a PDF straight from HTML and CSS, with rake vivliostyle:preview for checking it in a browser. The same manuscript can now leave by either door. What this really illustrates is Re:VIEW’s architectural position: LaTeX is one output format among several. Because the manuscript lives in .re and the appearance lives in a class or a stylesheet, the entire back half can be swapped out. Which door to use depends on what the typesetting demands; for close control of Japanese composition and a print submission with crop marks, the LaTeX route still has the fuller set of tools.

Re:VIEW or plain LaTeX: which to write the book in

Re:VIEW if you need the EPUB, plain LaTeX if you do not — that decision covers most of it. Start in LaTeX while still owing someone an EPUB and you will end up writing the HTML conversion stage yourself, which becomes the heaviest part of the project. Start in Re:VIEW with no EPUB in sight and you have simply bought an extra layer of abstraction: every time you want to adjust the typesetting you will first have to work out whether the fix belongs in the .re, in the LaTeX, or in between. The other deciding factor is your co-authors. Anyone who knows Markdown can read .re markup in a few minutes; a LaTeX preamble is not so hospitable.

One last thing worth holding on to: using Re:VIEW does not exempt you from knowing LaTeX. A figure that drifts, Japanese leading that has closed up, a \usepackage you need to add — every one of those is ultimately settled in the class file and the .sty, and what you consult at that moment is not the Re:VIEW documentation but your knowledge of LaTeX. The three keys texdocumentclass, texcommand and dvicommand in config.yml exist precisely as the doorway down to that level.