js-based classes

Ask jsarticle for a “10 pt” body and the Japanese type you actually get measures about 9.25 pt. That is not a bug but the design: Haruhiko Okumura’s jsclasses (jsarticle, jsbook) are built around the Japanese printing body of 13 Q (3.25 mm), not the Latin 10 pt. The js-based classes keep the feel of the LaTeX standard classes and replace only what Japanese needs — the font metric, the ladder of body sizes, and the machinery that scales them. ltjsclasses carries that design to LuaLaTeX; BXjscls carries it to every engine. This page is about what each of the three actually solves, and how to choose.

The two things jsclasses changes from the standard classes

The manual that ships with jsclasses names exactly two differences from the standard document classes: the Japanese font metric and the handling of size options. It did not rewrite a philosophy of margins or leading; it fixed two things that were actually broken when setting Japanese. First, it uses the JIS font metrics jis.tfm and jisg.tfm, made by Hajime Kobayashi of Tokyo Shoseki Printing, in place of the older min10 and goth10. Second, it rebuilt size selection: the standard classes offered only 10pt, 11pt and 12pt, and — in the manual’s own words — outside the standard 10 pt the balance of the fonts was somewhat off.

The two are really one root. Japanese printing counts type in Q (kyū, 1 Q = 0.25 mm), and the standard body is 13 Q, that is 3.25 mm. But a full-width character in the raw JIS metric is 13.527 Q, so jsclasses scales the Japanese font by 0.961 (= 13 ÷ 13.527) to land the em exactly on 13 Q. The manual spells the arithmetic out and notes that after scaling the 9.62216 pt metric, a nominally 10-point body is really “a little over 9 points”. The ratio lives in the real-valued macro \Cjascale, which is 0.924690 in jsarticle, jsbook and jsreport (= 9.62216 pt × 0.961 ÷ 10 pt). Since 2018 the OTF package reads that macro to match the Japanese size.

% upLaTeX: the dvipdfmx option is a global option for graphicx/hyperref
\documentclass[uplatex,dvipdfmx,a4paper,papersize]{jsarticle}
\begin{document}
こんにちは、\LaTeX！
\end{document}

The family is jsarticle (papers and reports), jsbook (books) and jsreport (reports), with jspf for a society journal and kiyou for bulletins bundled alongside. jsreport was split off in February 2017, after a forum discussion, from what people had been doing with jsbook’s report option. Okumura originally wrote the bundle on top of the LaTeX3 Project’s classes.dtx and ASCII Corporation’s jclasses.dtx; Takuji Tanaka’s upLaTeX-support patch was merged in 2009, and since July 2016 the Japanese TeX Development Community has maintained it (texjporg/jsclasses on GitHub). It ships with TeX Live, so there is nothing to install.

How the body size is built: \mag versus nomag

jsclasses sets the body at 10 pt and then scales the whole document with TeX’s \mag primitive to reach the size you asked for (×1.095 for 11pt, ×1.200 for 12pt). That is how it can offer sizes the standard classes do not: the geometric ladder 8pt, 9pt, 14pt, 17pt, 20pt, 21pt, 25pt, 30pt, 36pt, 43pt, the Q-unit 12Q and 14Q, and the true-size 10ptj, 10.5ptj, 11ptj, 12ptj. \mag stretches paper, glyphs and rules alike, which is powerful — but some tools do not understand the value, and the result depends on how dvipdfmx or dvips treats it downstream.

In practice, start with the default usemag. If geometry, image placement or PDF post-processing shows a real mismatch in dimensions, then try nomag*. Reproducibility — the same commands producing the same PDF — matters more than loading every option up front. And because a \mag-scaled document has to tell every downstream DVI tool that a magnification is in force, deciding the scaling method together with the build recipe saves trouble in collaborative work.

Does jsarticle need pLaTeX or upLaTeX?

Either works, because the class detects the engine itself. Write just \documentclass{jsarticle} and run upLaTeX, and the log says Class jsarticle Info: Autodetected engine: upLaTeX, switching the Japanese encodings to JY2/JT2; under pLaTeX it says Autodetected engine: pLaTeX. You still write uplatex (or platex, or autodetect-engine) as a class option for two reasons: it records the intent in the source, and it stops a mismatch from quietly producing a different layout. If the option and the actual engine disagree the class refuses to continue, with a message such as ! Class jsarticle Error: Option 'platex' is specified but you are running upLaTeX.

dvipdfmx, by contrast, is not a class option at all. Anything jsclasses does not consume is handed on as a global option to the packages that follow, and graphicx, color and hyperref read it to pick their driver. Writing it once in the brackets of \documentclass therefore saves writing it on each package — which is all the familiar [uplatex,dvipdfmx] really is.

Why an A5 document comes out as an A4 PDF

If you asked for a5paper and the PDF is A4, the cause is not the class but the fact that the DVI carries no paper size. On TeX Live 2024, \documentclass[uplatex,a5paper]{jsarticle} passed to dvipdfmx yields a PDF of 595.28 × 841.89 pt — A4 — because a DVI file has no notion of paper and dvipdfmx falls back to its own default. Add the class option papersize and a \special{papersize=...} is written out; the same source then comes out at 419.53 × 595.28 pt, which is A5. With tombow as well, the sheet grows by the trim marks: A5 becomes 563.53 × 739.28 pt, exactly one inch added on every side. LuaLaTeX (ltjsclasses, in the next section) writes the PDF directly and never hits this.

ltjsclasses: jsclasses moved to LuaLaTeX

ltjsclasses rewrites jsclasses for LuaLaTeX (LuaTeX-ja) and is maintained by the LuaTeX-ja project. It offers ltjsarticle, ltjsbook and ltjsreport (plus ltjspf and ltjskiyou), matching the jsclasses one for one, as the names suggest. The biggest difference is the scaling method. The LuaTeX manual states plainly that magnification with \mag is supported only in DVI output mode, so it is unavailable when LuaLaTeX writes PDF directly. ltjsclasses therefore makes nomag* the default, and if you pass usemag it warns This ltjsarticle cls does not support 'usemag' option, since LuaTeX does not support \mag in pdf output and falls back to nomag*.

The engine-related options behave differently too. Passing uplatex is an error (this class does not support 'uplatex' option), while autodetect-engine merely raises a warning and is ignored — reasonable, since there is only one engine here. The Japanese metric defaults to LuaTeX-ja’s standard jfm-ujis.lua; the ptexjis option switches to the same JIS metric jsclasses uses (jfm-jis.lua), and mingoth to the older jfm-min.lua. To change fonts, pair the class with luatexja-fontspec and name any OpenType font installed on the system.

% compile with lualatex; nomag* is already the default here
\documentclass[a4paper]{ltjsarticle}
\usepackage{luatexja-fontspec}
\setmainjfont{Noto Serif CJK JP}
\setsansjfont{Noto Sans CJK JP}
\begin{document}
こんにちは、\LaTeX！
\end{document}

BXjscls: one source, every engine

BXjscls (Takayuki Yato, known as ZR) widens the jsclasses design so it works on any engine, providing bxjsarticle, bxjsbook, bxjsreport and bxjsslide. The first thing to get right is how the engine is named. The engine is a bare class option, not engine= — one of lualatex, xelatex, pdflatex, platex, uplatex, latex, platex-ng, or autodetect-engine for automatic detection. Write engine=lualatex and the setting never arrives; the run stops with ! Class bxjsarticle Error: An engine option must be explicitly given.

% the engine is a bare option; ja= picks the Japanese driver
\documentclass[lualatex,ja=standard,a5paper]{bxjsarticle}
\begin{document}
こんにちは、\LaTeX！
\end{document}

% same body, different engine: swap the first option only
% \documentclass[uplatex,ja=standard,dvipdfmx,a5paper]{bxjsarticle}

The second key is ja= (formerly jadriver), which picks the Japanese-handling scheme from standard, minimal, modern and pandoc. This is where the real trap sits. Omit ja= and only (u)pLaTeX gets standard supplied for it; every other engine falls back to minimal with the warning The option 'ja' is MISSING!! So 'ja=minimal' is assumed as fallback, but such implicit setting is now DEPRECATED! Conversely, once you do write ja=, an explicit engine option becomes mandatory. In practice, then, the only safe form is to write the engine and ja= together, always. With ja=standard the class loads the right Japanese package for the engine in use.

The vocabulary for dimensions borrows from both jsclasses and jlreq. The Latin base size is base= (alias fontsize=), the Japanese size is jbase= (alias jafontsize=), and the Japanese scale ratio is scale= (alias jafontscale=), whose default is \jsScale = 0.924715 (\Cjascale points at the same value). The text block can be given as textwidth= and number-of-lines=, or with jlreq’s own spellings line_length= and number_of_lines=. Scaling is chosen with magstyle=, taking usemag, nomag or nomag*; from LuaTeX v0.87 onward, and on pTeX-ng, the default becomes nomag* and asking for magstyle=usemag stops with ! Class bxjsarticle Error: The engine does not support 'magstyle=usemag'.

Choosing between jsclasses, ltjsclasses and BXjscls

Pick the engine first, then the class that fits it. Even for the same “jsarticle look”, the class name changes with the processor. Swapping the class while leaving the engine alone is the way to lose Japanese handling altogether and watch the layout collapse.

• On pLaTeX/upLaTeX, use jsclasses. The standard choice when existing sources or submission rules fix the processor. Start from \documentclass[uplatex,dvipdfmx,papersize]{jsarticle}.
• Mostly LuaLaTeX? ltjsclasses. System OpenType fonts work directly and the PDF is written without a DVI stage; nomag* is the default and the paper size never goes missing.
• Don’t want to fix the engine, or shipping the source to others? BXjscls. Change two things — the engine name and ja= — and the same file moves between pdfLaTeX, XeLaTeX, LuaLaTeX and (u)pLaTeX.
• Want the text block specified in numbers? jlreq. A separate lineage from the js family, where line length, line count and margins are designed against the standard.

Confirm the route in the log

Because engine and class come as a pair in the js family, the first lines of the .log tell you whether the document was set by the route you intended. In collaboration or CI, check not that a PDF appeared but that the PDF came out of the intended route. Ideally the build command, the \documentclass line and the README all name the same thing.