DEV Community: 川口晃世（Kosei Kawaguchi）

I Built a Read-Only MCP Server for Japanese LaTeX Documents

川口晃世（Kosei Kawaguchi） — Fri, 14 Aug 2026 13:13:29 +0000

I wanted to give an AI a source document and say something ordinary like:

Turn this into a B5 Japanese lecture note. Keep the definitions precise, add two worked examples, compile it, and show me the finished pages.

The difficult part was not persuading the model to emit LaTeX. The difficult part was making the whole workflow repeatable: choosing a document structure, keeping Japanese typesetting stable, checking that every exercise has an answer, compiling locally, reading the log, and inspecting the rendered pages.

So I built TeX64, a free, open-source MCP server that gives Claude and Codex a reusable Japanese LuaLaTeX document system. (The repository retains the project's original texmcp name.)

This is an example of the output produced from one natural-language request:

The design: guidance on the server, execution on your machine

TeX64 is intentionally not a remote LaTeX compiler. Its six public tools are read-only. They return style files, document rules, scaffolds, checks, known issues, and compilation instructions as text. One of those tools, check_document, receives the .tex source for transient structural processing; the service does not persist it. Compilation and generated files stay on the client machine.

The connected AI client does the stateful work on your machine:

Your request
    ↓
Claude or Codex
    ↓  reads styles, rules, and scaffolds through MCP
TeX64 (read-only, stateless)
    ↓
Claude or Codex writes .tex/.sty files locally
    ↓
Local TeX Live compiles the PDF
    ↓
The agent renders pages to images, inspects them, and repairs problems

This split is important. A hosted service does not need permission to write into your project or run arbitrary TeX jobs. Meanwhile, the AI can use the tools it already has for editing files, running latexmk, reading logs, and checking page images.

What the MCP server provides

TeX64 currently exposes six tools:

Tool	What it returns
`get_style_files`	Japanese study-note or report styles, an annotated skeleton, and design notes
`doc_types`	Six document structures and their editing rules
`scaffold_document`	A compilable `.tex` scaffold for the selected document type
`check_document`	Structural checks, such as problem/answer pairing and numbering
`known_issues`	A searchable list of troublesome LuaLaTeX, `jlreq`, and LuaTeX-ja combinations
`compile_guide`	A local build, repair, and visual-inspection procedure for the AI agent

The six document types are lecture notes, exam summaries, exercise sets, past-exam collections, language notes, and compact short-answer sheets. Each type defines an expected section order, editing rules, automatic checks, and items that still require visual or human review.

For example, an exercise set is expected to place each solution immediately after its problem, number problems without gaps, state the relevant formulas before the questions, and include the important intermediate steps rather than only final answers.

Install it in one command

You do not need to clone the repository or install an npm package to use the hosted server.

For Claude Code:

claude mcp add --transport http tex64 https://mcp.tex64.com/

For Codex:

codex mcp add tex64 --url https://mcp.tex64.com/

If you prefer to edit the Codex configuration directly, add this to ~/.codex/config.toml:

[mcp_servers.tex64]
url = "https://mcp.tex64.com"

The public endpoint does not require an account or API key.

These commands were verified with Claude Code 2.1.227 and Codex CLI 0.145.0 on August 14, 2026. Check the current client documentation if a future CLI release changes its MCP syntax.

Local requirements

The machine running your AI client needs:

TeX Live with lualatex and latexmk
an agent that can write project files and run local commands
optionally, Poppler's pdftoppm for turning PDF pages into images for visual inspection

TeX64 uses LuaLaTeX because Japanese documents need more than a generic pdflatex template. Its styles account for Japanese fonts, line breaking, page geometry, headings, boxes, and the interactions among jlreq, LuaTeX-ja, TikZ, and related packages.

Harano Aji is the safest font choice when portability matters because it is distributed with TeX Live. Other included profiles cover Hiragino, Yu, BIZ UD, Source Han, and IPAex fonts.

A complete first request

After connecting the server, try a prompt like this:

Create a B5 Japanese lecture note titled
「リーマン積分の定義と可積分条件」 from the material I provide.

Use the TeX64 lecture-note structure and the Harano Aji font profile.
Include the definitions before they are used, two worked examples,
and a short review section.

Save the source in a new local project, run the structural checks,
compile it with LuaLaTeX, render the pages to images, inspect the cover,
Japanese glyphs, headings, boxes, margins, and page breaks, and repair
any problems before showing me the PDF and previews.

The wording is deliberately about the document you want, not about internal style commands. The MCP tools give the agent the specialized implementation details.

Here is a content page from the resulting document:

And here is a page combining a theorem-style box, a warning, and a worked exercise:

Why structural checks matter

A PDF can compile successfully and still be a bad study document.

LaTeX will not tell you that problem 4 has no solution, that the numbering jumps from 6 to 8, that a formula is used before its variables are defined, or that an OCR-based language note no longer matches its sentence-by-sentence commentary.

check_document treats those as document-structure problems. The check is separate from compilation because a TeX engine and an editorial rule checker answer different questions:

Compilation: Is this valid TeX, and can it produce a PDF?
Structural checking: Does the document follow the rules of its intended form?
Visual inspection: Are glyphs, boxes, margins, headings, and page breaks actually correct on the rendered page?

TeX64's workflow requires all three.

Privacy and security boundaries

The public tools are annotated as read-only, non-destructive, and idempotent. The server does not write files, run LaTeX, or retain prompts, document source, generated files, or tool results. Infrastructure providers may still process transient network and security metadata needed to operate the service; see the privacy policy and terms of use.

There is one boundary worth stating precisely: when the client calls check_document, it sends the .tex source to the server for transient structural processing. The service does not persist it, but you still should not submit secrets or sensitive personal information. Compilation and generated files remain on the client machine.

You can also self-host the MIT-licensed server and enable bearer-token authentication if you need to control access.

Current limitations

TeX64 is deliberately opinionated:

It focuses on Japanese study materials and simple academic reports.
It requires a local TeX installation; the hosted server does not return a compiled PDF.
Its automatic checks cover known structural rules, not mathematical correctness.
Visual inspection is still required. A zero-error log is not proof of a good page.
The quality of the result depends on the connected agent actually following the compile-and-review loop.

That narrow scope is useful. Instead of trying to be a general document generator, TeX64 supplies a concrete system for one difficult class of documents and leaves the final execution visible and editable on the user's machine.

The source and self-hosting instructions are available on GitHub. The hosted endpoint is https://mcp.tex64.com/.

If you create Japanese notes with LaTeX, which document type should I add next?

Write Chemical Structural Formulas Faster in LaTeX with KKchemstruct

川口晃世（Kosei Kawaguchi） — Mon, 03 Aug 2026 07:22:09 +0000

Hi, I'm KKTeX. I build LaTeX tools for teaching materials.

If you typeset chemical structural formulas in LaTeX, chemfig is the standard choice. It is flexible enough to draw everything from benzene rings to reaction schemes, but repeating the same structures across a worksheet means repeatedly matching bond lengths, line widths, and double-bond spacing.

I made KKchemstruct to package those recurring settings and structures into short commands:

\KKbenzene[2=OH,3=COOH]                     % salicylic acid
\KKchemchain{H-O-S(\KKdative{2}O)(\KKdative{6}O)-O-H}
\KKscheme{\KKsalicylicacid\arrow{->[\ck{CH_3OH}][Esterification]}\KKmethylsalicylate}

This article focuses on using the package rather than its implementation.

What it does

Draw substituted benzene rings by numbered positions
Keep bond lengths and line widths consistent in condensed structural formulas
Assemble reaction schemes, branching reactions, and compound names
Add leaving-group marks, hydrogen bonds, and a cross for “no reaction”
Insert common compounds with a single command
Scale dimensions with the surrounding text by using em-based settings

The actual drawing is still handled by chemfig. When a prepared command is not enough, you can use ordinary chemfig syntax directly.

1. Install it

You need LuaLaTeX (recommended), or pLaTeX with dvipdfmx. The dependencies—chemfig, etoolbox, and xkeyval—are included in TeX Live.

Download KKchemstruct.sty from the GitHub repository and, for the simplest setup, put it next to your .tex file:

my-document/
├── main.tex
└── KKchemstruct.sty

Then add one line to the preamble:

\usepackage{KKchemstruct}

Here is a minimal example:

\documentclass[a4paper,11pt]{article}
\usepackage[margin=22mm]{geometry}
\usepackage{KKchemstruct}

\begin{document}

\begin{center}
  \KKname{\KKsalicylicacid}{Salicylic acid}
\end{center}

\end{document}

Compile it as usual:

lualatex -interaction=nonstopmode -halt-on-error main.tex

Documents using \KKchemmark or \KKhbond need two runs so that TikZ can resolve the node positions.

2. Draw substituted benzene rings by number

Use \KKbenzene and assign substituents to numbered positions:

\KKbenzene[2=OH,3=COOH]

Position 1 is at the top, and the numbers continue clockwise:

These three commands draw salicylic acid, terephthalic acid, and unsubstituted benzene:

\KKbenzene[2=OH,3=COOH]
\KKbenzene[1=COOH,4=COOH]
\KKbenzene[]

Subscripts such as COOCH_3 work directly:

\KKbenzene[2=OH,3=COOCH_3]

Use angle to rotate a ring and sep to change the side length for that ring only:

\KKbenzene[2=OH,angle=30,sep=1.0em]

If a substituent comes too close to an inner double bond, reverse the Kekulé pattern with kekule=b:

\KKbenzene[1=OH,kekule=b]

For a horizontally connected ring inside a line of text, use one of these commands:

Command	Purpose
`\KKphenylring`	An unsubstituted ring
`\KKphenyl{COOH}`	A substituent on the right
`\KKphenylene{SO_3H}`	Bonds on both sides, for inserting the ring into a chain

Their baselines are adjusted so that they do not excessively increase the line spacing.

3. Write condensed structural formulas

Pass chains of atom labels to \KKchemchain:

\KKchemchain{CH_2(-OH)-[6,1.15]CH(-OH)-[6,1.15]CH_2-OH}

The angle numbers follow chemfig's 45-degree system. These four cover many classroom formulas:

Value	Direction
`[0]`	right
`[2]`	up
`[4]`	left
`[6]`	down

The number after the angle is a length multiplier, so [6,1.15] means downward at 1.15 times the default length.

Common fragments have shorter commands:

\KKchemchain{R_1-C\KKcarbonyl-OH}
\KKchemchain{H-O-S(\KKdative{2}O)(\KKdative{6}O)-O-H}

Command	Result
`\KKcarbonyl`	Upward C=O
`\KKcarbonyldown`	Downward C=O
`\KKdative{angle}`	A coordinate bond such as S→O, P→O, or N→O

Rings and chains have separate commands because they need different spacing rules:

\KKbenzene and \KKchemring keep atom-center distances constant to preserve regular polygons.
\KKchemchain keeps the visible bond lines consistent, even after a wide label such as CH_2.

Choosing the appropriate command is often enough to make a page of formulas look much more uniform.

4. Insert common compounds with one command

Frequently used compounds already have named commands:

\KKsalicylicacid
\KKmethylsalicylate
\KKaspirin
\KKphthalicanhydride
\KKmaleicacid
\KKfumaricacid
\KKnitricacid
\KKsulfuricacid
\KKphosphoricacid
\KKglycerol
\KKtriglyceride{R_1}{R_2}{R_3}

Benzoic acid, phenol, all three phthalic-acid isomers, maleic anhydride, and more are also included. See the English manual for the full list.

Use \KKname to place a name below a structure:

\KKname{\KKaspirin}{Acetylsalicylic acid}

5. Build reaction schemes

Inside \KKscheme, arrange structures with chemfig's \arrow command:

\KKscheme{%
  \KKname{\KKsalicylicacid}{Salicylic acid}
  \arrow{->[\ck{CH_3OH}][Esterification]}
  \KKname{\KKmethylsalicylate}{Methyl salicylate}}

Arrow labels are not in math mode. Wrap formulas such as CH_3OH in \ck{...}:

\arrow{->[\ck{CH_3OH}][Esterification]}

The longer alias \KKchemformula{...} does the same thing.

For one substrate branching into two reactions, \KKbranchscheme takes seven arguments:

\KKbranchscheme
  {\KKname{\KKsalicylicacid}{Salicylic acid}}
  {\ck{CH_3OH}}{Esterification}
  {\KKname{\KKmethylsalicylate}{Methyl salicylate}}
  {\ck{(CH_3CO)_2O}}{Acetylation}
  {\KKname{\KKaspirin}{Acetylsalicylic acid}}

The order is: substrate, upper reagent, upper reaction name, upper product, lower reagent, lower reaction name, lower product.

6. Add annotations

To outline a leaving group, mark two atoms with @{name} and pass the names to \KKchemmark:

\KKchemchain{R-C\KKcarbonyl-@{s}OH}\ +\
\KKchemchain{@{e}H-O-R'}%
\KKchemmark{s}{e}

To draw an intramolecular hydrogen bond:

\KKbenzene[2=@{oh}OH,3=C@{co}OOH]%
\KKhbond{oh}{co}

To place a cross over a structure:

\KKchemcross{\KKphenol}

Because \KKchemmark and \KKhbond refer to TikZ nodes, compile twice:

lualatex -interaction=nonstopmode -halt-on-error main.tex
lualatex -interaction=nonstopmode -halt-on-error main.tex

7. Adjust bond lengths and line widths together

Change global dimensions with \KKchemsetup:

\KKchemsetup{
  ring sep=2.0em,
  bond width=0.09em,
  double bond sep=0.4em
}

Put the setup in a group when you want a local change:

\begingroup
  \KKchemsetup{ring sep=2.0em,bond width=0.09em}
  \KKsalicylicacid
\endgroup

% Back to the defaults here
\KKsalicylicacid

The dimensions are primarily expressed in em, so the structures follow surrounding size changes such as \small and \large.

8. Draw rings that do not have a prepared command

For fused rings and other special cases, pass raw chemfig syntax to \KKchemring:

\KKchemring[atom sep=1.75em]{%
  *6(=-*5(-C(=O)-O-C(=O)-)=-=-)}

KKchemstruct is not meant to hide chemfig. Its purpose is to standardize common settings and components: use short commands for repeated structures, and drop down to chemfig syntax only for the unusual parts.

Common pitfalls

Parentheses create branches

In chemfig, ( and ) are structural branch syntax. If you only want to display a molecular formula such as CH_3(CH_2)_{11}, use \ck{...} rather than passing it directly to \KKchemchain.

Wrap formulas in arrow labels with `\ck`

Unlike atom labels in a structure, reaction-arrow labels are not automatically typeset in math mode:

\arrow{->[\ck{H_2SO_4}][Heat]}

Compile annotations twice

The positions used by \KKchemmark and \KKhbond are not final on the first run. If an annotation is displaced even though compilation succeeds, run LaTeX again.

Use the ring and chain commands for their intended geometry

Use \KKbenzene or \KKchemring when a regular polygon matters, and \KKchemchain for a condensed structural formula. Some inputs compile with either command, but the spacing will differ.

License and dependencies

KKchemstruct is released under the MIT License. It uses the LPPL 1.3c-licensed chemfig for drawing, plus the LPPL-licensed etoolbox and xkeyval packages. These dependencies are loaded from your TeX installation; their code is not copied into KKchemstruct.

Start with four commands

KKchemstruct keeps chemfig's flexibility while making repeated classroom structures shorter and more consistent. These four commands are enough to get started:

\KKbenzene[2=OH,3=COOH]  % substituted benzene
\KKchemchain{...}        % condensed structural formula
\KKscheme{...}           % reaction scheme
\KKchemsetup{...}        % dimensions

When you need a structure that is not predefined, use chemfig syntax through \KKchemring or \KKchemchain. If the same structure keeps appearing, that is the right time to turn it into your own command.

How Classical Chinese Is Traditionally Annotated in Japan

川口晃世（Kosei Kawaguchi） — Sat, 01 Aug 2026 16:44:12 +0000

Hi, I'm KKTeX. I maintain TeX packages on CTAN, including gckanbun.

In Japan, Classical Chinese can be read through a traditional annotation system called kanbun kundoku. The Chinese text remains in place while tiny marks encode a Japanese reading.

What are the tiny marks?

Furigana are small kana showing Japanese pronunciation.
Okurigana add Japanese verb endings and grammatical particles.
Kaeriten, or "return marks," tell the reader when to reverse the order of characters.
A rereading character is read twice, with a different Japanese form each time.

The annotations are not decoration. Together they carry pronunciation, grammar, and reading order without rewriting the original text.

Typesetting it with TeX

gckanbun keeps the source editable while handling the delicate placement of all those marks. It supports LuaLaTeX and (u)pLaTeX, is included in TeX Live, and is released under the MIT License.

Two tools from the same desk

📘 Evolton turns a photo or screenshot of a mathematics problem into a polished, reference-book-style solution PDF.

✍️ MathHover opens a LaTeX panel beside your cursor and pastes the finished formula into the app you are already using. It is free and requires no account.

What is the most unusual writing or annotation system you have typeset with TeX?

Engineering a Japanese Exam-Prep Handout with LuaLaTeX and tcolorbox

川口晃世（Kosei Kawaguchi） — Thu, 30 Jul 2026 01:06:18 +0000

Measured headers, drawing layers, and page-break states for a dense three-page mathematics booklet.

Hi, I'm KKTeX. I publish LaTeX packages on CTAN and maintain a private toolkit for producing books and teaching materials.

In the shorter companion article, I treated a Japanese exam-preparation handout as information design. This article opens the implementation.

The result is a three-page LuaLaTeX document:

The design is original. Tetsuryokukai is a useful public reference point for Japan's highly selective juku—private after-school education—culture, but this is not a reproduction of its material, and I am not claiming that it uses TeX. The organization publicly describes itself as a University of Tokyo preparation school for students in six-year secondary programs (official profile). The wider social context is also substantial: the OECD describes private after-school lessons as a pervasive part of Japanese education (OECD overview).

The technical problem is independent of any one institution:

How do we build a compact visual language that remains stable when titles change, solutions grow, and boxes cross pages?

The frame grammar grows from two families in my private toolkit: ascolorbox4, which cuts a rule with its title and combines different rail styles, and later ornate-frame experiments with explicit corner geometry. I call this production variant the Rinceau Frame / 唐草額. It keeps the dotted outer boundary, title interruption, inward quarter-circle corners, and four terminals of ascolorbox4, then rebuilds the terminals as compact C-scroll and palmette ornaments. The result deliberately looks like a Western book frame, but the ornament remains outside the mathematics.

I will focus on four implementation decisions, followed by two editorial ones.

1. Model pedagogical roles, not appearances

The document does not contain a generic FancyBox. It contains components named after their jobs:

\LessonHeading{11}{LECTURE}{A Moving Minimum}

\begin{DrillBox}
  {PROBLEM 18}{Quadratic Optimization}[3]
  ...
\end{DrillBox}

\begin{StrategyBox}
  ...
\end{StrategyBox}

\begin{SolutionBox}{SOLUTION}
  ...
\end{SolutionBox}

\begin{KeyPointBox}{STRUCTURAL MAP / 見通し}
  ...
\end{KeyPointBox}

This matters when a book grows.

If an editor later decides that every strategy should use a left rule instead of a filled background, the content files do not change. If every problem needs a difficulty marker, the DrillBox interface already has one.

The markup carries semantics; the style file carries the visual system.

The implementation uses \DeclareTColorBox rather than a collection of copied \newtcolorbox definitions. Its xparse-style argument specification gives each component a small, explicit interface:

\DeclareTColorBox{DrillBox}{m m O{2} O{}}{
  ...
}

Here:

the first mandatory argument is the problem number;
the second is the topic;
the first optional argument selects the 基礎 / 標準 / 発展 level;
the final optional argument accepts ordinary tcolorbox overrides.

2. Preserve a grammar, not a screenshot

The design started by treating ascolorbox4 as a set of invariants:

the title cuts the top rail;
a dotted boundary sits outside a solid rail;
every corner turns through an inward quarter-circle;
every corner has a visible terminal.

For the Western vocabulary, I studied public-domain museum material rather than tracing a modern border. The Metropolitan Museum's ornamental designs show scrolling acanthus, palmettes, garlands, and pearl strips; Cooper Hewitt's catalog describes frame designs built from rinceaux, flowers, scrolls, shells, rosettes, and bead-like rails (Met example, Cooper Hewitt frame design, Cooper Hewitt ornament album). I reduced that vocabulary to one mirrored C-scroll and a three-leaf palmette small enough for a study booklet.

The title is attached to the frame instead of positioned with an absolute coordinate:

attach boxed title to top left={
  xshift=10mm,
  yshift=-\tcboxedtitleheight/2
},
boxed title style={
  colback=white,
  colframe=white,
  boxrule=0pt,
  left=2mm,
  right=2mm
},
borderline={.55pt}{2.7pt}{ehBlue,dotted},

The white title field is not a badge pasted over the frame. It is a controlled interruption: the solid and dotted rails disappear behind it, then resume at title.east.

The main rail is a single path:

\draw[ehAccent,line width=.72pt,
      line cap=round,line join=round]
  ([xshift=2mm]title.east|-frame.north east)
  --([xshift=-7mm]frame.north east)
  arc[start angle=180,end angle=270,radius=7mm]
  --([yshift=7mm]frame.south east)
  arc[start angle=90,end angle=180,radius=7mm]
  --([xshift=7mm]frame.south west)
  arc[start angle=0,end angle=90,radius=7mm]
  --([yshift=-7mm]frame.north west)
  arc[start angle=270,end angle=360,radius=7mm]
  --([xshift=-2mm]title.west|-frame.north west);

A second, thinner antique-gold path is inset by 2 mm. That pair reads as picture-frame molding. The outer dotted borderline preserves the lighter rail contrast of ascolorbox4.

This follows a principle I use throughout my Japanese Qiita articles:

If an ornament depends on a box, derive it from the box. If it depends on a title, derive it from the title.

The geometry can therefore survive a new title, a taller solution, or a different page width.

3. Put each line on the correct drawing layer

An advanced tcolorbox is easier to reason about as a layer stack:

finish
overlay
content
underlay
interior
frame
shadow

The title box has its own corresponding layers.

The navy rail, gold inset molding, and four ornaments belong in the underlay: they must sit below the mathematics. The difficulty marker belongs in an overlay, because its white field intentionally knocks out a small portion of the top rail.

\DeclareTColorBox{DrillBox}{m m O{2} O{}}{
  enhanced,
  breakable,
  empty,
  sharp corners,
  title={#1\hspace{2.2mm}
    {\color{ehGold}/}\hspace{2.2mm}#2},
  left=9mm,
  right=9mm,
  top=5mm,
  bottom=5mm,
  borderline={.55pt}{2.7pt}{ehBlue,dotted},
  underlay unbroken={\ehFrameUnbroken},
  underlay first={\ehFrameFirst},
  underlay middle={\ehFrameMiddle},
  underlay last={\ehFrameLast},
  overlay unbroken and first={
    % the 基礎 / 標準 / 発展 marker
  }
}

empty removes the default skin. The component then draws only the parts of the selected grammar:

one rounded solid rail;
one thinner inset molding;
one dotted offset boundary;
one title interruption;
four C-scroll and palmette terminals;
a 基礎 / 標準 / 発展 level chip.

This avoids a common failure mode: drawing a custom frame on top of a default frame and then chasing tiny disagreements in corner radius and line position.

4. A breakable box has four drawings

The solution box is allowed to grow. Therefore it cannot have one frame path.

tcolorbox exposes four states:

unbroken  one-page box
first     first fragment of a broken box
middle    intermediate fragment
last      final fragment

The fragment drawings are assigned accordingly:

underlay unbroken={\ehFrameUnbroken},
underlay first={\ehFrameFirst},
underlay middle={\ehFrameMiddle},
underlay last={\ehFrameLast},

The first fragment draws the title, top corners, and vertical continuations. A middle fragment draws only two pairs of vertical rails. The last fragment draws the bottom corners and closes the frame.

\newcommand{\ehFrameLast}{%
  \draw[ehAccent,line width=.72pt,
        line cap=round,line join=round]
    (frame.north east)
    --([yshift=7mm]frame.south east)
    arc[start angle=90,end angle=180,radius=7mm]
    --([xshift=7mm]frame.south west)
    arc[start angle=0,end angle=90,radius=7mm]
    --(frame.north west);
  \ehFrameBottomCorners
}

The direction of those arcs matters. The last fragment is traced from the right edge to the left edge, matching the angle sequence used by the original ascolorbox4. Reversing the path without also reversing the angles makes the bottom rail leave the corner diagonally—a defect that can hide in a one-page test and appear only after a forced page break.

On the middle fragment, there are no fake corners and no repeated ornament. Treating the four states as separate drawings is not an optimization. It is the correct model.

5. Keep visual weight scarce

The page uses eight named colors, each with a narrow role:

\definecolor{ehInk}{HTML}{202428}
\definecolor{ehMuted}{HTML}{667085}
\definecolor{ehLine}{HTML}{AEB5BF}
\definecolor{ehPale}{HTML}{F3F4F6}
\definecolor{ehAccent}{HTML}{34435F}
\definecolor{ehBlue}{HTML}{8292AE}
\definecolor{ehGold}{HTML}{A37B3C}
\definecolor{ehVermilion}{HTML}{B4442E}

ehInk carries mathematics and hard structure;
ehAccent carries navigation and the main frame rail;
ehBlue carries the dotted offset boundary;
ehGold carries the inset molding and palmette leaves;
ehLine remains available for quiet separators;
ehPale is limited to secondary label fields.
ehMuted carries running metadata;
ehVermilion appears only in advanced-level and answer signals.

The point is not to make every component visibly different. The point is to make different components recognizable without making the page compete with itself.

6. Design the return visit

The third PDF page is a review page, not another full solution.

Its prompts ask:

What does “for every real x” become?
Which variable is currently being optimized?
Do strict inequalities exclude the endpoints?
Is the claimed maximum attained?

This is a typesetting decision as much as a teaching decision. A weekly booklet is a retrieval system. Numbering, labels, and stable component shapes help a student find a previous method quickly.

That is why a dense handout can benefit from stronger visual structure than a conventional textbook chapter.

Compilation environment

I compiled the specimen with LuaLaTeX and ltjsarticle. When recreating the example from these excerpts, place the component definitions in exam-handout.sty beside technical-handout.tex, then run:

lualatex -interaction=nonstopmode -halt-on-error technical-handout.tex

The example uses ltjsarticle, matching my Japanese material workflow. The visible content is mostly English, but the component labels can contain Japanese micro-labels such as 要点 and 見通し without changing the geometry.

The box system is built on tcolorbox, whose current CTAN release supports framed boxes, split content, and breakable material.

Two tools from the same desk

Disclosure: these are my projects.

Evolton converts a photographed mathematics problem into a polished solution PDF. It is useful when the finished explanation needs the visual discipline of a reference book.

MathHover keeps formula entry close to the cursor, so mathematical writing does not have to pause for a separate editor.

The deeper lesson is simple: a teaching-material style should not be a collection of attractive boxes. It should be a small visual language whose components survive the text ranges and page lengths they were designed for—and expose clear guard rails when content exceeds them.

What Japan's Elite Cram-School Handouts Teach Us About Page Design

川口晃世（Kosei Kawaguchi） — Thu, 30 Jul 2026 01:03:44 +0000

A one-page mathematics handout can tell a student what to do before the teacher says a word.

Hi, I'm KKTeX. I publish LaTeX packages on CTAN and build typesetting tools for education in Japan.

Japan has a large system of private after-school education known as juku. One unusually intensive public example is Tetsuryokukai. According to its official profile, it is a six-year secondary-school program specializing in preparation for the University of Tokyo and was founded in 1983 by students and graduates of the university's medical and law faculties (official profile).

The institution is interesting. But for a typesetter, the more interesting question is smaller:

What does an intensive mathematics handout ask the page itself to do?

This is my answer, built from scratch in LuaLaTeX:

This is not a reproduction of a Tetsuryokukai handout, and I am not claiming that the organization uses TeX. It is an original reconstruction of the broader visual grammar surrounding high-density Japanese exam preparation.

The page gives instructions

Look at the page before reading the mathematics.

The dark 07 badge answers: Where am I?

The segmented header answers: What kind of object is this?

The right-hand 標準 (standard) chip answers: How demanding is it?

STRATEGY answers: What should I notice before calculating?

SOLUTION answers: How do I verify the argument?

KEY POINT / 要点 answers: What should I retain for the next problem?

QUICK RETRIEVAL answers: Can I rebuild it later without rereading?

None of these elements is merely decorative. Together they turn a page into a sequence of learning actions:

locate;
classify;
calibrate;
choose a method;
verify;
remember;
retrieve.

That sequence is especially useful in a weekly booklet. Students do not read such material once from beginning to end. They return to it before a test, search for a familiar problem type, cover the solution, and try again.

Dense does not have to mean noisy

An intensive handout needs to carry a great deal of information, but visual weight must remain scarce.

In this design:

black is reserved for mathematics and the main structure;
blue-slate identifies navigation;
a dotted outer boundary and a solid inner rail establish each teaching object;
a thin antique-gold inset reads like the molding inside a picture frame;
compact C-scrolls and shell-like palmettes terminate the four corners;
pale gray is reserved for secondary labels.

The result is dense, but it still has a reading order. I call this production variant the Rinceau Frame / 唐草額. Its structure comes directly from my ascolorbox4 experiments: the title interrupts the top rail, a dotted boundary sits outside it, and inward quarter-circles turn all four corners. I then rebuilt those corner terminals with the grammar of a Western picture frame—C-scrolls, a small palmette, and a second molding line—without letting the ornament enter the reading column.

The most important design decision is not the color. It is placing the strategy before the full solution. A student first receives a way into the problem, not an answer to copy.

The TeX idea

The page uses one reusable component for each pedagogical role:

\LessonHeading{07}{LESSON}{A Parameter and a Quadratic}

\begin{DrillBox}
  {EXAMPLE 12}{Positive for Every Real \textit{x}}[2]
  ...
\end{DrillBox}

\begin{StrategyBox}
  ...
\end{StrategyBox}

\begin{SolutionBox}{SOLUTION}
  ...
\end{SolutionBox}

The content says what an object means. The style file decides how that meaning should look.

That separation is what makes TeX unusually well suited to systematic teaching materials: the visual language can remain stable across hundreds of pages.

Two tools from the same desk

Disclosure: these are my projects.

Evolton turns a photograph or screenshot of a mathematics problem into a polished solution PDF. It treats the answer as a teaching object, not merely a block of correct text.

MathHover opens a LaTeX panel beside the cursor and inserts the finished formula into the application you are already using.

The next article opens the same component system and explains the engineering behind title-cut rails, ornamental corner geometry, and page-break states in a longer specimen.

Build a Ghost-Number Section Heading in LaTeX

川口晃世（Kosei Kawaguchi） — Tue, 28 Jul 2026 11:24:22 +0000

Hi, I'm KKTeX. I publish LaTeX packages on CTAN and build typesetting tools for education in Japan.

In many Japanese mathematics books, a section heading is not merely larger text. It is page architecture: number, hierarchy, and reading rhythm.

This article makes one heading with a pale “ghost number” and a restrained blue rule.

The drawing

\usepackage{tikz}

\definecolor{qink}{HTML}{0F172A}         % slate-900
\definecolor{qline}{HTML}{CBD5E1}        % slate-300
\definecolor{qaccent}{HTML}{38BDF8}      % sky-400
\definecolor{qaccentDark}{HTML}{0369A1}  % sky-700

\newcounter{booksection}

\NewDocumentCommand{\BookSection}{m}{%
  \refstepcounter{booksection}%
  \par\medskip\noindent
  \begin{tikzpicture}
    \useasboundingbox
      (0,0) rectangle (\linewidth,-2.7\baselineskip);

    \node[
      anchor=base west,text=qline,
      font=\sffamily\bfseries
            \fontsize{40pt}{40pt}\selectfont
    ] at (0,-1.55\baselineskip)
      {\ifnum\value{booksection}<10 0\fi
       \arabic{booksection}};

    \node[
      anchor=base west,text=qaccentDark,
      font=\sffamily\scriptsize\bfseries
    ] at (26mm,-.55\baselineskip) {LESSON};

    \node[
      anchor=base west,text=qink,
      font=\sffamily\Large\bfseries
    ] at (26mm,-1.45\baselineskip) {#1};

    \draw[qaccent,line width=.8pt]
      (26mm,-2.2\baselineskip)
      -- (.78\linewidth,-2.2\baselineskip);
    \draw[qline,line width=.8pt]
      (.78\linewidth,-2.2\baselineskip)
      -- (\linewidth,-2.2\baselineskip);

    \foreach \x in {0,1,2}{
      \fill[qaccentDark]
        ([xshift=-\x*3.4mm]\linewidth,
          -.55\baselineskip)
        circle[radius=1.2pt];
    }
  \end{tikzpicture}
  \par\smallskip
}

Use it once per section:

\BookSection{Completing the Square}

Compilation note: my figure source uses ltjsarticle with LuaLaTeX, matching my Japanese material workflow. The heading itself also works inside an ordinary article document.

The page gets a clear hierarchy, ordered here by visual importance:

The dark title carries meaning.
The small LESSON label identifies the component.
The pale number helps navigation without competing for attention.

The component-system idea comes from my private book-production toolkit, kkbookmaker, but the ghost-number design is new for this article.

Why the number is large but pale

Japanese reference books often expose structure more aggressively than ordinary prose books. A student may jump between an example, its solution, a related exercise, and a later review page. Strong numbering helps that movement, but a dark oversized number would compete with the mathematics.

The ghost number solves both problems: it is large enough to find quickly and light enough to sit behind the reading hierarchy. The title remains the darkest element, while the small LESSON label tells the reader what kind of marker this is. This is navigation, not decoration.

Two tools from the same desk

Disclosure: I'm promoting both projects in this section.

Evolton turns a photo or screenshot of a mathematics problem into a reference-book-style worked-solution PDF. Its database lets you browse university entrance-exam material by university, faculty, and year.

MathHover opens a LaTeX input panel beside your cursor, then pastes the finished formula into your current app. It is free to use and requires no account.

Next in the series: Japanese-born CTAN packages for answer fields, Kanbun, underlining, and more.

Build a Star-Rated Example Box in LaTeX

川口晃世（Kosei Kawaguchi） — Tue, 28 Jul 2026 11:22:56 +0000

Hi, I'm KKTeX. I publish LaTeX packages on CTAN and build typesetting tools for education in Japan.

A Japanese exam-prep page often tells you three things before the problem begins: its number, its topic, and its difficulty. That compact metadata turns a dense booklet into something students can scan and revisit.

Today we will make one component: a worked-example box with two measured header segments and a three-star difficulty scale.

The locator above the box and the bold problem statement are page content from my figure source, not automatic parts of ExampleBox.

Measure first, then draw

\usepackage[most]{tcolorbox}
\usetikzlibrary{shapes.geometric}

\definecolor{qink}{HTML}{0F172A}         % slate-900
\definecolor{qline}{HTML}{CBD5E1}        % slate-300
\definecolor{qaccentDark}{HTML}{0369A1}  % sky-700
\definecolor{qaccentPale}{HTML}{E0F2FE}  % sky-100

\newlength{\ExampleHeadHeight}
\newlength{\ExampleTitleWidth}
\newlength{\ExampleTopicWidth}
\newlength{\ExampleTopicX}
\setlength{\ExampleHeadHeight}{6.2mm}

\newcommand{\ExampleSegmentFont}{%
  \sffamily\bfseries\fontsize{8.5}{10}\selectfont
}

\DeclareTColorBox{ExampleBox}{ m m o O{2} O{} }{%
  enhanced,
  empty,
  sharp corners,
  before={%
    \def\ExampleTitleText{%
      #1%
      \IfValueT{#3}{%
        \hspace{1.5mm}{\fontsize{6}{7}\selectfont #3}%
      }%
    }%
    \settowidth{\ExampleTitleWidth}{%
      \ExampleSegmentFont\ExampleTitleText
    }%
    \settowidth{\ExampleTopicWidth}{%
      \ExampleSegmentFont #2
    }%
    \setlength{\ExampleTopicX}{%
      \dimexpr\ExampleTitleWidth+7.7mm\relax
    }%
    \par\noindent
  },
  enlarge top by=\ExampleHeadHeight,
  left=5mm, right=3mm, top=3.5mm, bottom=3.5mm,
  underlay unbroken={%
    % Measured title segment
    \fill[qaccentDark]
      ([yshift=\ExampleHeadHeight]frame.north west)
      -- ([xshift=\dimexpr\ExampleTitleWidth+6.5mm\relax,
           yshift=\ExampleHeadHeight]frame.north west)
      -- ([xshift=\dimexpr\ExampleTitleWidth+6.5mm
                         -.5\ExampleHeadHeight\relax]
           frame.north west)
      -- (frame.north west)
      -- cycle;
    \node[anchor=west,inner sep=0pt,text=white,
          font=\ExampleSegmentFont]
      at ([xshift=2.5mm,yshift=.5\ExampleHeadHeight]
          frame.north west)
      {\ExampleTitleText};

    % Measured topic segment with the same shear
    \fill[qaccentPale]
      ([xshift=\ExampleTopicX,yshift=\ExampleHeadHeight]
        frame.north west)
      -- ([xshift=\dimexpr\ExampleTopicX+\ExampleTopicWidth
                         +5mm\relax,
           yshift=\ExampleHeadHeight]frame.north west)
      -- ([xshift=\dimexpr\ExampleTopicX+\ExampleTopicWidth
                         +5mm-.5\ExampleHeadHeight\relax]
           frame.north west)
      -- ([xshift=\dimexpr\ExampleTopicX
                         -.5\ExampleHeadHeight\relax]
           frame.north west)
      -- cycle;
    \node[anchor=west,inner sep=0pt,text=qink,
          font=\ExampleSegmentFont]
      at ([xshift=\dimexpr\ExampleTopicX+2.5mm
                         -.25\ExampleHeadHeight\relax,
           yshift=.5\ExampleHeadHeight]frame.north west)
      {#2};

    % Right-anchored stars; #4 is the filled count.
    \foreach \i in {1,2,3}{%
      \ifnum\i>#4\relax
        \node[star,star points=5,star point ratio=2.2,
          minimum size=2.6mm,inner sep=0pt,
          fill=white,draw=qline,line width=.4pt]
          at ([xshift={-2.3mm-(3-\i)*3.4mm},
               yshift=.5\ExampleHeadHeight]
               frame.north east) {};
      \else
        \node[star,star points=5,star point ratio=2.2,
          minimum size=2.6mm,inner sep=0pt,
          fill=qaccentDark,draw=qaccentDark,line width=.4pt]
          at ([xshift={-2.3mm-(3-\i)*3.4mm},
               yshift=.5\ExampleHeadHeight]
               frame.north east) {};
      \fi
    }%

    % Open frame: a strong spine and three quiet rules.
    \draw[qink,line width=1.5pt]
      ([xshift=.75pt,yshift=\ExampleHeadHeight]
        frame.north west)
      -- ([xshift=.75pt]frame.south west);
    \draw[qink,line width=.5pt]
      ([yshift=\ExampleHeadHeight]frame.north west)
      -- ([yshift=\ExampleHeadHeight]frame.north east);
    \draw[qink,line width=.5pt]
      (frame.north west) -- (frame.north east);
    \draw[qink,line width=.5pt]
      (frame.south west) -- (frame.south east);
  },
  #5
}

The normal call is portable:

\begin{ExampleBox}{EXAMPLE 07}{Quadratic Inequalities}
Find all real \(a\) such that
\[
  x^2+ax+a+3>0
\]
for every real \(x\).
\end{ExampleBox}

The first optional argument adds a LuaLaTeX Japanese label; the second sets the filled-star count:

\begin{ExampleBox}
  {EXAMPLE 07}{Quadratic Inequalities}[例題][2]
  ...
\end{ExampleBox}

The important rule is simple: measure with the exact font used to draw. Both polygons then grow with their text, while \ExampleHeadHeight controls the band and both parallel shears.

Why the strategy appears before the answer

Japanese self-study books often separate the way in from the full solution. For example, the exam-prep series described by Suken Publishing places a 指針 (strategy) before each solution and uses side notes for formulas and extra explanation (publisher release).

That is why the preview says STRATEGY before calculating (D<0). The line is ordinary content inside the same box—not a second component.

This measured-header pattern grew from KKfbox11 and KKfbox8 in my private kkbookmaker toolkit. I kept the genre's information hierarchy but replaced its proportions, colors, glyph stars, and frame construction.

This design and its proportions are new for this series. It is not affiliated with, and does not copy, Suken Publishing, a particular textbook series, or any school.

Two tools from the same desk

Disclosure: I'm promoting both projects in this section.

Evolton turns a photo or screenshot of a mathematics problem into a polished, reference-book-style solution PDF. Its database is browsable by university, faculty, and year.

MathHover opens a LaTeX panel beside your cursor and pastes the finished formula into the app you are already using. It is free and requires no account.

Next: a section heading with a ghost number.

Build a Chamfered Key-Point Box in LaTeX

川口晃世（Kosei Kawaguchi） — Tue, 28 Jul 2026 11:21:41 +0000

Hi, I'm KKTeX. I publish LaTeX packages on CTAN and build typesetting tools for education in Japan.

Japanese study guides use small, repeated labels—要点 (key point), 例題 (worked example), 指針 (strategy)—as navigation. The frame is not merely decoration: it tells the learner what kind of reading to do.

Today we will make one component: a print-friendly key-principle box with a title tab whose chamfer stays at 45 degrees.

The small locator above the box is page context from my figure source, not part of the component.
The gray closing sentence and right-aligned Japanese tag are ordinary box content, not generated automatically by KeyPointBox.

The component

\usepackage[most]{tcolorbox}

\definecolor{qink}{HTML}{0F172A}         % slate-900
\definecolor{qline}{HTML}{CBD5E1}        % slate-300
\definecolor{qaccentDark}{HTML}{0369A1}  % sky-700
\definecolor{qaccentPale}{HTML}{E0F2FE}  % sky-100

\DeclareTColorBox{KeyPointBox}{ m o O{} }{%
  enhanced,
  empty,
  sharp corners,
  arc=0pt,
  outer arc=0pt,
  left=5mm, right=5mm, top=4mm, bottom=4mm,
  enlarge top by=6mm,
  attach boxed title to top left={xshift=0mm,yshift=0mm},
  boxed title style={
    empty,
    arc=0pt,
    outer arc=0pt,
    boxrule=0pt,
    top=1.4mm, bottom=1.4mm,
    left=3mm, right=3mm,
  },
  fonttitle=\sffamily\bfseries\fontsize{8.5}{10}\selectfont,
  coltitle=white,
  title={%
    #1%
    \IfValueT{#2}{%
      \hspace{2mm}\textcolor{white}{\rule{.4pt}{2.2mm}}%
      \hspace{2mm}{\fontsize{6}{7}\selectfont
        \textcolor{qaccentPale}{#2}}%
    }%
  },
  underlay boxed title={%
    \fill[qink]
      (title.north west) rectangle (title.south east);
    \fill[qaccentDark]
      (title.north east)
      -- +(\dimexpr\tcboxedtitleheight-.6mm\relax,
           -\dimexpr\tcboxedtitleheight-.6mm\relax)
      -- (title.south east)
      -- cycle;
    \draw[qink,line width=.5pt]
      ([xshift=\dimexpr\tcboxedtitleheight-.6mm\relax]
        title.south east)
      -- (title.south east-|frame.east);
  },
  underlay unbroken={%
    \draw[qink,line width=.5pt]
      (title.south west-|frame.west)
      -- (frame.south west)
      -- (frame.south east)
      -- (title.south east-|frame.east);
    \draw[qline,line width=.3pt]
      ([xshift=-1.2pt]title.south east-|frame.east)
      -- ([xshift=-1.2pt,yshift=1.2pt]frame.south east)
      -- ([xshift=1.2pt,yshift=1.2pt]frame.south west);
  },
  #3
}

The portable call contains only Latin text:

\begin{KeyPointBox}{KEY PRINCIPLE}
For positive reals \(a,b\), the arithmetic mean is at least
the geometric mean.
\[
  \frac{a+b}{2}\geq\sqrt{ab}
  \qquad (a>0,\ b>0)
\]
Equality holds if and only if \(a=b\).
\end{KeyPointBox}

With LuaLaTeX and luatexja, add the optional Japanese micro-label:

\begin{KeyPointBox}{KEY PRINCIPLE}[要点]
  ...
\end{KeyPointBox}

The useful trick

Inside underlay boxed title, \tcboxedtitleheight is the measured title height. I use \tcboxedtitleheight-.6mm for both the horizontal run and vertical drop of the blue tail. Equal run and drop give a 45-degree chamfer even when the title font changes.

The rest stays quiet: white paper, one dark frame, one pale inner rule, and a single accent. Japanese publishers explicitly describe using frames to separate important material while limiting dark colors and the total number of colors to reduce visual stimulation (Tokyo Shoseki, PDF).

The engineering idea grew from ascolorbox patterns in my private kkbookmaker toolkit. This design is not affiliated with Tokyo Shoseki; its proportions are new for this series and do not copy any particular publisher or school.

Two tools from the same desk

Disclosure: I'm promoting both projects in this section.

Evolton turns a photo or screenshot of a mathematics problem into a polished, reference-book-style solution PDF—useful when you want the answer to look teachable, not merely correct.

MathHover opens a LaTeX panel beside your cursor and pastes the finished formula into the app you are already using. It is free and requires no account.

Next: a worked-example header that measures its own segments.

DEV Community: 川口晃世（Kosei Kawaguchi）

I Built a Read-Only MCP Server for Japanese LaTeX Documents

The design: guidance on the server, execution on your machine

What the MCP server provides

Install it in one command

Local requirements

A complete first request

Why structural checks matter

Privacy and security boundaries

Current limitations

Write Chemical Structural Formulas Faster in LaTeX with KKchemstruct

What it does

1. Install it

2. Draw substituted benzene rings by number

3. Write condensed structural formulas

4. Insert common compounds with one command

5. Build reaction schemes

6. Add annotations

7. Adjust bond lengths and line widths together

8. Draw rings that do not have a prepared command

Common pitfalls

Parentheses create branches

Wrap formulas in arrow labels with \ck

Compile annotations twice

Use the ring and chain commands for their intended geometry

License and dependencies

Start with four commands

How Classical Chinese Is Traditionally Annotated in Japan

What are the tiny marks?

Typesetting it with TeX

Two tools from the same desk

Engineering a Japanese Exam-Prep Handout with LuaLaTeX and tcolorbox

1. Model pedagogical roles, not appearances

2. Preserve a grammar, not a screenshot

3. Put each line on the correct drawing layer

4. A breakable box has four drawings

5. Keep visual weight scarce

6. Design the return visit

Compilation environment

Two tools from the same desk

What Japan's Elite Cram-School Handouts Teach Us About Page Design

The page gives instructions

Dense does not have to mean noisy

The TeX idea

Two tools from the same desk

Build a Ghost-Number Section Heading in LaTeX

The drawing

Why the number is large but pale

Two tools from the same desk

Build a Star-Rated Example Box in LaTeX

Measure first, then draw

Why the strategy appears before the answer

Two tools from the same desk

Build a Chamfered Key-Point Box in LaTeX

The component

The useful trick

Two tools from the same desk

Wrap formulas in arrow labels with `\ck`