summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/platex/pxjahyper/pxjahyper.tex
blob: 2af226192eac127522ae8b88c3feec0ba8f3c2f3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
% 文字コードは 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{*}
\usepackage{shortvrb}
\MakeShortVerb{\|}
\newcommand{\PkgVersion}{0.9c}
\newcommand{\PkgDate}{2021/06/06}
\newcommand{\Pkg}[1]{\textsf{#1}}
\newcommand{\Meta}[1]{$\langle$\mbox{}#1\mbox{}$\rangle$}
\newcommand{\Note}{\par\noindent ※}
\newcommand{\Means}{:\quad}
\providecommand{\Strong}[1]{\textsf{#1}}
%-----------------------------------------------------------
\begin{document}
\title{\Pkg{pxjahyper} パッケージ}
\author{八登崇之\ (Takayuki YATO; aka.~``ZR'')}
\date{v\PkgVersion\quad[\PkgDate]}
\maketitle
\tableofcontents

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

(u){\pLaTeX} + hyperref + dvipdfmxの組み合わせで
日本語を含む「しおり」をもつPDF文書を作成する
場合に必要となる機能を提供する。
\begin{itemize}
\item dvipdfmx用の「tounicode special」について、
  内部漢字コードに応じて適切なものを出力する。
\item PDF文字列の中でLICR(|\"a| や |\textsection| 等の
  文字出力の命令)が正しく機能するようにする。
  ただし、エンジンが {\pTeX} の場合は、out2uni/convbkmk を利用
  する場合を除き、JIS~X~0208にない文字は出力できない
  (hyperrefの警告が出る)。
\item {\TeX} の版面拡大機能が使われている
  (|\mag| が1000でない;典型的には\Pkg{jsclasses}の
  文書クラスで基底フォントサイズが10\,pt以外である)
  場合に、\Pkg{hyperref}が出力するpapersize specialの
  紙面サイズの値が不正になるが、この場合に |\mag| 値を
  考慮して求めた正しいサイズによるpapersize specialを
  改めて出力する。
\end{itemize}

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

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

使用可能なオプションは以下の通り。
\begin{itemize}
\item \Strong{ドライバオプション}\Means
  |dvipdfmx|、|dvips|、および |nodvidriver|%
  (ドライバ依存動作の無効化を明示的に指示、
  現状ではほとんどの動作が無効になる)
  が指定できる。
  \Note 0.5版より、|nodvidriver| の別名の |none| は非推奨の扱いとする。
\item |auto|(既定)\Means
  ドライバオプションを\Pkg{hyperref}のドライバ指定から自動的に判定する。
\item |tounicode|(既定)\Means
  dvipdfmx用の「tounicode special」を発行し、
  それを前提にした出力を行う。
\item |notounicode|\Means
  dvipdfmx用の「tounicode special」を発行しない。
\item |out2uni|\Means
  out2uniフィルタを使うことを前提にした出力を行う。
\item |convbkmk|\Means
  convbkmkフィルタを使うことを前提にした出力を行う。
  \Note ドライバがdvipsの場合は既定で有効になる。
\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 詳細は\ref{ssec:otf-package}節を参照。
  \Note |otfcid| の利用には、エンジンの{\eTeX}拡張および
  \Pkg{etoolbox}と\Pkg{bxjatoucs}パッケージのインストールが必要。
\item |nootfcid|\Means
  |otfcid| の否定。
\item |disablecmds|(既定)\Means
  「PDF文字列中のテキスト装飾命令の無効化」を有効にする。
  \Note 詳細は\ref{ssec:disablecmds}節を参照。
\item |nodisablecmds|\Means
  |disablecmds| の否定。
\item |otfmacros|(既定)\Means
  \Pkg{japanese-otf}付属の\Pkg{ajmacros}パッケージが提供する
  文字入力命令(|\ajMaru|、|\ajLig| 等)をPDF文字列中で
  “可能な限り”使えるようにする。
  \Note 詳細は\ref{ssec:otf-package}節を参照。
  \Note |otfmacros| を有効にする場合は |otfcid| も有効にする必要がある。
\item |nootfmacros|\Means
  |otfmacros| の否定。
  \Note 0.6版より既定を |otfmacros| に変更した。
\item |bigcode|(既定)\Means
  {\upTeX}でのToUnicode CMapとして既定のUTF8-UCSの代わりに\ 
  UTF8-UTF16を用いる。
  (当該のファイルが存在する必要がある。)
\item |nobigcode|\Means
  |bigcode| の否定。
  \Note 0.3a版より既定を |bigcode| に変更した。
\item |papersize|(既定)\Means
  papersize specialの補正を有効にする。
\item |nopapersize|\Means
  |papersize| の否定。
\end{itemize}

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

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

%-------------------
\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{|Unicode符号値16進|}|\Means
  その符号値の文字を出力する。
  具体的な動作は以下の通り:
  \begin{itemize}
  \item エンジンが{\upLaTeX}のときは、当該の文字自体を書いたのと
  同等になる。
  \item エンジンが{\pLaTeX}で |out2uni| または |convbkmk| が有効の
  場合は、エスケープ表記(|\0xUUUU|)を出力する。
  \end{itemize}
  \item それ以外の場合は、|\Ux| は定義されない。
\end{itemize}

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

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

\begin{itemize}
\item |\Ux| 命令(\ref{ssec:ux-command}節参照)が有効の場合は、
  |\Ux| と同じ動作になる。
\item それ以外の場合
  (エンジンが{\pLaTeX}でtounicodeを前提にする場合)は、
  警告を出した上でゲタ記号を出力する。
  \Note {\pLaTeX}ではtounicodeの機能でUnicode文字を出力できないため。
\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版において仕様を変更する予定。}
\item ただし |\Ux| 命令(\ref{ssec:ux-command}節参照)が
  無効になる場合は、そもそもUnicode文字も出力できないため、
  常に(警告を出した上で)ゲタ記号を出力する。
  結局情報は欠落するが、それでも未定義動作(エラーになりえる)
  よりは好ましいであろう。
\end{itemize}

\Note |otfcid| の利用には、エンジンの{\eTeX}拡張および
\Pkg{etoolbox}と\Pkg{bxjatoucs}パッケージのインストールが必要。
\Note |\CID| 命令の多言語版はサポートされない。

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

\begin{itemize}
\item 現状では、|\Ux| 命令が有効になる場合のみが
  サポートされる。
  \Note それ以外の場合は |otfmacros| オプションは無効になる。
\item Unicode文字で表現可能であればそれを出力し、
  なければ代替表現を出力する。
\item Unicode文字を出力する場合の仕様は |\CID| と同じ。
  代替表現の場合は文字自体が出力されることもある。
\end{itemize}

\Note |otfmacros| を有効にする場合は |otfcid| も有効にする必要がある。
(従って |otfcid| と同じ前提条件が課される。)
|nootfcid| を指定した場合は |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進数で指定する。
「JIS符号値」は {\upLaTeX} では使われないので省略して
(空にして)もよい
(或いはそもそも JIS~X~0208 にない文字の場合は省略する)。
逆に「Unicode符号値」は {\pLaTeX} の動作でかつ「JIS符号値」が
指定されている場合は省略してよい。

例えば、以下のように定義しておくと、
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 和文のフォント選択命令\Means
  |\textmc| |\gtfamily| |\kanjifamily| |\useroman| |\userelfont|
  など
\item 次の{\pLaTeX}カーネル命令\Means
  |\<|
\item 次の{\pTeX}プリミティブ\Means
  |\inhibitglue| |\|(|no|)|autospacing| |\|(|no|)|autoxspacing|
\item 次の\Pkg{plext}の命令\Means
  |\bou| |\kasen| |\rensuji|
\item 次の\Pkg{japanese-otf}の命令\Means
  |\textmg| |\mgfamily| |\ltseries| |\ebseries| |\propshape|
\end{itemize}

\end{document}