jlreq

jlreq is probably the only LaTeX document class that will tell you, mid-run, that your line spacing falls outside what the standard recommends. Released by Noriyuki Abe in 2017, it is an attempt to implement the W3C technical note “Requirements for Japanese Text Layout” (JLReq) in LaTeX, and that is where the name comes from. Its source carries more than thirty comments citing clause numbers of those requirements, and with the jlreq_notes option the advice — clause number attached — appears in the log. This page covers what jlreq does differently from the js-based classes, how it lets you design the text block in numbers, and how it handles Japanese-specific decisions such as vertical writing and where an opening bracket sits at the head of a line.

What JLReq is, and how the class implements it

JLReq is a W3C technical note describing what is needed to set Japanese correctly. Built on the Japanese Industrial Standard JIS X 4051 (formatting rules for Japanese documents), it lists — clause by numbered clause — the rules that technologies such as CSS and e-books ought to honour: which characters may not begin or end a line, the space between Japanese and Latin script, the treatment of notes and headings, how the text block is arrived at. The head of the jlreq class file names the edition it implements: the W3C Note of 11 August 2020. The accurate description is that a specification has been translated into a document class.

How deep the implementation goes shows in the fact that the class ships its own Japanese font metrics (JFM). Where jsclasses borrows the JIS metric, jlreq distributes dedicated TFM files such as jlreq.tfm, jlreqg-v.tfm and jlreq-jidori.tfm, plus jfm-jlreq.lua and jfm-jlreqv.lua for LuaTeX-ja. The spacing around punctuation and brackets is decided inside the metric rather than in a class macro — the requirements are baked into the lowest layer of the typesetting engine. The class detects for itself whether pLaTeX, upLaTeX or LuaLaTeX is running and records it in the log as, for example, jlreq guessed engine: uplatex (XeLaTeX is not supported). To force the choice, pass platex, uplatex or lualatex as a class option.

The difference between jlreq and jsclasses

In a sentence: jsclasses hands you a finished look, jlreq hands you the dials that make one. Haruhiko Okumura’s jsarticle is designed around well-tuned defaults you simply accept, and it produces a readable Japanese document with no thought required. jlreq assumes the opposite: that you will supply the numbers yourself — body size, characters per line, lines per page, line spacing, and the top, bottom, spine and fore-edge margins. So the two do not really compete. Reach for jsclasses when a paper has to look tidy in a hurry, and for jlreq when the trim size and the line length were decided before you started.

The other difference is that the fine decisions needed to follow the standard are exposed as options. Add narrow_kanjiskip, for instance, and the space between Japanese characters (kanjiskip) reverts to what jsarticle uses. That option is the shortest answer to “the texture of the type changed when I moved to jlreq”. The default JFM takes the spacing the requirements call for, so a manuscript moved unchanged from jsclasses to jlreq will look slightly different line by line even at the same characters-per-line. If you are migrating, compare one page before you commit the whole manuscript.

The basic options: document type, paper and font size

jlreq has only one class. You switch the kind of document with a bracketed option: the default behaves like article, report gives you a report with \chapter, and book gives a book. Note that the class name is not split per type as it is in jsclasses. Add tate for vertical writing. Beyond that, familiar spellings from the standard classes work unchanged: twocolumn, twoside, titlepage, landscape, draft, openright/openany, disablejfam.

Paper is given with paper=. Besides paper=a4 and paper=a5 you can write the width and height directly, as in paper={148mm,210mm}. There is a trap here. paper=b5 means ISO B5 (176×250 mm), not the 182×257 mm that “B5” denotes in Japan. The class does not let this pass silently; it warns Class jlreq Warning: The option 'b5' means the papersize in the ISO B-series, not in the JIS B-series. This behavior was changed from jlreq version 2021-11-05. Use 'paper=b5j' for the JIS-B-series. For a self-published book or a Japanese printer, paper=b5j is almost certainly what you want.

Think of the Latin and Japanese sizes separately. fontsize= is the base Latin size (default 10pt), jafontsize= is the Japanese size, and jafontscale= gives the ratio between them directly (default 1, that is, the same size). jlreq accepts the printing units Q and H as dimensions, so fontsize=13Q can be written as it stands (1 Q = 1 H = 0.25 mm). Japanese layout specifications almost always arrive in Q, and being able to copy them across without converting matters more in practice than it sounds.

Designing the text block in numbers

The text block — the rectangle the body is set in — is fixed from the inside out or from the outside in. Inside out means giving the line length line_length=, the number of lines number_of_lines= and the line spacing baselineskip=, and letting the margins be whatever is left. Outside in means giving the top head_space=, bottom foot_space=, spine gutter= and fore-edge fore_edge= (fore-edge= also works) margins, and letting the block be whatever is left. If the specification arrives as “38 characters per line, 18 lines per page”, work from the inside; if it arrives as “20 mm at the head, 18 mm at the spine”, work from the outside. There is no need to mix the two.

Dedicated units help here. zw is the width of one full-width character and zh its height, so line length and spacing can stay in units of characters. line_length=40zw is 40 characters per line; baselineskip=1.75zw is spacing of 1.75 full-width characters. Line spacing can also be given as linegap=, which counts “one full-width character plus the gap you name”. Left unset, line_length is 0.75× the paper’s extent in the character direction, number_of_lines is whatever fits within 0.75× the extent in the line direction, baselineskip is 1.7× the Japanese size, and the column gap column_gap is 2zw. Omit head_space and foot_space and the block is centred vertically.

Japanese-specific settings: brackets, hanging punctuation, tate-chu-yoko

This is jlreq’s most distinctive territory. open_bracket_pos= decides how an opening bracket is placed when it falls at the head of a line (JLReq 3.1.5). The three values are zenkaku_tentsuki (the default), zenkakunibu_nibu and nibu_tentsuki, choosing whether the bracket sits flush at full width or is pulled in by half an em. hanging_punctuation switches on hanging punctuation, letting a comma or full stop at the end of a line hang outside the text block (3.8.2, note 1). Both are choices that web and DTP people argue about routinely; being able to flip them with a single class option is close to unique to jlreq.

The body of the document gets Japanese tools too: \tatechuyoko for setting digits upright inside vertical text, \jidori for fitting text into a fixed allotment of characters, \warichu for the small two-line inline note, \sidenote for side notes, \endnote for endnotes, and \akigumi for temporarily widening the inter-character space. Dates have their own etiquette: declare \和暦 and \today prints the date with the era name, in kanji numerals when the document is vertical. The class carries the Shōwa/Heisei/Reiwa boundaries — 8 January 1989 and 1 May 2019 — in its own code, and its changelog records the 2019 change simply as a new regnal year.

A vertical example, and choosing the engine

Here is an A5 document, set vertically, with the text block designed from the inside out: tate makes it vertical, paper=a5 fixes the trim size, and the rest states the block in numbers — Japanese at 13 Q, 40 characters per line, 17 lines per page, spacing of 1.75 full-width characters. Nothing needs adding to the body; that one line fixes a book-like layout. The same \documentclass line runs either way: upLaTeX takes it through DVI, LuaLaTeX writes the PDF directly with system fonts. To go horizontal, drop tate.

\documentclass[
  tate,                 % vertical writing
  paper=a5,
  fontsize=13Q,         % 1 Q = 0.25 mm
  line_length=40zw,     % 40 characters per line
  number_of_lines=17,
  baselineskip=1.75zw,
]{jlreq}
\begin{document}
\title{雪国}
\author{川端康成}
\maketitle
国境の長いトンネルを抜けると雪国であった。
\end{document}

There is one trap that appears only on the DVI route. jlreq does not write the paper size into the DVI as a \special. So a source that says paper=a5, set with upLaTeX and handed to dvipdfmx, produces a PDF at dvipdfmx’s default paper — A4 under the standard TeX Live configuration. There are two fixes: add \usepackage{bxpapersize} to the preamble, or name the size on the converter, as in dvipdfmx -p a5. LuaLaTeX writes the page size straight into the PDF and never runs into this.

Let the class check your design (jlreq_notes)

Add jlreq_notes to the class options and jlreq checks your numbers against the requirements, writing anything out of range into the log. Set baselineskip=1.2zw, for instance, and a line appears under a JLReq heading saying that the line gap should be between half an em and a full em (clause 2.4.2.d, note 3). It will also speak up when a side note’s measure is too short, or when a vertical layout leaves too little room between the block and the running head, each time citing the clause. Typesetting does not stop — these are notes, not rules. Only a physically impossible setting halts the run: if the line spacing is smaller than the font size you get ! Class jlreq Error: The baselineskip is less than fontsize.

Shaping headings and notes with \jlreqsetup

The dimensions of the text block are set as class options, but the detail of notes, quotations, lists and headings is tuned in the preamble with key=value pairs in \jlreqsetup{...}: how footnotes, side notes, warichu and endnotes are rendered, the indent of quotations (quote_indent=), the line allotment of headings. To redesign a heading itself, use \NewBlockHeading or \ModifyHeading. The division of labour is deliberate — the text block is what a reader sees the instant a page opens, while \jlreqsetup governs how individual elements behave. You do not need all of it at once: fix trim size, line length and line count in \documentclass, then add to \jlreqsetup as the need arises. The authoritative list is in the bundled manual (in Japanese, by Abe), which texdoc jlreq opens.

After setting the block, inspect one page

jlreq is powerful enough that wrong numbers still produce a PDF. Before writing the real body, build one page of dummy text with a heading, a footnote, a quotation and a small figure or table, and actually measure the line length, the line count and the spine and fore-edge margins. In vertical writing the line direction and the character direction swap places compared with horizontal writing, so check first that line_length and number_of_lines have not been exchanged. If you need trim marks, use the jlreq-trimmarks package rather than a class option; passing tombow warns The option 'tombow' is not supported by jlreq class. Please use the jlreq-trimmarks package.

• Line length — count full-width characters in the body text, not just where the punctuation falls.
• Line count — count body lines on an ordinary page and on a page carrying a heading.
• Margins — allow more at the spine for a bound manuscript; avoid an excessive gutter for a PDF-only submission.
• Paper — on the DVI route, measure the finished PDF. Forget bxpapersize or dvipdfmx -p and it comes out A4.
• Engine — if upLaTeX and LuaLaTeX use different fonts, treat only the chosen route’s PDF as authoritative.