%#!make pbibtex-manual.pdf
\documentclass[a4paper,11pt,nomag,dvipdfmx]{jsarticle}
\usepackage[textwidth=42zw,lines=40,truedimen,centering]{geometry}

%%%%%%%%%%%%%%%%
% additional packages
\usepackage{amsmath}
\usepackage{array}\usepackage[all]{xy}
\SelectTips{cm}{}
%\usepackage[dvipdfmx]{graphicx}
\usepackage[T1]{fontenc}
\usepackage{booktabs,enumitem,multicol}
\usepackage[defaultsups]{newpxtext}
\usepackage[zerostyle=c,straightquotes]{newtxtt}
\usepackage{newpxmath}
\usepackage[hyperfootnotes=false]{hyperref}
\usepackage{pxjahyper}
\usepackage{hologo}

% common
\usepackage{../ptex-manual/ptex-manual}

\def\code#1{\texttt{#1}}
\def\file#1{\texttt{#1}}
\def\codechar#1{\ensuremath{\langle\mbox{\null\code{#1}\null}\rangle}}

%%%%%%%%%%%%%%%%
\makeatletter
\setlist{leftmargin=2zw}
\setlist[description]{labelwidth=2zw,labelindent=1zw,topsep=\medskipamount}

\def\>{\ifhmode\hskip\xkanjiskip\fi}

\def\tsp{_{\mbox{\fontsize\sf@size\z@\ttfamily \char32}}}
\def\tpar{_{\mbox{\fontsize\sf@size\z@\ttfamily \string\par}}}
\def\tign{_{\mbox{\fontsize\sf@size\z@\selectfont --}}}

\def\tableautorefname{表}
\def\figureautorefname{図}
\def\HyRef@autoref#1#2{%
  \begingroup
    \Hy@safe@activestrue
    \expandafter\HyRef@autosetref\csname r@#2\endcsname{#2}{#1}%
  \endgroup\textcompwordmark %欧文ゴースト
}
\makeatother

\usepackage{shortvrb}
\MakeShortVerb*{|}
%%%%%%%%%%%%%%%%

% logos
\def\JTeX{\leavevmode\textcompwordmark\lower.5ex\hbox{J}\kern-.17em\TeX}
\def\JBibTeX{\leavevmode\textcompwordmark\lower.5ex\hbox{J}\kern-.08em\BibTeX}
\def\pBibTeX{p\kern-.05em\BibTeX}
\def\upBibTeX{u\pBibTeX}

% additions to jslogo.sty
\makeatletter
\g@addto@macro\pdfstringdefPreHook{%
  \def\JBibTeX{J\BibTeX}%
  \def\pBibTeX{p\BibTeX}%
  \def\upBibTeX{u\pBibTeX}%
}
\makeatother

\def\TL{\TeX\ Live}

\def\_{\leavevmode\vrule width .45em height -.2ex depth .3ex\relax}

\frenchspacing
\begin{document}
\catcode`\<=13
\title{\emph{\pBibTeX~/~\upBibTeX マニュアル}}
\author{日本語\TeX 開発コミュニティ\null
\thanks{\url{https://texjp.org},\ e-mail: \texttt{issue(at)texjp.org}}}
\date{version 0.99d-j0.34，\today}
\maketitle

\pBibTeX と\upBibTeX は，それぞれ\pTeX と\upTeX と組み合わせて使用することを
想定して開発された\BibTeX の日本語対応版である．
\begin{itemize}
  \item \pBibTeX の開発元：\\
    \url{https://github.com/texjporg/tex-jp-build/}
  \item \upBibTeX の開発元：\\
    \url{http://www.t-lab.opal.ne.jp/tex/uptex.html}
  \item 本ドキュメントの開発元：\\
    \url{https://github.com/texjporg/pbibtex-manual/}
\end{itemize}

\BibTeX の日本語化は，電力中央研究所の松井正一氏によって
\JBibTeX という名称で公開されたもの\footnote{%
最終版は\JBibTeX~0.31である．1991/01/01付の\JBibTeX~0.30のパッケージに，
1992/10/31にfj.comp.texhaxグループへ投稿されたバグ修正パッチ(0.31)を
当てて得られる．}がベースであり，その仕様は\cite{jbibtex}に詳しい．
また，オリジナルの\BibTeX 付属ドキュメント\file{btxdoc.pdf}と
\file{btxhak.pdf}を日本語に訳し，\JBibTeX について補足を加えたドキュメントも
用意されている\cite{jbtxdoc,jbtxhak}．
これらのドキュメントは，レガシーエンコーディングの扱いに関する
記述（第\ref{diff}節を参照）を除き
現在の(u)\pBibTeX でも有効であるので，参照されたい．

本文書では，オリジナルの\BibTeX の仕様を把握している読者を想定し，
\pBibTeX および\upBibTeX における機能の変更・追加点を説明する．

\tableofcontents
\clearpage

\section{日本語化の仕様}

\BibTeX の日本語化の特徴は，大きく分けて3つである．
\begin{itemize}
 \item 多バイト文字の扱い
 \item 文字種が増えたことへの対応
 \item 日本語文字とそれ以外の区別
\end{itemize}

\subsection{多バイト文字の扱い}\label{sec:substring}

(u)\pBibTeX は，\BibTeX から最小の変更量で日本語を含む文献情報を
扱えるようにした都合上，多バイト文字の扱いは以下のとおりとなっている．
\begin{itemize}
 \item \emph{文字列の位置や長さは「文字単位」ではなく「バイト単位」でカウントする}．
 \item その結果として，開始位置や終了位置が多バイト文字の途中となる場合は，
   \emph{多バイト文字の途中で切られないように位置を調整する}．
\end{itemize}

具体的には，以下のスタイルパラメータが該当する．
\begin{itemize}
 \item |substring$|\\
  整数値2つ（長さ，起点）と文字列リテラル1つをpopし，
  指定の長さ（バイト長）の部分文字列をpushする組込関数である．
  起点に指定された整数値が正であれば文字列の先頭から，
  負であれば末尾から長さを数えて取り出す．

  多バイト文字についての開始・終了位置の調整は以下の順で行う．
\begin{quotation}
  \begin{enumerate}
   \item[(1)] 開始位置が多バイト文字の2バイト目以降であれば，1バイト目から取り出す．
   \item[(2)] 終了位置が多バイト文字の最終バイトでなければ，最終バイトまで取り出す．
  \end{enumerate}
\end{quotation}
  したがって，この時点で\pBibTeX （内部コード|euc|）では最大2バイト長く，
  \upBibTeX （内部コード|uptex|）では最大6バイト長い文字列が取り出されうる．

  さらに，(u)\pBibTeX~j0.34 (\TeX~Live 2022)以降では% r62095 (2022-02-20)
\begin{quotation}
  \begin{enumerate}
   \item[(3)] 起点が|#2|以上に指定されたにもかかわらず，上の(1)の調整により
     開始位置が文字列の先頭になってしまった場合は，
     その先頭の多バイト文字を切り捨てる．
   \item[(4)] 起点が|#-2|以下に指定されたにもかかわらず，上の(2)の調整により
     終了位置が文字列の末尾になってしまった場合は，
     その末尾の多バイト文字を切り捨てる．
  \end{enumerate}
\end{quotation}
  という調整も加えてある．したがって，\pBibTeX では最大1バイト短く，
  \upBibTeX では最大3バイト短くなる（場合によっては空になる）ことがある．

 \item |text.prefix$|\\
  整数値（長さ）と文字列リテラルをpopし，文字列の先頭から指定の長さ（バイト長）の
  連続した文字列をpushする組込関数である．
  終了位置が多バイトの文字の途中にならないよう調整されるので，
  \pBibTeX （内部コード|euc|）では最大1バイト長く，
  \upBibTeX （内部コード|uptex|）では最大3バイト長い文字列が取り出されうる．
\end{itemize}

以下に例を示す．
% 例示ソース：tests/01jtest
% https://oku.edu.mie-u.ac.jp/tex/mod/forum/discuss.php?d=2006
\pBibTeX と\upBibTeX では同じ文字でもバイト長が異なる場合があり，
その結果として取り出される見かけの文字数が異なることに注意．

\par\medskip\noindent
\begin{minipage}{0.45\textwidth}
\begin{verbatim}
例1：長めに調整(2)
"あいうえお" #1 #1 substring$
"あいうえお" #1 #2 substring$
"あいうえお" #1 #3 substring$
"あいうえお" #1 #4 substring$
"あいうえお" #1 #5 substring$
"あいうえお" #1 #6 substring$
\end{verbatim}
\end{minipage}
\begin{minipage}{0.5\textwidth}
\begin{tabular}{lll}
            & \pBibTeX   & \upBibTeX \\
最初の1文字 & 「あ」     & 「あ」    \\
最初の2文字 & 「あ」     & 「あ」    \\
最初の3文字 & 「あい」   & 「あ」    \\
最初の4文字 & 「あい」   & 「あい」  \\
最初の5文字 & 「あいう」 & 「あい」  \\
最初の6文字 & 「あいう」 & 「あい」
\end{tabular}
\end{minipage}

\par\medskip\noindent
\begin{minipage}{0.45\textwidth}
\begin{verbatim}
例2：長めに調整(1)
"あいうえお" #-1 #1 substring$
"あいうえお" #-1 #2 substring$
"あいうえお" #-1 #3 substring$
"あいうえお" #-1 #4 substring$
"あいうえお" #-1 #5 substring$
"あいうえお" #-1 #6 substring$
\end{verbatim}
\end{minipage}
\begin{minipage}{0.5\textwidth}
\begin{tabular}{lll}
            & \pBibTeX   & \upBibTeX \\
最後の1文字 & 「お」     & 「お」    \\
最後の2文字 & 「お」     & 「お」    \\
最後の3文字 & 「えお」   & 「お」    \\
最後の4文字 & 「えお」   & 「えお」  \\
最後の5文字 & 「うえお」 & 「えお」  \\
最後の6文字 & 「うえお」 & 「えお」
\end{tabular}
\end{minipage}

\par\medskip\noindent
\begin{minipage}{0.45\textwidth}
\begin{verbatim}
例3：先頭文字の途中調整(3)
"あいうえお" #1 #6 substring$
"あいうえお" #2 #5 substring$
"あいうえお" #3 #4 substring$
"あいうえお" #4 #3 substring$
"あいうえお" #5 #2 substring$
"あいうえお" #6 #1 substring$
\end{verbatim}
\end{minipage}
\begin{minipage}{0.5\textwidth}
\begin{tabular}{lll}
                       & \pBibTeX   & \upBibTeX \\
最初の6文字            & 「あいう」 & 「あい」  \\
最初の1文字を除く5文字 & 「いう」   & 「い」    \\
最初の2文字を除く4文字 & 「いう」   & 「い」    \\
最初の3文字を除く3文字 & 「いう」   & 「い」    \\
最初の4文字を除く2文字 & 「う」     & 「い」    \\
最初の5文字を除く1文字 & 「う」     & 「い」
\end{tabular}
\end{minipage}

\par\medskip\noindent
\begin{minipage}{0.45\textwidth}
\begin{verbatim}
例4：末尾文字の途中調整(4)
"あいうえお" #-1 #6 substring$
"あいうえお" #-2 #5 substring$
"あいうえお" #-3 #4 substring$
"あいうえお" #-4 #3 substring$
"あいうえお" #-5 #2 substring$
"あいうえお" #-6 #1 substring$
\end{verbatim}
\end{minipage}
\begin{minipage}{0.5\textwidth}
\begin{tabular}{lll}
                       & \pBibTeX   & \upBibTeX \\
最後の6文字            & 「うえお」 & 「えお」  \\
最後の1文字を除く5文字 & 「うえ」   & 「え」    \\
最後の2文字を除く4文字 & 「うえ」   & 「え」    \\
最後の3文字を除く3文字 & 「うえ」   & 「え」    \\
最後の4文字を除く2文字 & 「う」     & 「え」    \\
最後の5文字を除く1文字 & 「う」     & 「え」
\end{tabular}
\end{minipage}

\par\medskip
\begin{dangerous}
  (u)\pBibTeX~j0.33 (\TeX~Live 2021)以前の|substring$|では，
  オリジナルの\JBibTeX と同様，上記のうち調整(1)と(2)しか
  行っていなかった．すなわち「開始位置や終了位置が多バイトの文字の
  途中となる場合は，位置を調整して\emph{常に長めに切り出す}」という
  仕様であった．しかし，これでは
\begin{verbatim}
"（あいうえお" #2 global.max$ substring$  % 最初の1文字を除去したい
"あいうえお）" #-2 global.max$ substring$ % 最後の1文字を除去したい
\end{verbatim}
  のような場合に文字を除去できず，例えば「|while$|ループ内で
  |substring$|関数により文字列を1つずつ切り詰めて短くする処理」に
  和文文字リテラルが渡ると文字列が一向に短くならず，
  無限ループが起きてしまっていた\cite{tjb133}．
  そこで，(u)\pBibTeX~j0.34 (\TeX~Live 2022)以降は調整(3)と(4)を加え，
  \emph{カウント起点が「先頭の多バイト文字の途中」または「末尾の多バイト文字の
  途中」の場合に限って取り除くことで短めに切り出す}こととした．
  なお，カウント終点側の多バイト文字については常に長めに切り出すし，
  カウント起点が先頭でも末尾でもない多バイト文字の場合は長めに切り出す
  という点は従来と同じである．上記の例を見るのが早いであろう．
\end{dangerous}

\subsection{文字種が増えたことへの対応}

\begin{itemize}
 \item |add.period$|\\
  文字列リテラルをpopし，最後の文字（|}|を除く）がピリオド類
  \codechar{.}\codechar{?}\codechar{!}のいずれでもないときに
  \codechar{.}を最後に加える組込関数である．

  \pBibTeX では，全角の\codechar{！}\codechar{？}\codechar{．}\codechar{。}
  （それぞれU+FF01, U+FF1F, U+3002, U+FF0E）もピリオド類とみなし，
  これらで終わっても\codechar{.}を付加しない．

  \upBibTeX ではさらにU+203C, U+2047, U+2048, U+2049もピリオド類とみなす．

 \item |format.name$|\\
  文字列（フォーマット指定），整数値（何番めか），文字列（名前リスト）をpopし，
  フォーマットされた名前の文字列をpushする組込関数である．\\
  (u)\pBibTeX では，日本人の姓名の間のスペースとして全角空白U+3000も
  半角空白と同じとみなし（全角空白は半角空白に変換して処理），
  また複数の氏名間の区切りとして|and|と同様に
  全角の読点\codechar{、}とコンマ\codechar{，}（それぞれU+FF0C, U+3001）も使える．
\end{itemize}

\subsection{日本語文字とそれ以外の区別}

\begin{itemize}
 \item |is.kanji.str$|\\
  (u)\pBibTeX 独自の組込関数である．
  スタックトップの文字列リテラルをpopし，
  文字列中に「日本語文字」が1つでも含まれていれば整数値1を，
  含まれなければ0をpushする．
  なお，「日本語文字」かどうかの判定は以下のように行う．
  \begin{itemize}
   \item \pBibTeX の場合\\
    ASCIIの範囲(0--127)に収まらない文字を全て「日本語文字」として扱う．
   \item \upBibTeX （内部コード|uptex|）の場合\\
    漢字・かな・ハングルに該当するUnicodeブロックの文字を「日本語文字」と
    して扱う\footnote{実装上は\upTeX の\.{kcatcode}と同じブロック分けを流用して
    いるのでそれに即して記述すると，既定値が16 (kanji), 17 (kana), 19 (hangul)の
    ブロックを真，15 (latin), 18 (CJK symbol)のブロックを偽としている．}．
    \pBibTeX とは異なり，記号類（句読点，括弧類，●○■□◆◇など）は「日本語文字」と
    して扱わない（バージョンu1.27（\TL~2021）以降\cite{tjb109}）．
  \end{itemize}
\end{itemize}

(u)\pBibTeX 用のスタイルファイルでは，しばしば著者名のフォーマットで
「日本人の姓名の間にはスペースを入れない」という挙動を実現するために
|is.kanji.str$|関数が実用されているし，
他にも``, et~al.''の代わりに「ほか」としたり``Vol.~2''の代わりに「第2巻」と
したりといったローカライズにも多用されている．

\begin{dangerous}
  |is.kanji.str$|について，\pBibTeX は松井氏の\JBibTeX の仕様を踏襲している．
  \upBibTeX のバージョンu1.27以降では上記の調整を行っているが，これは
  \begin{itemize}
   \item |is.kanji.str$|が「日本語文字」が
         \emph{最低1つでも含まれていれば}真となること
   \item 各種スタイルファイルで「著者名の文字列について
         |is.kanji.str$|が真ならば姓名の間にスペースを入れないという
         使われ方が多いこと
  \end{itemize}
  を踏まえたものである．少なくともラテン文字(15)はASCIIの範囲(0--127)に
  収まらないが欧文扱いされたほうが都合がよいし，
  さもないとErwin Schrödingerのような姓名の間のスペースが失われてしまう．
  また，記号類(18)の一部は欧文の文脈で使われる可能性もある\footnote{さらに言えば
  ギリシャ文字とキリル文字も一部JIS~X~0208に含まれ，(u)\pTeX の既定で和文扱い
  される（いわゆる全角文字である）し，\upTeX での\.{kcatcode}はともに18で
  記号類と同じ扱いである（ちなみに\pTeX ではギリシャ文字は17，キリル文字は18）．}．
  上記の調整を行うことで，文字列全体で見たときに「日本語の文脈なら真，
  そうでなければ偽」となるので都合がよいという算段である．
  なお，漢字・かな・ハングルの文字で真としているのは，日本人・中国人・韓国人の
  姓名の間にはスペースを入れない記法がよく行われることに依る．
\end{dangerous}

\subsection{その他詳細}\label{sec:jnewline}

(u)\pBibTeX は，文献データベース（BIBファイル）を読み込んで文献リスト（BBLファイル）を
出力するが，ファイルの行末の扱いは以下のとおりである．% r62001 (2022-02-08)
\begin{itemize}
 \item \emph{入力BIBファイル内}の改行は，(u)\pBibTeX では一律に半角空白と同様に扱われる．
   すなわち，(u)\pTeX とは異なり\emph{日本語文字直後の改行も半角空白と等価である}．
 \item \emph{BBLファイルの出力時}に，長いエントリを一行に出力するか複数行に分割するか決定
   する場面において，オリジナルの\BibTeX は任意の半角空白を分割可能箇所とみなす
   \footnote{\BibTeX~0.99c以前では半角空白以外の箇所も行末に\code{\%}を補って改行された
   が，2010年の0.99dでURLなどの長い文字列を壊さないように半角空白以外での分割が
   禁止された．}が，(u)\pBibTeX~j0.34 (\TeX~Live 2022)以降は\emph{日本語文字の直後でない
   半角空白のみを分割可能箇所とみなす}．これは，元々BIBファイルにあった日本語文字直後の
   半角空白が仮にBBLファイルで改行に置換されれば，(u)\pTeX での読込時に「日本語文字直後の
   改行は空白を発生しない」という仕様により半角空白が消えてしまうためである\cite{tjb132}．
   % ここでの「日本語文字」は\pBibTeX/\upBibTeX ともに単に「ASCIIの範囲(0--127)に
   % 収まらない文字」としている（\upBibTeX でも|is.kanji.str$|のような調整は行わないし
   % 敢えて改行を増やす必要はない）．
\end{itemize}


\section{コマンドラインオプション}

基本的には\BibTeX と同様であるが，以下が追加されている．
\begin{itemize}
 \item |-kanji=|<encoding>\\
   入出力ファイルの文字コードを指定する．
   利用可能な<encoding>の値：
   \begin{itemize}
    \item \pBibTeX ：\code{euc}, \code{sjis}, \code{jis}, \code{utf8}
    \item \upBibTeX ：\code{euc}, \code{sjis}, \code{jis}, \code{utf8}, \code{uptex}
   \end{itemize}
 \item |-kanji-internal=|<encoding>\\
   内部コードを指定する（\upBibTeX 専用）．
   利用可能な<encoding>の値：
   \begin{itemize}
    \item \pBibTeX ：なし（常に\code{euc}に固定）
    \item \upBibTeX ：\code{euc}, \code{uptex}
   \end{itemize}
\end{itemize}


\section{参考：\JBibTeX と\pBibTeX の違い}\label{diff}

松井氏による\JBibTeX~0.31（\BibTeX~0.99cベース）から
現在の\pBibTeX に至った経緯は以下のとおりである．
\begin{itemize}
 \item 1994年，都立大（のち千葉大）の桜井貴文氏により，
   \JTeX~1.6 (web2c~6.1)の配布キットに含めるための調整 → \JBibTeX~0.32
 \item 1995年，アスキー\pTeX の配布キットに含めるための調整
 \item 2002年，アスキーにより|-kanji|オプションの追加 → \JBibTeX~0.33
 \item 2009年，日本語\TeX 開発コミュニティが\JBibTeX をフォークし，\pBibTeX に改名
 \item 2010年，\pBibTeX が\pTeX とともに\TL へ収録される．のちに\BibTeX~0.99d対応
 \item 2012年，\upBibTeX が\upTeX とともに\TL へ収録される．
 \item 2022年，出力BBLファイルでの行分割の改良（第\ref{sec:jnewline}節を参照）\\
   |substring$|関数の改良（第\ref{sec:substring}節を参照） → \pBibTeX~j0.34
\end{itemize}

\JBibTeX は当初NTT \JTeX と組み合わせて使用することを想定して開発されたため，
文字コードに関する扱いにNTT \JTeX 由来のものが多かった．
これらはコマンド名が|jbibtex|から|pbibtex|（\pTeX と同じ接頭辞）
に改名された2009年に削除された\cite{ptexlive}ため，\pBibTeX は\JBibTeX と
以下の点で異なっている：
\begin{itemize}
 \item JISコードにおいて日本語文字コード開始・終了を示す
  種々のエスケープ・シーケンス（|ESC$@|と|ESC$B|，|ESC(J|と|ESC(B|など）を区別しない．
 \item 環境変数|BIBTERMCODE|, |BIBFILECODE|\footnote{松井氏のドキュメント
  \file{jbibtex.pdf} \cite{jbibtex}の「3.3 漢字コードの扱い」および
  \file{jbtxdoc.pdf} \cite{jbtxdoc}の「1. 概要」の\JBibTeX での注意点として
  言及されているもの．}は，\pBibTeX では参照されない．
\end{itemize}


\clearpage
\begin{thebibliography}{99}
 \bibitem{jbibtex} 松井正一，「日本語\BibTeX ：\JBibTeX」，
  \file{./jbibtex.pdf}
 \bibitem{jbtxdoc} 松井正一，「\BibTeX ing：\BibTeX の使い方」，
  \file{./jbtxdoc.pdf}
 \bibitem{jbtxhak} 松井正一，「Designing \BibTeX\ Styles --- \BibTeX スタイルの作り方」，
  \file{./jbtxhak.pdf}
 \bibitem{ptexlive} 土村展之，「コマンド名問題 - ptexlive Wiki」\\
  \url{https://tutimura.ath.cx/ptexlive/?%A5%B3%A5%DE%A5%F3%A5%C9%CC%BE%CC%E4%C2%EA}
 \bibitem{tjb109} Haruhiko Okumura，「upbibtexで名と姓の間のスペースが消える」，
  2020/10/11,\\
  \url{https://github.com/texjporg/tex-jp-build/issues/109}
 \bibitem{tjb132} Hironobu Yamashita，「(u)pbibtexで和文文字直後の半角スペースで改行が起きる」，
  2022/02/07,\\
  \url{https://github.com/texjporg/pbibtex-manual/issues/1}
 \bibitem{tjb133} Hironobu Yamashita，「(u)pbibtex: freeze at en-dash etc. + sieicej.bst」，
  2022/02/19,\\
  \url{https://github.com/texjporg/tex-jp-build/issues/133}
\end{thebibliography}

\end{document}