Writing Japanese in LaTeX : Part 3 – Simple documents

After the bit technical part on characters and encodings, we continue this tutorial on writing Japanese in LaTeX today with a bit more hands-on practice, namely writing simple hello-world-style documents for different engines/packages.

Today’s part will also include a bit on how to setup your TeX environment using TeX Live to work with Japanese documents.

Getting a Japanese TeX environment

In the following I will assume that a TeX system similar to TeX Live 2014 is installed. To achieve this, there are the following options:

• Upstream TeX Live installation – the full installation procedure is described in the TeX Live documentation, chapter 3 on Installation. We also provide quick installation notes for Linux and Windows. For MacOS, it is recommended to install MacTeX, which is based on TeX Live.
• Distribution’s TeX Live – here it strongly depends on the actuality of your distribution. If you are using Debian/jessie or Debian/sid, you are fine, as they contain already TeX Live 2014. Call apt-get install texlive-full and wait ;-). For other distributions (Fedora, RedHat, SuSE) you have to check the current level. Don’t be surprised if not all my examples work as expected when using older TeX installations.
• W32TeX – there is a version closely related and packages specifically for Windows by Akira KAKUTO, called W32TeX. It provides probably the most complete Japanese TeX setup, but I don’t have personal experience.
• Other TeX distributions – MikTeX is the other big player in the world of TeX Distributions. But due to the differences in packaging and support scripts, several of my advices will not work, in particular everything related to updmap which is a completely different beast in MikTeX. That said, it is still an excellent distribution for Windows, well integrated.

My recommendation is: If your distribution is recent enough to provide a TeX Live 2014 based TeX installation, use that one. Otherwise use TeX Live from TUG, including MacTeX on Mac.

Sample documents

So let us dive into the real. What I want to typeset now with various engines and packages, is a simple Hello World like document. Of course no “Hello World” because we wouldn’t see the Japanese characters in all their beauty. So the text I want to do is:

\begin{document}
\LaTeX で日本語を書きましょう！
\end{document}

But before we dive into the actual examples, one warning again about encodings: When saving files, please make sure that they are saved in the proper encoding:

• Unix and Mac systems: save them as UTF-8, in all cases
• Windows: for pLaTeX save them as ShiftJIS, otherwise as UTF-8

The reason is that pTeX expects as default ShiftJIS on Windows, and UTF-8 on all other systems. You can save everything as UTF-8 on Windows, too, but then you have to tell ptex with the command line switch -kanji utf8 that you are using it.

pLaTeX – upLaTeX

In the simplest case, just throw in a documentclass statement and you are settled:

\documentclass{article}
\begin{document}
\LaTeX で日本語を書きましょう！
\end{document}

Save this a hello-ptex.tex, and make sure that the correct encoding (see above) is used. Then run it through platex. You should see an output similar to this, when running on a system with utf-8 locale:

$ platex hello-ptex.tex 
This is e-pTeX, Version 3.14159265-p3.5-130605-2.6 (utf8.euc) (TeX Live 2014) (preloaded format=platex)
 restricted \write18 enabled.
entering extended mode
(./hello-ptex.tex
pLaTeX2e <2006/11/10> (based on LaTeX2e <2014/05/01> patch level 0)
Babel <3.9k> and hyphenation patterns for 79 languages loaded.
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/size10.clo)) (./hello-ptex.aux
) [1] (./hello-ptex.aux) )
Output written on hello-ptex.dvi (1 page, 384 bytes).
Transcript written on hello-ptex.log.

On Windows the output will be very similar, only that in the very first line you will not have utf8.euc, but sjis written in the parenthesis after the version number.

As you see, what is generated is a DVI file. Now, do NOT try to convert this to PostScript with dvips, it will work in some way, but the resulting PostScript file cannot be displayed.

Warning: When converting DVI files generated by ptex, uptex and related, always use dvipdfmx to generate a PDF.

So let us do that:

$ dvipdfmx hello-ptex.dvi 
hello-ptex.dvi -> hello-ptex.pdf
[1]
7636 bytes written

After this you can open the resulting pdf file in any viewer (evince, atril, okular, xpdf) and it should show you the output similar to this one:

If the fonts looks slighly different, don’t wonder for now, I will explain this later on (font embedding and selection). But you should see the Japanese characters, otherwise something went wrong.

Now the very same procedure will work with uptex, too:

$ uplatex hello-ptex.tex 
This is e-upTeX, Version 3.14159265-p3.5-u1.11-130605-2.6 (utf8.uptex) (TeX Live 2014) (preloaded format=uplatex)
 restricted \write18 enabled.
entering extended mode
(./hello-ptex.tex
pLaTeX2e <2011/05/07u00>+0 (based on LaTeX2e <2014/05/01> patch level 0)
Babel <3.9k> and hyphenation patterns for 79 languages loaded.
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/size10.clo)) (./hello-ptex.aux
) [1] (./hello-ptex.aux) )
Output written on hello-ptex.dvi (1 page, 380 bytes).
Transcript written on hello-ptex.log.
$ dvipdfmx hello-ptex.dvi 
hello-ptex.dvi -> hello-ptex.pdf
[1]
7638 bytes written

with the same output.

Wow, that was easy.

xeLaTeX

Now, if you try the same with xeLateX, you will be disappointed, because no Japanese characters will show up. Here we have to do a bit more work. We have to decide which support package to use. I will show example documents with xeCJK and ZXjatype, both available in TeX Live.

In both cases you need to redefine the default fonts for Japanese characters, as the default is something that does not work.

xeCJK

For xeCJK you have to use the following input file:

\documentclass{article}
\usepackage{xeCJK}
\setCJKmainfont{ipaexm.ttf}
\begin{document}
\LaTeX で日本語を書きましょう！
\end{document}

and running it through xelatex will give you

$ xelatex hello-xetex.tex 
This is XeTeX, Version 3.14159265-2.6-0.99991 (TeX Live 2014) (preloaded format=xelatex)
 restricted \write18 enabled.
entering extended mode
(./hello-xetex.tex
LaTeX2e <2014/05/01>
Babel <3.9k> and hyphenation patterns for 79 languages loaded.
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/size10.clo))
(/home/norbert/tl/2014/texmf-dist/tex/xelatex/xecjk/xeCJK.sty
(/home/norbert/tl/2014/texmf-dist/tex/latex/l3kernel/expl3.sty
.....
(./hello-xetex.aux) (/home/norbert/tl/2014/texmf-dist/tex/latex/tipa/t3cmr.fd)
[1] (./hello-xetex.aux) )
Output written on hello-xetex.pdf (1 page).
Transcript written on hello-xetex.log.

and the resulting pdf file can already be viewed.

ZXjatype

For ZXjatype you have to replace the two lines in the preamble with the following:

\usepackage{zxjatype}
\setjamainfont{ipaexm.ttf}

pdflatex

We are now switching to pdfLaTeX, based on the pdftex engine, probably the one used the most in a global perspective. Here again, we consider two packages: The CJK package from Werner Lemberg, and the BXcjkjatype package by Takayuki Yato.

CJK

I haven’t used this package a lot, but by using another sample document I managed to create the fulling code:

\documentclass{article}
\usepackage{CJKutf8}
\newenvironment{Japanese}{%
  \CJKfamily{min}%
  \CJKtilde
  \CJKnospace}{}
\begin{document}
\begin{CJK}{UTF8}{}
\begin{Japanese}
\LaTeX で日本語を書きましょう！
\end{Japanese}
\end{CJK}
\end{document}

Running this through pdflatex should give you something like:

$ pdflatex hello-cjk.tex 
This is pdfTeX, Version 3.14159265-2.6-1.40.15 (TeX Live 2014) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./hello-cjk.tex
LaTeX2e <2014/05/01>
Babel <3.9k> and hyphenation patterns for 79 languages loaded.
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/size10.clo))
(/home/norbert/tl/2014/texmf-dist/tex/latex/cjk/texinput/CJKutf8.sty
...
t/fonts/type1/wadalab/dmj/dmjkk.pfb>
Output written on hello-cjk.pdf (1 page, 29574 bytes).
Transcript written on hello-cjk.log.

If you look closely at the output you will see that the font as well as the spacing around the LaTeX is different. Although the input looks a bit complicated, it is an easy way to add very short text of Japanese to a otherwise non-Japanese document. It supports mixture of all kind of encodings and languages within the same input file.

BXcjkjatype

If the above looks tedious, the wrapper, or better extension, BXcjkjatype might provide a simpler solution. In our case, we can easily get the output with the following minimal input file:

documentclass{article}
\usepackage[whole]{bxcjkjatype}
\begin{document}
\LaTeX で日本語を書きましょう！
\end{document}

which results in a similar output during compile time. Note that the embedded fonts are different in this case. BXcjkjatype use the IPAex fonts as default. Just one warning when using this way: Don’t put any non-ascii characters into the file.

luaLaTeX

Luatex is a new engine that incorporates the Lua interpreter, and allows to control and adjust many of the internals of the TeX program. While it is still not considered an complete replacement of pdftex, it has already reached a status that it is usable as default engine. For typesetting Japanese, a group of Japanese developers have created the luatexja package. Our sample document would look like this:

\documentclass{article}
\usepackage{luatexja}
\begin{document}
\LaTeX で日本語を書きましょう！
\end{document}

and the lualatex run would look similar to the following. Note that on the first run it might take a long time to run lualatex, as a font cache is built up first. Please wait, it will finish.

$ lualatex hello-luatexja.tex 
This is LuaTeX, Version beta-0.79.1 (TeX Live 2014) (rev 4971) 
 restricted \write18 enabled.
(./hello-luatexja.tex
LaTeX2e <2014/05/01>
Babel <3.9k> and hyphenation patterns for 79 languages loaded.
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/home/norbert/tl/2014/texmf-dist/tex/latex/base/size10.clo))
(/home/norbert/tl/2014/texmf-dist/tex/luatex/luatexja/luatexja.sty
...
 1923 words of node memory still in use:
   6 hlist, 1 vlist, 3 rule, 3 glue, 10 kern, 1 glyph, 241 attribute, 299 glue_s
pec, 16 attribute_list, 1 write nodes
   avail lists: 1:1,2:888,3:5,4:40,5:4,6:25,7:3,9:12
<<
Output written on hello-luatexja.pdf (1 page, 17058 bytes).
Transcript written on hello-luatexja.log.

The output depends again on the default font set in your system, but should be similar to the above.

Conclusion

We have seen very simple documents that can be run through various TeX engines and package combinations. If you have managed to run all these documents then you can rest assured that even much more complicated documents will work out, and that your TeX environment is perfectly prepared for Japanese typesetting.

There are still many details, in particular font support and selection, inclusion of graphics, mixing of languages and non-ASCII text, but we will come to these later on.