- 参考 URL:
参考 URL の最初の2つのサイトにあるように、Doxygen の LaTeX 出力ソースからの PDF 作成は、 欧文の LaTeX もしくは pdfLaTeX を想定しており、そのままでは日本語が使えません。 PDF の日本語が文字化けしてしまいます。
そこで上記参考 URL のサイトを参考にして、それらのサイトでの修正と同様ことを行う LaTeX スタイルシートを作ってみました。
参考サイトでは、Doxygen が出力した LaTeX ソースファイル（refman.tex）を
sed もしくは手動で編集しています。
Doxygen を実行するたびに修正するのは、ほんの僅かではありますが手間がかかります。
以降で説明するいくつかのスタイルシートでは、それらのファイル名を
Doxygen の Doxyfile に書いておくだけで、
出力された refman.tex を修正することなしに、
日本語の PDF を文字化けすることなしに生成することができるようになります。
また、私の環境だけかもしれませんが、 Doxygen の出力から作成した PDF では、 関数名などのリンクをクリックしたときに、その定義場所にジャンプできていませんでした。 その現象の修正も LaTeX スタイルシートで行っています。
動作確認は以下の環境で行いましたが、他の環境でも同じスタイルシートが使えると期待しています。
- オペレーティングシステム：
- Windows 7 Professional 64bit
- macOS High Sierra
- アプリケーション：
- Doxygen: 1.8.14 (Cygwin 版 / Homebrew 版)
- LaTeX: e-upTeX 3.14159265-p3.8.1-u1.23-180226-2.6 (utf8.uptex) (TeX Live 2018)
プロジェクト用の Doxyfile に、以下の設定を行います。
GENERATE_LATEX = YES
LaTeX 出力を有効にします。
LATEX_CMD_NAME = uplatex
LaTeX のコマンド名に、日本語に対応した upLaTeX のコマンドを指定します。
USE_PDFLATEX = NO
pdfLaTeX は日本語を扱えないため、これを使わないようにします。
LATEX_EXTRA_STYLESHEET = doxygenjpext.sty pdfinfo.sty fontsettings.sty hyperlinkfix.sty
以降で説明するスタイルシートファイルを指定します。
Doxygen が出力する LaTeX ソースファイルの冒頭に、
\usepackage{doxygenjpext} などが挿入されるようになります。
doxygenjpext.sty は Doxygen が出力した文書の、日本語に関する設定を行います。
pdfinfo.sty は、出力する PDF ファイルのプロパティ情報を設定する内容を記述します。
fontsettings.sty は Doxygen が出力した文書の、フォントに関する設定を行います。
hyperlinkfix.sty は、 PDF の関数名などのリンクをクリックしたときに、
正常にジャンプできるようにします。
LATEX_EXTRA_FILES = book.cls
refman.tex LaTeX 文書のが使用するドキュメントクラスを、
book ではなく日本語に対応した jsbook を使用するように修正するための
偽装 book ドキュメントクラスファイルを指定します。
PDF_HYPERLINKS = YES
PDF で HTML 出力のようなハイパーリンクを、ページ参照の代わりに出力するようにします。 Adobe Acrobat Reader のような PDF Viewer でブラウズするときに便利です。
この設定を行った上で、 LATEX_EXTRA_STYLESHEET に hyperlikfix.sty を指定することで、
ハイパーリンクをクリックすると参照先のページに移動できるようになります。
以降で説明するスタイルシートファイルを、Doxyfile と同じディレクトリに置きます。
スタイルシートファイルは、 GitHub からダウンロードしてください。
ファイル名は doxygenjpext.sty、
pdfinfo.sty、
fontsettings.sty、
hyperlinkfix.sty です。
それらのうち、 pdfnfo.sty は、プロジェクト固有の情報を設定するため、
修正を行う必要があります。ファイルの内容は、以下のようになっているので、
TITLE, PROJECT NAME, AUTHOR NAME, Doxygen 1.8.14,
KEYWORDS を書き換えてください。
\AtBeginDocument{\hypersetup{%
pdfinfo={
Title={TITLE},
Subject={PROJECT NAME},
Author={AUTHOR NAME},
% Creator={},
Producer={Doxygen 1.8.14},
Keywords={KEYWORDS}%
}%
}}
準備ができたら、以下の手順で PDF を作成します。
(LaTeX 出力が doc/latex に出力されると想定しています。)
cd /path/to/your/project
doxygen && ( cd doc/latex && make && dvipdfmx refman )
以下に、各スタイルシートに記述する内容を説明します。
Doxygen は出力する LaTeX 文書のドキュメントクラスに、 book クラスを使用するようにしています。
しかし、参考サイト LaTeX の「アレなデフォルト」傾向と対策 にあるように、新日本語ドキュメントクラス jsbook を使用するように変更します。
そのためには、 book クラスの定義ファイルと同名のファイルを、
refman.tex と同じディレクトリに配置することで、
book クラスを偽装し、内部で jsbook クラスを読み込むことにします。
ただし、jsbook クラスでは、索引が3段組みになるので、
2段組になるように report オプションを指定するようにしました。
jsbook クラスでは余白が大きすぎるので、最小になるように設定し直しています。
また、Doxygen が使用している他のスタイルシートなどの影響でしょうか、 目次の章の行が章番号と見出しが重なってしまっています。 各章の見出しのページでは、章番号の後ろの「章」が出力されていません。 そこで、章番号の前後に「第」と「章」を出力しないようにしました。
book クラスのファイル book.cls は以下のようになります。
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{book}[2018/06/10 v0.1 Fake book class to generating Japanese PDF]
% Parses and passes class options to the underlying jsbook class
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{jsbook}}
\ProcessOptions
% Load LaTeX's jsbook class with the uplatex and the dvipdfmx options
\LoadClass[uplatex,dvipdfmx,report]{jsbook}%
\renewcommand{\prechaptername}{}%
\renewcommand{\postchaptername}{}%
% Expand margins to fit doxygen output contents
\setlength{\textwidth}{\fullwidth}%
\setlength{\evensidemargin}{\oddsidemargin}%
\setlength\footskip{2\baselineskip}%
\addtolength{\textheight}{-2\baselineskip}%
doxygenjpext.sty に、日本語に関する設定を行うため、以下の内容を記述します。
各種パッケージに、 dvipdfmx または dvipdfm ドライバを指定します。
\PassOptionsToPackage{dvipdfmx}{adjustbox}
\PassOptionsToPackage{dvipdfmx}{color}
\PassOptionsToPackage{dvipdfmx}{xcolor}
\PassOptionsToPackage{dvipdfmx}{graphicx}
\PassOptionsToPackage{dvipdfm}{geometry}
和文フォントのメトリックを調整するために、otf パッケージなどを読み込みます。
\usepackage[deluxe,jis2004,uplatex]{otf}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
Doxygen の出力した LaTeX ファイルでは、hyperref パッケージに pdftex
または ps2pdf ドライバが指定されています。これを dvipdfmx に変更します。
まず、hyperref パッケージを dvipdfmx ドライバを指定して読み込んで、
さらに和文に対応させるために、pxjahyper パッケージを読み込みます。
pxjahyper パッケージの最新版は、hyperref の unicode オプションに
対応しているので、 hyperref を読み込むときに unicode を指定します。
(pxjahyper を読み込む前に指定しておかないと、しおりが文字化けしてしまいます。)
そして、このスタイルシート以降に現れた \usepackage に hyperref が指定されていたら、
無視するようにしてしまいます。
\RequirePackage[dvipdfmx,pagebackref=true,unicode]{hyperref}
\usepackage{pxjahyper}
%
\RequirePackage{xifthen}
\RequirePackage{letltxmacro}
\LetLtxMacro\originalusepackage\usepackage\relax
\renewcommand\usepackage[2][]{%
\ifthenelse{\equal{#2}{hyperref}}{}{\originalusepackage[#1]{#2}}%
}
Doxygen の出力では、LATEX_EXTRA_STYLESHEET で指定したスタイルシート、
すなわち doxygenjpext.sty を読み込んだ後で
hyperref パッケージのオプションを指定しています。
そこで、プリアンブルの読み込みが終わってから、 hyperref のオプションを追加指定します。
\AtBeginDocument{%
\hypersetup{%
bookmarks=true,bookmarksnumbered=true,% enable bookmarks
setpagesize=false}%
}
jsbook クラスを使うようにすると、目次に索引の行が2つ重複して出力されるようになってしまいます。
これは book や jbook クラスでは目次に索引が自動的には出力されないため、 Doxygen が明示的に目次の章を出力しているのですが、 jsbook クラスでは自動的に出力されるようにしているので2行出力されてしまいます。
そこで以下のように printindex マクロを再定義して、
jsbook 内で索引を目次に出力している addcontentsline マクロを何もしないようにします。
\AtBeginDocument{%
\LetLtxMacro\printindex\originalprintindex@fixaddcontentsline\relax
\renewcommand\printindex{%
\renewcommand\addcontentsline[3]{}%
\originalprintindex@fixaddcontentsline}}
pdfinfo.sty に PDF のプロパティに関する設定を行うため、以下の内容を記述します。
TITLE, PROJECT NAME, AUTHOR NAME, Doxygen 1.8.14,
KEYWORDS は、プロジェクト固有の情報に書き換えてください。
\AtBeginDocument{\hypersetup{%
pdfinfo={
Title={TITLE},
Subject={PROJECT NAME},
Author={AUTHOR NAME},
% Creator={},
Producer={Doxygen 1.8.14},
Keywords={KEYWORDS}%
}%
}}
個人的な好みの設定になりますが、 fontsettings.sty に以下の内容を記述します。
(したがってこのスタイルシートは LATEX_EXTRA_STYLESHEET に書かなくても構いません。)
見出しが太字になるようにします。
\DeclareFontShape{JY2}{hmc}{bc}{n}{<->ssub*hmc/bx/n}{}
\DeclareFontShape{JT2}{hmc}{bc}{n}{<->ssub*hmc/bx/n}{}
\DeclareFontShape{JY2}{hgt}{bc}{n}{<->ssub*hgt/bx/n}{}
\DeclareFontShape{JT2}{hgt}{bc}{n}{<->ssub*hgt/bx/n}{}
表紙の見出しはゴシックのボールド体にします。
\RequirePackage{letltxmacro}
\LetLtxMacro\originaltitlepage\titlepage\relax
\renewenvironment{titlepage}{%
\begin{originaltitlepage}\gtfamily\sffamily\bfseries%
}{\end{originaltitlepage}}
Doxygen は書体にサンセリフ体を指定していますが、 和文の書体は指定していないためデフォルトの明朝体が使われてしまい、 欧文と和文がアンバランスになってしまいます。 そこで、本文の書体をローマンと明朝体に変更します。 ただし見出しとラベルはサンセリフ体にします。
\AtBeginDocument{%
% Change serif fonts in body text
\renewcommand{\kanjifamilydefault}{\mcdefault}
\renewcommand{\familydefault}{\rmdefault}
% Select sanserif fonts in section headers
\allsectionsfont{%
\gtfamily\sffamily%
\fontseries{bc}\selectfont%
\color{darkgray}%
}
\renewcommand{\DoxyLabelFont}{%
\gtfamily\sffamily%
\fontseries{bc}\selectfont%
\color{darkgray}%
}
}
Doxygen の出力のハイパーリンクが正常に機能するように、
hyperlinkfix.sty に以下の内容を記述します。
私の環境のせいかもしれませんが、 Doxygen の出力から作成した PDF では、
関数名などのリンクをクリックしたときに、その定義場所にジャンプできていませんでした。
これはどうやら、Doxygen がリンクの参照に \hyperlink コマンドを使用しているせいのようです。
\hyperlink コマンドは、\hypertarget コマンドを使って参照先を設定するもののようですが、
Doxygen は参照先に \label コマンドを使用しているので、
dvipdfmx が PDF に変換するときに参照先が見つからないというエラーになってしまいます。
そこで \hyperlink コマンドを \hyperref コマンドにマクロ置換するようにします。
しかしながら、目次や索引の参照は \hyperref に置き換えるとリンクができないようでした。
そのため、 プリアンブルの \makeindex には影響がないようにするとともに、
\tableofcontents と \printindex の前後では、
マクロ置換を元に戻すようにしました。
それらを行うマクロが以下のようになります。
\AtBeginDocument{%
\LetLtxMacro\originalhyperlink\hyperlink\relax
\def\hyperlinkexch#1#2{\hyperref[#1]{#2}}
\LetLtxMacro\originaltableofcontents\tableofcontents\relax
\def\tableofcontents{%
\let\hyperlink\originalhyperlink\originaltableofcontents%
\let\hyperlink\hyperlinkexch}%
\LetLtxMacro\originalprintindex@hyperlinkfix\printindex\relax
\renewcommand\printindex{%
\let\hyperlink\originalhyperlink\relax\originalprintindex@hyperlinkfix%
\let\hyperlink\hiperlinkexch}%
}
今回、このスタイルシートを作成する際には、冒頭の参考 URL のサイトの他にも 様々なサイトを参考にさせていただきました。
先人の方々には、大変感謝いたします。
また、私のブログでは kim 様からいろいろなアイデアをいただきました。 重ねて感謝の意を表します。