path: root/info/mendex-doc/mendex.tex

%#!platex -kanji=utf8 mendex.tex
% この文書は日本語で書かれています (encoding: UTF-8N)
% エンコード指定 (since e-pTeX 20160201)
\ifx\epTeXinputencoding\undefined\else
  \epTeXinputencoding utf8
\fi

\documentclass[a4paper]{jsarticle}

% 依存パッケージ
\usepackage{otf}
\usepackage{enumitem}
\usepackage{shortvrb}
\usepackage{newverbs}
\usepackage[dvipdfmx,colorlinks=false]{hyperref}
\usepackage{pxjahyper}

% リスト設定
\setlist[description]{font=\normalfont, style=nextline}
\newenvironment{syntax}{\begin{quote}\small}{\end{quote}}

% インラインコード用設定
\let\xpar\par
\MakeShortVerb{\|}
\newverbcommand{\ParamNum}{\jMeta{数値}\quad 規定値：}{\xpar}
\newverbcommand{\ParamChar}{\jMeta{文字}\quad 規定値：`}{'\xpar}
\newverbcommand{\ParamString}{\jMeta{文字列}\quad 規定値：``}{''\xpar}

% 文書マクロ
\newcommand{\SoftName}[1]{\textsf{#1}}
\newcommand{\FileExtension}[1]{\texttt{.#1}}
\newcommand{\Meta}[1]{$\langle$\mbox{}\textit{#1}\mbox{}$\rangle$}
\newcommand{\jMeta}[1]{$\langle$\mbox{}\textsf{#1}\mbox{}$\rangle$}

% 文書情報
\title{\SoftName{mendex}：索引整形ツール}
\author{アスキー・メディアワークス \and 日本語\TeX 開発コミュニティ}

\begin{document}

\maketitle

\begin{abstract}
\SoftName{mendex}は文書の索引を作成するコマンドラインツールです．\LaTeX により抽出された
索引リストファイル（\FileExtension{idx}）を並べ替え，実際の索引のソースファイルの形に
整形します．\SoftName{makeindex}と互換性があり，さらに「読み」の扱いの手間を減らすように
特殊化されています．出力される索引の形式は，スタイルファイルに従って決定されます．また，
辞書ファイルを与えることにより，索引中の漢字の読みが登録されます．索引の階層は3段階まで
作成することができます．
\end{abstract}

\tableofcontents
\clearpage

\section{使用法}

はじめに\SoftName{mendex}の使用法を示します．
%
\begin{syntax}
|mendex [-ilqrcgfEJSU]|
|[-s| \Meta{sty}|]|
|[-d| \Meta{dic}|]|
|[-o| \Meta{ind}|]|
|[-t| \Meta{log}|]|
|[-p| \Meta{no}|]|
|[-I| \Meta{enc}|]| \\
\phantom{\texttt{mendex }}%
|[--help]|
|[--]|
|[|\Meta{idx0} \Meta{idx1} \Meta{idx2} |...]|
\end{syntax}

\subsection{オプション}

\SoftName{mendex}で利用可能なオプションは以下の通りです．

\begin{description}[leftmargin=2cm]
\item[|-i|]
索引リストファイルが指定されている場合でも，標準入力を索引リストとして使用します．

\item[|-l|]
索引のソートを文字順で行います．指定されなければ単語順のソートになります
（ソート方法については後述）．

\item[|-q|]
静粛モードです．エラーおよび警告以外は標準エラー出力に出力しません．

\item[|-r|]
ページ範囲表現を無効にします．指定しないと，連続して出てくる索引については ``1--5'' のように
ページ範囲で表現されます．

\item[|-c|]
スペースやタブといったブランクを短縮して，すべて1個の半角スペースにします．
また，前後のブランクは削除されます．

\item[|-g|]
日本語の頭文字の区切りを「あかさた……わ」にします．指定しないと「あいうえ……わをん」
になります．

\item[|-f|]
辞書ファイルにない漢字も強制的に出力するモードです．

\item[|-s| \Meta{sty}]
ファイル\Meta{sty}をスタイルファイルと見なします．スタイルファイルを指定しなければ，
デフォルトの索引形式で作成します．

\item[|-d| \Meta{dic}]
ファイル\Meta{dic}を辞書ファイルと見なします．辞書ファイルは日本語の
``\jMeta{漢字} \jMeta{読み}'' のリストで構成されます．

\item[|-o| \Meta{ind}]
ファイル\Meta{ind}を出力ファイルと見なします．指定がない場合は最初の入力ファイルの拡張子を
\FileExtension{ind}としたもの，入力ファイルが標準入力のみであれば標準出力に出力します．

\item[|-t| \Meta{log}]
ファイル\Meta{log}をログファイルと見なします．指定がない場合は最初の入力ファイルの拡張子を
\FileExtension{ilg}としたもの，入力ファイルが標準入力のみであれば標準エラー出力のみに
出力されます．

\item[|-p| \Meta{no}]
\Meta{no}を索引ページの先頭ページとして指定します．また，\TeX のログファイル
（\FileExtension{log}）を参照することにより |any|（最終ページの次のページから），
|odd|（最終ページの次の奇数ページから），|even|（最終ページの次の偶数ページから）といった
指定の仕方も可能です．

\item[|-E|]
入出力文字エンコーディングをEUC-JPに指定します．入力ファイル，出力ファイルともEUC-JPとして扱います．

\item[|-J|]
入出力文字エンコーディングをJIS (ISO-2022-JP)に指定します．入力ファイル，出力ファイルともJISとして扱います．

\item[|-S|]
入出力文字エンコーディングをShift\_JISに指定します．入力ファイル，出力ファイルともShift\_JISとして扱います．

\item[|-U|]
入出力文字エンコーディングをUTF-8に指定します．入力ファイル，出力ファイルともUTF-8として扱います．

\item[|-I| \Meta{enc}]
内部バッファの文字エンコーディングを\Meta{enc}に指定します．\Meta{enc}には |euc|（EUC-JP）
または |utf8|（UTF-8）が指定可能です．このオプションが指定されていない場合のデフォルト
値は |utf8| です\footnote{v2.6fまでは「デフォルト値が |euc| で，オプション |-U| が
明示的に指定されている場合は |utf8| となる」という仕様でしたが，v3.0で変更しました．}．

\item[|--help|]
オプションの要約を表示します．

\item[|--|]
以降はオプション文字列と解釈しません．
\end{description}

\subsection{スタイルファイル}

スタイルファイルは\SoftName{makeindex}のものと上位互換です．
形式は ``\jMeta{スタイルパラメータ} \jMeta{引数}'' のリストで構成されます．
パラメータの記述順序は自由です．また `|%|' 以降はコメントと見なされます．

以下にスタイルパラメータとそのデフォルト値の一覧を示します．

\paragraph{入力ファイルスタイルパラメータ}

\begin{description}[leftmargin=3.5cm]
\item[|keyword|] \ParamString*|\\indexentry|
索引エントリを引数として持つコマンド．

\item[|arg\string_open|] \ParamChar|{|
索引エントリ文字列開始を表す文字．

\item[|arg\string_close|] \ParamChar|}|
索引エントリ文字列終了を表す文字．

\item[|range\string_open|] \ParamChar|(|
ページ範囲の開始を示す文字．

\item[|range\string_close|] \ParamChar|)|
ページ範囲の終了を示す文字．

\item[|level|] \ParamChar|!|
従属レベルであることを示す文字．

\item[|actual|] \ParamChar|@|
このシンボルに続く文字列が実際の索引文字列として出力ファイルに書かれる．

\item[|encap|] \ParamChar+|+ \par
このシンボルに続く文字列が，ページ番号に付くコマンド名として使われる．

\item[|page\string_compositor|] \ParamString*|-|
階層化されたページ番号における階層間の区切り文字．

\item[|page\string_precedence|] \ParamString*|rnaRA|
ページ番号の記法の優先順位．`|R|' および `|r|' はローマ数字，`|n|' はアラビア数字，
`|A|' および `|a|' はアルファベットによる記法を表す．

\item[|quote|] \ParamChar|"|
\SoftName{mendex}のパラメータ文字に対するエスケープキャラクタ．

\item[|escape|] \ParamChar|\\|
一般的な文字に対するエスケープキャラクタ．
\end{description}

\paragraph{出力ファイルスタイルパラメータ}

\begin{description}[leftmargin=3.5cm]
\item[|preamble|] \ParamString*|\\begin{theindex}\n|
出力ファイル先頭の文字列．

\item[|postamble|] \ParamString*|\n\n\\end{theindex}\n|
出力ファイル末尾の文字列．

\item[|setpage\string_prefix|] \ParamString*|\n  \\setcounter{page}{|
開始ページを設定するときの，ページ番号の前に付ける文字列．

\item[|setpage\string_suffix|] \ParamString*|}\n|
開始ページを設定するときの，ページ番号の後に付ける文字列．

\item[|group\string_skip|] \ParamString*|\n\n  \\indexspace\n|
新項目（頭文字）の前に挿入する縦スペースを表す文字列．

\item[|lethead\string_prefix|] \ParamString*||
頭文字の前に付けるコマンド文字列．

\item[|heading\string_prefix|] \ParamString*||
|lethead_prefix| と同じ．

\item[|lethead\string_suffix|] \ParamString*||
頭文字の後に付けるコマンド文字列．

\item[|heading\string_suffix|] \ParamString*||
|lethead_suffix| と同じ．

\item[|lethead\string_flag|] \ParamNum|0|
頭文字の出力のフラグ．|0| のとき出力しない．|0|より大きいときは英字を大文字で，
|0|より小さいときは小文字で出力する．

\item[|heading\string_flag|] \ParamNum|0|
|lethead_flag| と同じ．

\item[|item\string_0|] \ParamString*|\n  \\item |
主エントリ間に挿入するコマンド．

\item[|item\string_1|] \ParamString*|\n    \\subitem |
サブエントリ間に挿入するコマンド．

\item[|item\string_2|] \ParamString*|\n      \\subsubitem |
サブサブエントリ間に挿入するコマンド．

\item[|item\string_01|] \ParamString*|\n    \\subitem |
主−サブエントリ間に挿入するコマンド．

\item[|item\string_x1|] \ParamString*|\n    \\subitem |
主−サブエントリ間に挿入するコマンド（主エントリにページ番号がないとき）．

\item[|item\string_12|] \ParamString*|\n    \\subsubitem |
サブ−サブサブエントリ間に挿入するコマンド．

\item[|item\string_x2|] \ParamString*|\n    \\subsubitem |
サブ−サブサブエントリ間に挿入するコマンド（サブエントリにページ番号がないとき）．

\item[|delim\string_0|] \ParamString*|, |
主エントリと最初のページ番号の間の区切り文字列．

\item[|delim\string_1|] \ParamString*|, |
サブエントリと最初のページ番号の間の区切り文字列．

\item[|delim\string_2|] \ParamString*|, |
サブサブエントリと最初のページ番号の間の区切り文字列．

\item[|delim\string_n|] \ParamString*|, |
ページ番号間の区切り文字列．どのエントリレベルにも共通．

\item[|delim\string_r|] \ParamString*|--|
ページ範囲を示すときの，ページ番号間の区切り文字列．

\item[|delim\string_t|] \ParamString*||
ページ番号のリストの終端に出力する文字列．

\item[|suffix\string_2p|] \ParamString*||
ページ番号が2ページ連続する場合に，|delim_n| と2ページ目の番号の代わりに付加する文字列．
文字列が定義されている場合にのみ有効．

\item[|suffix\string_3p|] \ParamString*||
ページ番号が3ページ連続する場合に，|delim_r| と3ページ目の番号の代わりに付加する文字列．
|suffix_mp| より優先される．文字列が定義されている場合にのみ有効．

\item[|suffix\string_mp|] \ParamString*||
ページ番号が3ページまたはそれ以上連続する場合に，|delim_r| と末尾のページ番号の代わりに
付加する文字列．
文字列が定義されている場合にのみ有効．

\item[|encap\string_prefix|] \ParamString*|\\|
ページ番号にコマンドを付けるときの，コマンド名の前に付ける文字列．

\item[|encap\string_infix|] \ParamString*|{|
ページ番号にコマンドを付けるときの，ページ番号の前に付ける文字列．

\item[|encap\string_suffix|] \ParamString*|}|
ページ番号にコマンドを付けるときの，ページ番号の後に付ける文字列．

\item[|line\string_max|] \ParamNum|72|
1行の最大文字数．それを超えると折り返す．

\item[|indent\string_space|] \ParamString*||
折り返した行の頭に挿入するスペース．

\item[|indent\string_length|] \ParamNum|16|
折り返した行の頭に挿入されるスペースの長さ．

\item[|symhead\string_positive|] \ParamString*|Symbols|
|lethead_flag| または |heading_flag| が正数の場合に数字・記号の頭文字として出力する文字列．

\item[|symhead\string_negative|] \ParamString*|symbols|
|lethead_flag| または |heading_flag| が負数の場合に数字・記号の頭文字として出力する文字列．

\item[|symbol|] \ParamString*||
|symbol_flag| が|0|でない場合に，数字・記号の頭文字として出力する文字列．文字列が定義されて
いれば，|symhead_positive| および |symhead_negative| より優先される（\SoftName{mendex}専用）．

\item[|symbol\string_flag|] \ParamNum|1|
数字・記号の頭文字の出力フラグ．|0|のとき出力しない（\SoftName{mendex}専用）．

\item[|letter\string_head|] \ParamNum|1|
日本語の頭文字の出力のフラグ．|1|のときカタカナ，|2|のときひらがなで出力する
（\SoftName{mendex}専用）．

\item[|priority|] \ParamNum|0|
英字と日本語との混在した索引語のソート方法についてのフラグ．|0|でなければ英字と日本語との
間に半角スペースを入れた状態でソートする（\SoftName{mendex}専用）．

\item[|character\string_order|] \ParamString*|SEJ|
記号，英字，日本語の優先順位．`|S|' は記号，`|E|' は英字，`|J|' は日本語を表す
（\SoftName{mendex}専用）．
\end{description}

\subsection{参考：\SoftName{makeindex}との比較}
\SoftName{mendex}は基本的に\SoftName{makeindex}と互換ですが，以下の点で異なります．

\begin{itemize}
\item \SoftName{makeindex}には索引項目の分類として「記号」，「アルファベット」の
  他に，数字のみの項目として「数字」という分類がありますが，
  \SoftName{mendex}では数字は「記号」に含まれます．
  また，\SoftName{makeindex}に存在するスタイルパラメータのうち，
  |numhead_positive|と|numhead_negative|は認識されません．

\item 数字・記号→欧文→和文の順にこだわらない索引の作成が可能です
  （|character_order|パラメータを追加）．他に\SoftName{mendex}で追加された
  スタイルパラメータには，|symbol|，|symbol_flag|，|letter_head|，|priority|があります．

\item \SoftName{makeindex}の項目の並び順は，頭文字は
  「記号」「数字」「アルファベット」に分けて並べられますが，2文字目以降は単純に
  ASCIIコード順となり，記号よりアルファベットが先になる場合もあります．
  \SoftName{mendex}の英数字の並びは，2文字目以降も
  「記号」「数字」「アルファベット」の分類が考慮されます．

\item \SoftName{makeindex}には |-g| オプションでドイツ語辞書順
  （記号→アルファベット小文字→アルファベット大文字→数字）で並べるようにできますが，
  \SoftName{mendex}ではサポートしていません．代わりに，|-g| オプションは
  日本語の頭文字の区切りを切り換えるオプションになっています．
\end{itemize}

\section{日本語の扱いについて}

\SoftName{mendex}は日本語の索引をできるだけ楽に扱えるようになっています．
\SoftName{makeindex}では日本語の索引が正しく辞書順にソートするためには，ひらがなまたは
カタカナに揃え，拗音，撥音，濁点を除いた読みを付けなければなりませんでした
（自動的に揃えるバージョンもある）． \SoftName{mendex}ではカナについてはすべて自動的に
揃え，また漢字については辞書ファイルを設定することにより各索引語ごとに読みを付ける作業を
かなり解消できます．以下に内部でのカナの変換例を示します．
%
\begin{quote}
\begin{tabular}{ll}
かぶしきがいしゃ & かふしきかいしや \\
マッキントッシュ & まつきんとつしゆ \\
ワープロ & わあふろ
\end{tabular}
\end{quote}

辞書ファイルは ``\jMeta{漢字} \jMeta{読み}'' のリストで構成されます．
\jMeta{漢字}と\jMeta{読み}の区切りはタブまたはスペースです． 以下に辞書の例を示します．
%
\begin{quote}
\begin{tabular}{ll}
漢字 & かんじ \\
読み & よみ \\
環境 & かんきょう \\
$\alpha$ & アルファ
\end{tabular}
\end{quote}

辞書に登録する漢字については，読み方が1通りになるよう送り仮名を付けてください．
「表」，「性質」のように送り仮名によらず2通りの読み方ができる語についてはどちらか
1つしか登録できません．他の読み方については各索引語へ読みを付けることで対応してください．
また，環境変数 |INDEXDEFAULTDICTIONARY| に辞書ファイルを登録することにより，自動的に
辞書を参照します．環境変数に登録した辞書は |-d| で指定した辞書と併用できます．

\section{ソート方法について}

\SoftName{mendex}は通常は入力された索引語をそのままソートします．|-l| オプションが
付けられた場合，複数の単語で構成される索引語については，ソートするときに単語と単語の間の
スペースを詰めてソートします．ここでは前者を単語順ソート，後者を文字順ソートと呼ぶことに
します．文字順ソートの場合，実際に出力される文字列はスペースを含んだ状態のものですので，
索引語自体が変化することはありません．以下に例を示します．
%
\begin{quote}
\begin{tabular}{ll}
\emph{単語順ソート} & \emph{文字順ソート} \\
X Window & Xlib \\
Xlib & XView \\
XView & X Window
\end{tabular}
\end{quote}

また，日本語−英字間でも似たようなソート方法があります．スタイルファイルで |priority| を|0|以外
に指定した場合，隣接した日本語と英字の間にスペースを入れてソートします． 以下に例を示します．
%
\begin{quote}
\begin{tabular}{ll}
|priority 0| & |priority 1| \\
index sort & indファイル \\
indファイル & index sort
\end{tabular}
\end{quote}

\section{環境変数について}

\SoftName{mendex}では以下のような環境変数を使用しています．

\begin{description}[leftmargin=5cm]
\item[|INDEXSTYLE|]
索引スタイルファイルがあるディレクトリ．

\item[|INDEXDEFAULTSTYLE|]
デフォルトで参照する索引スタイルファイル．

\item[|INDEXDICTIONARY|]
辞書があるディレクトリ．

\item[|INDEXDEFAULTDICTIONARY|]
常に参照する辞書ファイル．
\end{description}

\section{既知の問題}
複数のページ記法を使用する場合，ページ順に索引リストファイル（\FileExtension{idx}）を
与えないとページ番号を誤認することがあります．

% また，\SoftName{makeindex}に比べると実行速度が遅くなっています．

\section{バグ報告先・開発元}
現在，\SoftName{mendex}は日本語\TeX 開発コミュニティによりメンテナンスされています．
\begin{itemize}
  \item \url{https://github.com/texjporg/tex-jp-build} （本体のソースコード）
  \item \url{https://github.com/texjporg/mendex-doc} （この文書を含むドキュメント類）
\end{itemize}

\end{document}