path: root/Master/texmf-dist/doc/platex/pxjahyper/pxjahyper.tex

% 文字コードは UTF-8
% uplatex で組版する
\documentclass[uplatex,dvipdfmx,a4paper]{jsarticle}
\renewcommand{\headfont}{\gtfamily\romanseries{sbc}\sffamily}
\usepackage[T1]{fontenc}
\usepackage{lmodern,textcomp}
\usepackage{color}
\definecolor{myblue}{rgb}{0,0,0.75}
\definecolor{mygreen}{rgb}{0,0.45,0}
\usepackage[colorlinks,hyperfootnotes=false]{hyperref}
\usepackage{pxjahyper}
\hypersetup{linkcolor=myblue,urlcolor=mygreen,
  pdftitle={pxjahyperパッケージ},
  pdfauthor={八登崇之}}
\usepackage{bxtexlogo}
\bxtexlogoimport{*,TL-e}
\usepackage{shortvrb}
\MakeShortVerb{\|}
\usepackage[verb]{bxghost}
\newcommand{\PkgVersion}{1.5}
\newcommand{\PkgDate}{2024/08/25}
\newcommand{\Pkg}[1]{\textsf{#1}}
\newcommand{\Meta}[1]{$\langle$\mbox{}#1\mbox{}$\rangle$}
\newcommand{\Note}{\par\noindent ※}
\newcommand{\Means}{：\quad}
\newcommand{\／}{\mbox{}／\mbox{}}
\providecommand{\Strong}[1]{{\headfont#1}}
%-----------------------------------------------------------
\begin{document}
\title{\Pkg{pxjahyper} パッケージ}
\author{八登崇之\ （Takayuki YATO; aka.~``ZR''）}
\date{v\PkgVersion\quad[\PkgDate]}
\maketitle
\tableofcontents

%===========================================================
\section{概要}

(u){\pLaTeX} + hyperref + dvipdfmxの組み合わせで
日本語を含む\Strong{PDF文字列}%
（“しおり”などの文書情報の文字列
\footnote{例えば、|\hypersetup|の|pdftitle|キーに指定する文字列は
  「PDF文字列」の一種である。
  また、|\section|命令の引数のテキストは
  「{\TeX}で組版する版面出力」と「PDF文字列」
  の両方に使われる。
  後者のような箇所で「{\TeX}の版面出力」と「PDF文字列」を
  別に指定したい場合は|\texorpdfstring|という命令が利用できる。}）
をもつPDF文書を作成する場合に必要となる機能を提供する。
\begin{itemize}
\item dvipdfmx用の「tounicode special」について、
  内部漢字コードに応じて適切なものを出力する。
\item PDF文字列の中で{\LaTeX}カーネル（|\"a|や|\textsection|等）
  や\Pkg{japanese-otf}パッケージ（|\UTF|や|\ajMaru|等）の
  文字出力用命令が“可能な限り”正しく機能するようにする。
  %ただし、エンジンが{\pTeX}の場合は、out2uni/convbkmk%
  %（および試験的機能の“force-unicode”）を利用
  %する場合を除き、JIS~X~0208にない文字は出力できない
  %（hyperrefの警告が出る）。
\item {\TeX}の版面拡大機能が使われている
  （|\mag|値が1000でない）場合
  \footnote{典型的には\Pkg{jsclasses}の
    文書クラスで基底フォントサイズを10\,pt以外に設定している場合。}%
  には\Pkg{hyperref}が出力するpapersize specialの
  紙面サイズの値が不正になるが、この場合に|\mag|値を
  考慮して求めた正しいサイズによるpapersize specialを
  改めて出力する。
\item \Pkg{hyperref}が行う「テキスト装飾命令の無力化」の
  対象に、{(u)\pLaTeX}特有のいくつかの命令を追加する。
\end{itemize}

%===========================================================
\section{パッケージの読込}

|\usepackage|で読み込む。
\begin{quote}\small\begin{verbatim}
\usepackage[オプション,...]{pxjahyper}
\end{verbatim}\end{quote}

\paragraph{plautopatchとの関係}
\Pkg{plautopatch}パッケージが事前に読み込まれている場合は、
\Pkg{hyperref}が読み込まれるとその直後に自動的に\Pkg{pxjahyper}が
\Strong{オプション無しで}読み込まれる。
もし何らかのオプションを指定したい場合は、
\Pkg{hyperref}の読込より前に|\PassOptionsToPackage|で
オプションを指定する必要がある。
\begin{quote}\small\begin{verbatim}
\PassOptionsToPackage[nopapersize]{pxjahyper}
\end{verbatim}\end{quote}

\paragraph{使用可能なオプション}\mbox{}
\begin{itemize}
\item \Strong{パラメタ設定}\Means
  |\pxjahypersetup|命令の引数に書くパラメタ設定設定記述を
  パッケージオプションに書くことができる。
  例えば
\begin{quote}\small\begin{verbatim}
\usepackage[fallback=delete]{pxjahyper}
\end{verbatim}\end{quote}
  と指定すると、表現不能な文字を代替するゲタ文字が出力されなくなる。
\item \Strong{ドライバオプション}\Means
  以下の値が指定できる。
  \begin{itemize}
  \item |dvipdfmx|
  \item |dvips|
  \item |resetdvidriver|（既定）\Means
    \Pkg{hyperref}のドライバ指定から自動的に判定する。
    \Note 1.1版において名前を|auto|から|resetdvidriver|に変更した。
      旧名の|auto|%
      \footnote{1.0版では|autodvidriver|としていたが、
        この旧名も\Strong{非推奨}とする。}%
      は\Strong{非推奨}とする。
  \item |nodvidriver|\Means
    ドライバ依存動作の無効化を指示する。
    ほとんどの機能が無効になる。
    \footnote{1.0版において|nodvidriver|の非推奨の別名の|none|は
      \Strong{廃止}された。}
    %（0.5版から非推奨だった。）
  \end{itemize}
\item |tounicode|（既定）\Means
  以下の2つの設定を行う。
  \begin{enumerate}
  \item ドライバが|dvipdfmx|である場合は適切な
    「tounicode special」を発行する。
    \Note この設定は|notounicode|オプションにより打ち消される。
  \item 「tounicode special」を前提にした出力を行う。
    \Note この設定は|out2uni|・|convbkmk|オプションと排他である。
  \end{enumerate}
\item |notounicode|\Means
  dvipdfmx用の「tounicode special」を発行しない。
\item |out2uni|\Means
  out2uniフィルタを使うことを前提にした出力を行う。
\item |convbkmk|\Means
  convbkmkフィルタを使うことを前提にした出力を行う。
  \Note ドライバが|dvips|の場合は既定で|convbkmk|が有効になる。
  これにより元の既定値|tounicode|は実質的に
  \footnote{|tounicode|の説明中の項目1の機能はdvipsでは効果がなく、
    また項目2の機能は上書きされるため。}%
  無効化される。
%\item |fallback-geta|（既定）\Means
%  PDF文字列中で表現不能な文字をゲタ記号（〓）に置き換える。
%\item |fallback-delete|\Means
%  PDF文字列中で表現不能な文字を削除する。
\item |papersize|（既定）\Means
  papersize specialの補正を有効にする。
\item |nopapersize|\Means
  |papersize|の否定。
\end{itemize}

\paragraph{上級者向けオプション}\mbox{}
\begin{itemize}
\item |otfmacros|（既定
  \footnote{0.6版より既定を|otfmacros|に変更した。}）\Means
  \Pkg{japanese-otf}付属の\Pkg{ajmacros}パッケージが提供する
  文字入力命令（|\ajMaru|、|\ajLig|等）をPDF文字列中で
  “可能な限り”使えるようにする。
  \Note 詳細は\ref{ssec:otf-package}節を参照。
  \Note |otfmacros|を有効にする場合は|otfcid|も有効にする必要がある。
\item |nootfmacros|\Means
  |otfmacros|の否定。
\item |otfutf|（既定）\Means
  \Pkg{japanese-otf}パッケージの|\UTF|命令をPDF文字列中で
  使えるようにする。
  \Note 詳細は\ref{ssec:otf-package}節を参照。
\item |nootfutf|\Means
  |otfutf|の否定。
\item |otfcid|（既定）\Means
  \Pkg{japanese-otf}パッケージの|\CID|命令をPDF文字列中で
  “可能な限り”使えるようにする。
  \Note エンジンの{\eTeX}拡張および
  \Pkg{etoolbox}と\Pkg{bxjatoucs}パッケージのインストールが必要。
  \Note 詳細は\ref{ssec:otf-package}節を参照。
\item |nootfcid|\Means
  |otfcid|の否定。
\item |disablecmds|（既定）\Means
  「PDF文字列中のテキスト装飾命令の無効化」を有効にする。
  \Note 詳細は\ref{ssec:disablecmds}節を参照。
\item |nodisablecmds|\Means
  |disablecmds|の否定。
\item |charcmds|（既定）\Means
  {\LaTeX}標準の文字命令をPDF文字列中で使えるようにする。
\item |nocharcmds|\Means
  |charcmds|の否定。
\item |bigcode|（既定
  \footnote{0.3a版より既定を|bigcode|に変更した。}）\Means
  {\upTeX}でのToUnicode CMapとしてUTF8-UTF16を用いる。
  %（当該のファイルが存在する必要がある。）
\item |nobigcode|\Means
  |bigcode|の否定。
  {\upTeX}でのToUnicode CMapとしてUTF8-UCS2を用いる。
\item |jacommentline|（既定）\Means
  \Pkg{hyperref}が出力する|.out|ファイルの先頭に日本語の文字を含む
  コメント行を出力する。
  \Note {\pTeX}系エンジンの「入力漢字コード自動判定」に対する対策。
\item |nojacommentline|\Means
  |jacommentline|の否定。
  \Note 不具合が発生したときのために無効化できるようにしている。
\item |force-unicode|（1.4版で\Strong{非推奨}）\Means
  このオプションは何もしない。
  \footnote{{\pLaTeX}での“unicodeモード”が正式にサポートされたため
    このオプションは不要になった。}
\end{itemize}

%===========================================================
\section{機能}

「概要」で述べた機能は（オプション設定に応じて）
自動的に実施される。

%-------------------
\subsection{パラメタ設定}
\label{ssec:setup}

パッケージの動作を制御する設定を|\pxjahypersetup|命令で行える。

\begin{quote}\small
|\pxjahypersetup{|\Meta{キー}|=|\Meta{値}|,...}|
\end{quote}
\Note 真偽値は|true|\／|false|で指定する。

有効な設定キーは以下の通り。

\begin{itemize}
\item |fallback=|\Meta{値}\Means
  PDF文字列中で表現不能な文字についての代替出力の方法を指定する。
  \footnote{1.1版ではパッケージオプション
    （|fallback-geta|／|fallback-delete|）
    として提供していたが、この方式は\Strong{非推奨}とする。}
  \begin{itemize}
  \item |geta|（既定）\Means
    表現不能な文字をゲタ記号（〓）に置き換える。
  \item |delete|\Means
    表現不能な文字を削除する。
  \end{itemize}
  \Note 以下、パッケージ動作の解説中で「ゲタ記号を出力」と
    ある場合は実際にはこの設定に従う。
\item |fallback-warn=|\Meta{真偽値}\Means
  PDF文字列中の表現不能な文字について「ゲタ記号を出力」する際に
  警告を出すか。
  既定値は真。
\item |fallback-cidm=|\Meta{真偽値}\Means
  \Pkg{japanese-otf}パッケージのAJ1\Strong{以外}のCID入力命令
  （|\CIDC|・|\CIDK|・|\CIDT|）
  について、PDF文字列中で「ゲタ記号を出力」する動作に置き換えるか。
  既定値は真。
  \Note これらの命令をサポートするような（本パッケージとは別の）
  何らかの機能を利用する場合には偽に設定する必要があるかもしれない。
  \footnote{ただし、本パッケージによる再定義は“優先度を下げて”いる
    ので、設定が不要である場合もある。}
\end{itemize}

%-------------------
\subsection{Unicode符号値による入力}
\label{ssec:ux-command}

PDF文字列入力中で、命令|\Ux|が以下の意味に変更される。
PDF文字列以外では|\Ux|は以前の定義（または未定義）に戻る。
\footnote{|\Ux|という命令名は\Pkg{bxbase}パッケージの
Unicode符号値入力用の命令が使っているものである。
従って、\Pkg{bxbase}パッケージを読み込んでいれば、
「PDF文字列と版面出力の両方に使われる」ようなテキストにおいて、
|\Ux|でUnicode符号値入力が可能になる。
ただし、Unicode符号値入力用の命令としては
「\Pkg{japanese-otf}パッケージの|\UTF|命令」
の方が有名であり、\Pkg{pxjahyper}は|\UTF|もサポートするので、
こちらを使う方が無難かもしれない。}

\begin{itemize}
\item |\Ux{|\Meta{Unicode符号値16進}|}|\Means
  その符号値の文字を出力する。
  具体的な動作は以下の通り：
  \begin{itemize}
  \item |out2uni|または|convbkmk|が有効の
  場合は、エスケープ表記（|\0xUUUU|）を出力する。
  \item エンジンが{\upLaTeX}の場合、
  あるいは\Pkg{hyperref}の“unicodeモード”
  （\ref{sec:Unicode-mode}節）が有効の場合は、
  当該のUnicode文字自体を書いたのと同等になる。
  \item 上記以外で、{\TeX} Live 2022以降の{\pLaTeX}の場合
  \footnote{正確にいうと、|\Uchar|と|\ucs|プリミティブをもつ
    {\TLe-(u)\pTeX}エンジンである場合。}%
  は、当該のUnicode文字に“対応”するJIS符号系の文字を書いたのと同等になる。
  “対応”する文字がない場合は出力できないので
  ゲタ記号を出力する。
  \end{itemize}
  \item どの条件にも当てはまらない場合は、|\Ux|は無効になる
  （定義されない）。
\end{itemize}

%-------------------
\subsection{\Pkg{japanese-otf}パッケージの文字入力命令への対応}
\label{ssec:otf-package}

\paragraph{\textbackslash UTF命令}
\Pkg{japanese-otf}パッケージの|\UTF|命令は、PDF文字列中では
out2uni用の出力を行う。
本パッケージで|otfutf|オプションを有効にした場合は、
PDF文字列中の動作が以下のように変更される。

\begin{itemize}
\item |\Ux|命令（\ref{ssec:ux-command}節参照）が有効の場合は、
  |\Ux|と同じ動作
  \footnote{もし|\Ux|の出力がゲタ記号になる場合は、
    |\UTF|もゲタ記号になる。}%
  になる。
\item それ以外の場合は、
  常にゲタ記号を出力する。
\end{itemize}

\Note |\UTF|命令の多言語版、
すなわち|\UTFC|・|\UTFK|・|\UTFM|・|\UTFT|命令も|\UTF|%
と同じ扱いになる。

\paragraph{\textbackslash CID命令}
\Pkg{japanese-otf}パッケージの仕様では|\CID|命令は、PDF文字列中では
サポートされない（未定義動作となる）。
本パッケージで|otfcid|オプションを有効にした場合は、
PDF文字列中で|\CID|が“可能な限り”使えるようにする。
具体的な仕様は以下の通り。

\begin{itemize}
\item 当該のAJ1のグリフに“対応”する\textbf{単独の}Unicode文字が
  あればそれを出力し、なければ
  ゲタ記号を出力する。
  \footnote{旧版では削除していたが、他の同様の場合と合わせるため
    1.0版よりゲタ記号を出力する仕様を変更した。}
  \Note 例えば、|\CID{8226}|（ローマ数字12）はUnicode文字の
  U+217Bに“対応”するので|\Ux{217B}|と同等になるが、
  |\CID{8297}|（ローマ数字15）については“対応”する
  単独のUnicode文字がないので、ゲタ記号に置き換えられる。
\item ただし|\Ux|命令（\ref{ssec:ux-command}節参照）が
  無効になる場合は、そもそもUnicode文字も出力できないため、
  常にゲタ記号を出力する。
  結局情報は欠落するが、それでも未定義動作（エラーになる可能性もある）
  よりは好ましいであろう。
\end{itemize}

|\CID|命令の多言語版、
すなわち|\CIDC|・|\CIDK|・|\CIDT|命令についてはサポートされないので、
常にゲタ記号を出力する。

\Note |otfcid|の利用には、エンジンの{\eTeX}拡張および
\Pkg{etoolbox}と\Pkg{bxjatoucs}パッケージが必要。

\paragraph{ajmacrosパッケージの命令}
本パッケージで|otfmacros|オプションを有効にした場合は、
\Pkg{japanese-otf}付属の\Pkg{ajmacros}パッケージが提供する
文字入力命令（|\ajMaru|、|\ajLig|等）をPDF文字列中で
“可能な限り”使えるようにする。
具体的な仕様は以下の通り。

\begin{itemize}
%\item 現状では、|\Ux|命令が有効になる場合のみが
%  サポートされる。
%  \Note それ以外の場合は|otfmacros|オプションは無効になる。
\item Unicode文字で表現可能であればそれを出力し、
  なければ代替表現を出力する。
\item Unicode文字を出力する場合の仕様は|\CID|と同じ。
  （|\Ux|が無効の場合はゲタ記号になる。）
  代替表現の場合は「普通の文字の出力に置き換えられる」
  可能性がある。
  \Note 例えば、|\ajLig{ドル}|（“ドル”の組文字）はUnicode文字の
  U+3326に“対応”するので|\Ux{3326}|と同等になるが、
  |\ajLig{ウルシ}|（“ウルシ”の組文字）はUnicodeに“対応”する
  文字がないため単に“\textgt{ウルシ}”と書いたのと同等になる。
\end{itemize}

\Note |otfmacros|を有効にする場合は|otfcid|も有効にする必要がある。
（従って|otfcid|と同じ前提条件が課される。）
|otfcid|が無効な場合は|otfmacros|も無効になる。
\Note \Pkg{ajmacros}パッケージの多くの命令は脆弱（fragile）である。
そのため、節見出し（|\section|等の引数）で|\ajMaru|等の命令を
使いたい場合は、命令の前に|\protect|を付ける必要がある。
\footnote{ちなみに、引数がPDF文字列として解釈される場合には、
  |\protect|は全く結果に影響しない。}

%-------------------
\subsection{PDF文字列用の文字命令のユーザ定義}

以下の命令が提供される。（プリアンブルでのみ使用可能。）

\begin{itemize}
\item |\pxDeclarePdfTextCommand{\制御綴}{|\Meta{JIS符号値}|}{|\Meta
{Unicode符号値}|}|\Means
  PDF文字列中の|\制御綴|の動作として、
  指定した符号値の文字を出力することを指定する。
\item |\pxDeclarePdfTextComposite{\制御綴}{|\Meta{引数}|}{|\Meta
{JIS符号値}|}{|\Meta{Unicode符号値}|}|\Means
  PDF文字列中の「|\制御綴|（アクセント命令）+ \Meta{引数}」の
  動作として、指定した符号値の文字を出力することを指定する。
\end{itemize}

これらの命令において、符号値は16進数で指定する。
Unicode文字の出力が可能な状況
（エンジンが{\upLaTeX}の場合は常に該当する）
では「JIS符号値」は使われないので省略して
（空にして）もよい
\footnote{一応、「JIS符号値」が使われることが確実な状況では
「Unicode符号値」も省略可能であるが、
そのような状況であるかの判断は困難であるため、
「Unicode符号値」の省略は推奨されない。}%
（或いはそもそもJIS~X~0208にない文字の場合は省略する）。

例えば、以下のように定義しておくと、
PDF文字列中で|\textschwa|（schwa記号）や|\d{t}|（\d{t}）が
使えるようになる。
\begin{quote}\small\begin{verbatim}
\pxDeclarePdfTextCommand{\textschwa}{}{0259}
\pxDeclarePdfTextComposite{\d}{t}{}{1E6D}
\end{verbatim}\end{quote}

%-------------------
\subsection{PDF文字列用中のテキスト装飾命令の無効化}
\label{ssec:disablecmds}

PDF文字列は単なるUnicode文字列として扱われるものなので、
|\textit|や|\large|等のテキスト装飾用の命令は意味をなさず、
またそれらの命令の実装はPDF文字列の解釈中は正常に処理できない。
PDF文字列と版面出力の両方に使われるテキスト（節見出し等）
についてテキスト装飾命令が支障なく使えるように、
\Pkg{hyperref}では基本的なテキスト装飾命令
（多くは{\LaTeX}カーネルが提供するもの）
について、「PDF文字列として扱う場合は自動的に無力化
\footnote{例えば、“|\textit{text}|”や“|{\large text}|”は
  単に“|text|”と書いたものと見なされる。}
する」機構を実装している。
これにより、例えば節見出しのテキストに“|\textit{text}|”が
含まれていたとすると、
版面に出力する場合には“\textit{text}”のように装飾が施され、
一方で、PDF文字列としては“|text|”と解釈されることになる。

0.5版以降の\Pkg{pxjahyper}では、この無効化の対象に
「和文用のテキスト装飾命令（およびそれに準じるもの）」
を追加するようになった。
以下の命令が対象になる。

\begin{itemize}
\item \Pkg{hyperref}での無効化の対象である「フォント選択命令」の
  和文版に相当するもの。
  例えば、
  |\textmc| |\gtfamily| |\kanjifamily| |\romanshape|
  |\usekanji| |\useroman| |\userelfont|
  等が該当する。
\item {\pLaTeX}カーネル命令\Means
  |\<|
\item {\pTeX}プリミティブ\Means
  |\|(|dis|)|inhibitglue| |\|(|no|)|autospacing| |\|(|no|)|autoxspacing|
\item \Pkg{plext}の命令\Means
  |\bou| |\kasen| |\rensuji|
\item \Pkg{japanese-otf}の命令\Means
  |\textmg| |\mgfamily| |\ltseries| |\ebseries| |\propshape|
\item \Pkg{jsclasses}のクラスの命令\Means
  |\maybeblue| |\HUGE|
\item \Pkg{jlreq}クラスの命令\Means
  |\jafontsize| |\tatechuyoko| |\jidori| % |\jaspace| |\akigumi|
\end{itemize}

%===========================================================
\section{hyperrefの“unicodeモード”での動作}
\label{sec:Unicode-mode}

\Pkg{hyperref}パッケージの|unicode|オプションが有効である場合
（これを“unicodeモード”と呼ぶことにする
\footnote{“unicodeモード”を有効にする方法は|unicode|(|=true|)\,%
  の指定以外にも存在する。
  また、\Pkg{hyperref}の7.00g版[2021-02-04]より、
  {\pLaTeX}以外のエンジン（\Strong{{\upLaTeX}も含む}）について
  “unicodeモード”は既定で有効になっていることに注意。}%
）で動作している場合は、PDF文字列のUnicodeへの変換は
（DVIドライバ等でなく）\Pkg{hyperref}自身により行われる。
\Pkg{hyperref}が“unicodeモード”である場合には、\Pkg{pxjahyper}は
それを自動的に検知してそれに適応した動作に切り替える。
\begin{itemize}
\item |\Ux|命令は\Pkg{hyperref}の|\unichar|命令を利用して出力する。
  このため、{\pLaTeX}でもUnicode文字の出力が可能になる。
\item PDF文字列中の和文文字やLICR命令の処理は
  \Pkg{hyperref}の側に任せられる。
  \Note ただし現状では「tounicode special」の発行は
  （特に害はないため）無効化されない。
\end{itemize}
ただし、現状での“unicodeモード”対応動作には以下の制限がある。
\begin{itemize}
\item \Pkg{hyperref}の（|pdftitle|等の）パッケージオプション中での
  和文文字の処理は失敗する。
  このため、文書情報は|\hypersetup|命令で指定する必要がある。
%\item {\pLaTeX}における“unicodeモード”対応動作は試験的機能の
%  扱いであるため、その旨の警告が表示される。
%  この警告は|force-unicode|オプションを指定すれば抑止できる。
\end{itemize}

\end{document}