path: root/Master/texmf-dist/doc/latex/bxbase/README

==================================================
== BXbase バンドル v0.5  <2010/06/15>           ==
==           by「ZR」（八登 崇之/Takayuki YATO）==
==                      <zrbabbler@yahoo.co.jp> ==
==================================================
(This file is encoded in UTF-8,)

欧文 LaTeX2e における多言語文書およびそれに関わるマクロパッケージの作成
を支援する基本的な機能を提供する。

  - bxutf8 入力エンコーディング: UTF-8 入力
  - bxutf8x 入力エンコーディング: UTF-8 入力
  - bxbase パッケージ: 基礎ライブラリ
  - bxucs パッケージ: 欧文 Unicode 文字出力

※ 対応環境は各々のパッケージの解説を参照。

■ 本ソフトウェアの一次配布サイト(作者のサイト)

    En toi Pythmeni tes TeXnopoleos 〜電脳世界の奥底にて〜
    http://zrbabbler.hp.infoseek.co.jp/

    ※ 以下のページに一部機能の使用例を紹介した。
    「Unicode による文字入力」
    http://zrbabbler.hp.infoseek.co.jp/unichar.html
    「BXbase パッケージ」
    http://zrbabbler.hp.infoseek.co.jp/bxbase.html

■ インストール

    TDS 1.1 に従ったシステムでは、各ファイルを次の場所に移動する。
    ・*.sty, *.def → $TEXMF/tex/latex/BXbase/
    (残りのファイルは不要)

    W32TeX を C:\usr\local にインストールした場合の例。
    ・*.sty, *.def → C:\usr\local\share\texmf-local\tex\latex\BXbase

--------------------------------------------------
 bxutf8 入力エンコーディング (v0.5) -- UTF-8 入力 
--------------------------------------------------

LaTeX2e 標準の utf8 入力エンコーディングを拡張して、utf8 で処理できない
文字について符号値を含む中間形式に変換する。この中間形式は他のパッケージ
が処理することが想定されている。

■ 対応環境

    欧文 LaTeX2e / pLaTeX2e / upLaTeX2e

■ 読込

    inputenc のオプションとして指定する。
      \usepackage[bxutf8]{inputenc}

    inputenc が読み込み済の場合は \inputencoding を使う。
      \inputencoding{bxutf8}

    本文中で他の入力エンコーディングとの間で切り替えることも可能であるが、
    その場合は、一度プレアンブルのどこかで入力エンコーディングを bxutf8
    に切り替えなければならない(bxutf8.def が内部で読み込む utf8.def の
    仕様による)。本文での切り替えはあまりテストされていないので、バグが
    ある可能性が高い ;-)

■ 機能

    bxutf8 は utf8 の拡張である。utf8 は UTF-8 で書かれた文字を次のよう
    に処理する。その文字が出力方法を知っている—つまり読込済のフォント
    エンコーディングに含まれる—文字の場合、それを LaTeX の標準的な内部
    形式(\"a や \OE 等)に変換して後をフォントエンコーディング(fontenc)
    の処理に任せる。しかし、知らない文字の場合はエラーになる。

    bxutf8 は「知らない文字」の場合の処理を変更し、これを \bxUHex{XXXX}
    の形式に変換する。ここで XXXX は該当の文字のコード値の 16 進表現で
    ある。\bxUHex は該当の文字を出力することが想定されているが、これの
    定義(「ドライバ」と呼ぶことにする)は他のパッケージで与えられる。
    bxutf8 自身のドライバの定義は単にエラーを出すだけである。

■ 注意事項

    - UTF-8 のバイト列から \bxUHex の形式までは完全展開可能になっている。
      また、\bxUHex の定義は robust でなければならない。これは他の入力
      エンコーディングと共通の性質である。
    - 0.5 版の改訂で、BMP 外(U+10000 以上)の符号値に対応した。
    - pLaTeX/upLaTeX の場合、入力漢字コードは UTF-8 (-kanji=utf8) である
      必要がある。この場合、処理系により和文トークンと解釈される文字以外
      が bxutf8 の処理に回る。
    - utf8 が扱える文字については飽くまでも utf8 と全く同じように処理
      されることに注意。例えば、フォントエンコーディングに OT1 と T2A が
      読み込まれている状態で「Д」が入力されると、utf8 はこれを \CYRD に
      変換するが、これは現在のフォントエンコーディングが OT1 である時は
      エラーになる(たとえ \bxUHex がフォントエンコーディングに関わらず
      動作するとしても)。


---------------------------------------------------
 bxutf8x 入力エンコーディング (v0.3) -- UTF-8 入力 
---------------------------------------------------

Unicode パッケージ(ucs パッケージ)が使用する utf8x 入力エンコーディング
を拡張して、bxutf8 と同様の機能を実現したものである。

■ 対応環境

    欧文 LaTeX2e / pLaTeX2e / upLaTeX2e

■ 読込

    inputenc のオプションとして指定する。
      \usepackage[bxutf8]{inputenc}

    inputenc が読み込み済の場合は \inputencoding を使う。
      \inputencoding{bxutf8}

    後者の使用については、bxutf8 と同じ制限の他に、utf8x に特有の制限
    がある。

■ 機能

    基本的には bxutf8 と同じなので、相違点を挙げておく。

    - utf8x (ucs) のプログラムは utf8 と比して遥かに複雑である。従って
      bxutf8x が正しく実装されているかについてはあまり自信が無い。
    - bxutf8x は \bxUInt という内部命令を用いる。
    - utf8x は実際にフォントエンコーディングが読み込まれているかに関わら
      ず広範な範囲の文字を自分で処理しようとする。結果的に、欧文の文字に
      関してはほとんど \bxUInt に変換されない。CJK 文字に対しては utf8x
      は既定では処理しないので \bxUInt に変換される。


--------------------------------------------
 bxbase パッケージ (v0.5) -- 基礎ライブラリ 
--------------------------------------------

他の BX シリーズのパッケージの下請けが主な役目である。文書作成者がこの
パッケージを読み込む場面は少ない。

■ 対応環境

    欧文 LaTeX2e / pLaTeX2e / upLaTeX2e

■ 読込

    \usepackage で読み込む。オプションはない。

■ pxbase パッケージとの関係

    bxbase パッケージと pxbase パッケージ(PX シリーズ)は大部分の機能を
    共通にしている。両方読み込んだ場合は、共通する機能については版が
    新しい方が採用される。過去互換性を崩す更新は行われないので、このこと
    に関して文書作成者が気にする必要はないはずである。

    なお、現在の所、bxbase のみに存在する機能はない。

■ 機能

    DVI special 出力の命令。

    \recordpapersize
      次の形の papersize special 命令を DVI の先頭に出力する。
        papersize=<幅>,<高さ>
      (幅と高さは現在の \paperwidth と \paperheight の値。)

    \dvipdfmxmapline{<テキスト>}
      dvipdfmx のマップ指定を文書中で行う。
      ※次の形の papersize special 命令を DVI の先頭に出力する。
        pdf:mapline <テキスト>

    \dvipdfmxmapfile{<ファイル名>}
      dvipdfmx のマップファイル指定を文書中で行う。
      ※次の形の papersize special 命令を DVI の先頭に出力する。
        pdf:mapfile <ファイル名>

    符号値による文字入力のための命令。

    \Ux{<コード値>,...}
    \UI{<コード値>,...}
      Unicode コード値による入力を行う。\Ux は欧文用、\UI は和文用(I は
      Ideographic の意味)。コード値は以下の形式で表す。コンマで区切って
      複数文字入力できる。
        - <16進数>:  A72C, 02000B, 1bd 等。
        - +<10進数>: +254, +0937 等。
        - '<8進数>:  '376, '1651 等。
      Unicode 文字の出力には次の順番で利用可能な最初の機能を用いる。(\UI
      の場合 3) を飛ばす。)
        1) zxjatype パッケージ。この場合、その機構に従って出力される。\UI
           は必ず和文フォントで出力し、\Ux は和文/欧文切替の対象となる。
        2) XeTeX の Unicode 出力。
        3) [\Ux のみ] bxums パッケージ。
        4) upTeX の和文 Unicode 出力。
        5) UTF/OTF/pxotf パッケージ。
        6) ums/bxsuika パッケージ。
      どれも使えない場合は「16進表現による代替表現」になる。

    \AJ{<コード値>,...}
      Adobe-Japan1 のコード値による入力を行う。コード値は 10 進数で指定
      する。出力には次の順番で利用可能な最初の機能を用いる。
        1) zxotf パッケージ。
        2) UTF/OTF/pxotf パッケージ。
      どれも使えない場合は代替表現になる。

    \JI{<コード値>,...}
      いわゆる「JIS コード」（JIS X 0208 の GL 表現）のコード値による入力
      を行う。コード値指定の方法は \Ux と同じ。出力には (u)pTeX の JIS
      コード和文出力の機能を使う。使えない場合は代替表現になる。

    \KI{<コード値>,...}
      いわゆる「区点コード」のコード値による入力を行う。コード値指定は
      以下のいずれかの方法で指定する。
        - RRCC : RR は区番号、CC は点番号を 10 進 2 桁で表したもの。
        - PRRCC : P は面番号。JIS X 0213 のための指定。
      出力には (u)pTeX の JIS コード和文出力の機能を使う。使えない場合は
      代替表現になる。JIS X 0213 の文字を出力したい場合は、現在の和文
      フォントのエンコーディングが JIS X 0213 に対応するものである必要が
      ある。さらに、第 2 面の文字を出力する場合には pTeX の内部漢字コード
      が sjis でなければならない。

    \bxUx / \bxUI / \bxAJ / \bxJI / \bxKI
       \Ux 等は非常に短い名前なので他のパッケージと衝突する恐れがあり、
       そこでこのパッケージでは既に同名の命令がある場合は上書きしない
       ようにしている。\bxUx 等はそれぞれ \Ux 等と同じで、先のような場合
       にも常に使える。

    加えて、このパッケージは bxutf8 の為のドライバ \bxUHex および bxutf8x
    の為のドライバを \Ux に相当するものに設定する。

    以下のものは本来は和文用の命令であるが、理由があって bxbase にも含めて
    いる。pxbase と共通なので詳細は PXbase の説明書を参照してほしい。

    \safecaret
      TeX エスケープ形式(^^ab)の解釈が失敗するのを回避する。

    Bwbel 関係の命令。

    \bxcaptionlanguage{<言語名>}
      Babel では、通常言語が切り替わるとキャプションや日付の文字列が切り
      替わる。この命令を実行すると、文字列は指定された言語のもので固定
      され、Babel の言語切替の命令に追随しなくなる。この命令自体はプレ
      アンブル中で何回でも使用できて最後のものが有効になる。引数には有効
      な言語オプションの名前の他に以下のものが指定できる。
        - main : 基底言語、すなわち Babel で最後に読み込まれた言語だが
          次に述べる \bxmainlanguage で変更可能。
        - default : 文書クラスで指定されたものをそのまま用いる。日本語
          の文書クラスで Babel を用いる時に便利である。
      この命令の意義については後の「キャプション文字列の切替機能について」
      の節を参照。

    \bxmainlanguage{<言語名>}
      基底言語、すなわち \begin{document} の直後において有効となる言語を
      設定する。通常は Babel において最後に読み込まれた言語オプションが
      基底言語になる。

■ キャプション文字列の切替機能について

    Babel の機能の 1 つとして、言語の切替に伴って、キャプションの文字列
    (「参考文献」や「図」等)および日付の書式をその言語用のものに切り替え
    るというものがある。これにより、ある言語(例えばスロベニア語)の為の
    文書クラスがなくても英語用のクラスと Babel の言語切替でスロベニア語
    のキャプションの文書が作成できる(レイアウトがその言語の使用圏で許容
    されるかの問題は残るが)。だがこの目的には、プレアンブルでキャプション
    言語を 1 回指定できればよく、文書途中での言語切替にまでキャプション
    が追随する利点はあまりなく、場合によっては弊害があると思われる。この
    ような場合は
      \bxcaptionlanguage{main}
    を実行すれば、キャプションは基底言語(\bxmainlanguage の説明参照)で
    固定され以後は変更されない。また
      \bxcaptionlanguage{spanish}
    のように直接に言語名を指定することもできる。

    日本語の場合はもっと特殊な事情がある。日本語のレイアウトは欧米の言語
    のものとは大きく異なるので、日本語の文書を作成する場合には日本語用の
    文書クラスが用いられるのが普通であり、そこでは当然キャプションは既に
    日本語になっている。このような場合は
      \bxcaptionlanguage{default}
    を実行すれば、キャプションは文書クラスで設定されたものに固定され、
    以後は変更されない。

■ 開発者向け機能

    \bxUHex{<コード値16進表記>}
      bxutf8 が構成する内部表現。用いる機能は \Ux と同じ。
    \bxUInt{<整数>}
      bxutf8x が構成する内部表現。用いる機能は \Ux と同じ。

    \bxInputDefFIle{<ファイルベース名>}
      拡張子 .def のファイルを \usepackage と同じ方式で読み込む。
    \bxCheckCPart{<ファイルベース名>}
      別のファイル(.sty/.def)との版の比較。
    \bxNullify\CS
      マクロ \CS を無効にする。
    \bxDebug{<テキスト>}
      デバッグメッセージの表示。
    \bxCheckMA<テキスト>\bxEndCheckMA
      \edef 中ではこの部分がエラーを出す命令に展開される。
    \bxIfPrimitive\CS{<yes>}{<no>}
      現在の \CS の定義が(同名の)プリミティブかの判定。
    \bxEngineTypeX  [整数定数]
      1=pTeX拡張; 2=XeTeX拡張; 3=Omega拡張; 0=以上に該当せず
    \bxEngineTypeY  [整数定数]
      1=eTeX拡張; 3=pdfTeX拡張; 0=以上に該当せず
    (upTeX か否かの判定は ifuptex パッケージを用いる)

    \bxTrivLangDef{<言語名>}
      中身が空の Babel 言語オプションを生成する。

    \bxToHexTwo{<整数>}      [%02X 形式; 0x00〜FF]
    \bxToHexThree{<整数>}    [%03X 形式; 0x000〜FFF]
    \bxToHexFour{<整数>}     [%04X 形式; 0x0000〜FFFF]
    \bxToHexFive{<整数>}     [%05X 形式; 0x00000〜FFFFF]
    \bxToHexFiveX{<整数>}    [%05X 形式; 0x00000〜FFFFF ※1]
    \bxToHexEight{<整数>}    [%08X 形式; 0x00000000〜7FFFFFFF]
    \bxToHexTiny{<整数>}     [%X 形式; 0x0〜FF]
    \bxToHexSmall{<整数>}    [%X 形式; 0x0〜7FFF]
    \bxToHexUC{<整数>}       [%04X 形式; 0x0000〜10FFFF ※2]
      16 進表記を \bxHex に返す。UC は 4〜6 桁での表記。
      ※1 0xFFFFF を超える場合は "FFFFF" になる
      ※2 XeTeX/LuaTeX/upTeX の場合、\char が可能な範囲。

    \bxCodeValueSeq\CS{<文字列>}    [16進]
    \bxCodeValueSeqD\CS{<文字列>}   [10進]
      \Ux, \UI が使っている、コード値の列を解釈するルーチン。

    \bxAssign<代入文>\relax
      代入文が完全(ゴミがない)かの判定しスイッチ \ifbxOk に返す。

    \bxToLower{<文字列>}
    \bxToUpper{<文字列>}
      小文字/大文字に変換したものを \bxRes に返す。

    \bxDocumentSpecial{<テキスト>}
      \AtBeginDvi を普通に用いて DVI の先頭部に special を出力する。
    \bxDocumentSpecialUrgent{<テキスト>}
      DVI のなるべく先頭(他の special より前)の位置に special を出力。

    \bxEnableSafeCaret
      safe caret 機能を使用可能にしておく。すなわち、プレアンブルでこの
      命令が呼ばれなかった場合、safe caret は使用不可になる。実際にある
      状況で safe caret を有効にするには、\bx@acr@normcaret を「その状況
      での本来の〈^〉の動作」に定義した上で〈^〉をアクティブにする必要が
      ある。
      ※ ユーザ命令の \safecaret はこの命令を実行するとともに、verbatim
      と babel での適切な safe caret 処理を有効化している。

    \bxUseShadowMap\CS{<TFM名>}
      命令語 \CS を指定の TFM から生成される shadow map として定義する。
    \bxMap\CS
      整数レジスタ \bxUcv の現在の値に shadow map を適用し、その結果を
      \bxUcv に代入する。
      ※ shadow map とは「16 bit 整数 → 整数」の写像を TFM として表現
      したもの。

---------------------------------------------------
  bxucs パッケージ (v0.2) -- 欧文 Unicode 文字出力 
---------------------------------------------------

Unicode subfont を利用して、(欧文の) Unicode 処理能力をネイティブには
もたない LaTeX 処理系で Unicode フォントを最大限活用する為のパッケージ
である。upLaTeX は和文に関するネイティブな Unicode 処理を行うが、欧文
として Unicode 文字を扱う場合にはこのパッケージが有効であろう。

■ 対応環境

    欧文 LaTeX2e / pLaTeX2e / upLaTeX2e

■ 読込

    \usepackage で読み込む。オプションはない。
      \usepackage{bxucs}

■ フォントの準備

    欧文フォントファミリに対してこのパッケージによる Unicode 出力を可能
    にする為には、次の 2 種類のエンコーディングに対するファミリの NFSS
    に基づくフォント定義が必要である。
      - LaTeX の通常のエンコーディング、最低でも OT1 と T1
      - Unicode subfont エンコーディング(ここでは USF と呼ぶ)

    例えば、次の 2 シェープからなるフォントファミリがあるとする。
      - FOO_R.ttf : regular weight
      - FOO_B.ttf ; bold weight
    これを LaTeX ファミリ名 "foo" で定義することを考える。

    最初に OT1 に関する定義をする。その為には、各シェープに対する TFM の
    名前を決める必要がある。regular を foo-r-ot1、bold を foo-b-ot1 と
    する(勿論 Berry 命名法に従っても良い)と、OT1 に対するフォント定義
    ファイル ot1foo.fd の内容は次のようになる。

      \DeclareFontFamily{T1}{foo}{}
      \DeclareFontShape{T1}{foo}{m}{n}{<->foo-r-ot1}{}
      \DeclareFontShape{T1}{foo}{bx}{n}{<->foo-b-ot1}{}

    T1 エンコーディングに対する設定も同様である。

    次に Unicode subfont (USF) に対する定義をする。Unicode subfont とは
    Unicode の BMP 領域を 256 文字毎に分割して複数の TFM に収めたもので
    ある。従って、1 つのシェープに対して TFM は(最大で) 256 個あること
    になり、名前の一部に番号(小文字 16 進表記)を含めて表す。今の場合で
    は例えば Regular のシェープに対する TFM 名は
      foo-r-u??   (?? は 00, 01, …, fe, ff)
    とすることができる。同様に Bold を foo-b-u?? とする。Unicode subfont
    に対するフォント定義ファイルは次の形式で記述される。

      \USFDeclareFontShape{<ファミリ>}{<番号列>}{
        \USFShape{<シリーズ>}{<シェープ>}{<TFM定義>}{<初期化>}
        (必要なだけ \USFShape を繰り返す)
      }

    Unicode subfont は 256 個全てが揃っているとは限らない。例えば 60 番
    (U+6000〜60FF) は漢字のみを含むので、元のフォントファイルが CJK 対応
    のものでない限り、60 番の subfont は存在しないことになる。<番号列>
    には、存在する番号の範囲の列を記す。ここでは 00, 01, 02, 03, ff が
    存在するとする。今の例でのフォント定義ファイル usffoo.fd の内容は次
    のようになる。

      \USFDeclareFontShape{foo}{00-03,FF}{
        \USFShape{m}{n}{<->foo-r-u#1}{}
        \USFShape{bx}{n}{<->foo-b-u#1}{}
      }

    あとは、今の過程で決めた事項に従って、実際に TFM ファイルを生成し
    (TrueType フォントの場合は ttf2tfm を使う)、さらに TFM と実物の
    フォントファイルを関連付けるように DVI ウェアを設定する必要もある。

■ 機能

    このパッケージは bxbase の \Ux のインタフェースを利用する。従って、
      \Ux{0425,043E,0440,043E,0448,043E}
    のように \Ux の引数にコード値の 16 進表記の列を書けばよい。ただし
    この時に、現在のフォントファミリは前述の説明で用意した Unicode
    subfont が定義されたものでなければならない。(なお、このパッケージは
    内部で bxbase を読み込むので別に読み込む必要はない。)

    使用中のフォントに指定されたコードの文字がない場合は、和文用の \UI
    の方に処理を渡す。ただしここで e-TeX 拡張が使えない場合、存在する
    文字と同じ subfont に属する文字は全て存在すると判断されてしまうと
    いう制限があり、結果として和文フォントには文字があるのに使えない
    という現象が起こりうる。


-------------------------------------------------------
  zxbase パッケージ (v0.4a) -- XeLaTeX 基礎ライブラリ
------------------------------------------------------

拙作の XeLaTeX 用パッケージ(ZX シリーズ)で使われる部品的機能を収めた
パッケージである。今のところ、このパッケージにはユーザ命令は定義されて
いないので、文書作成者が \usepackage で直接これを読み込むことはない。
(現在、zxotf がこのパッケージを内部で読み込む。)

----------------------------------------

■ 更新履歴

    version 0.5 <2010/06/15>
      - bxbase: \JI/\KI を追加。
      - bxbase: \dvipdfmxmapline/\dvipdfmxmapfont を追加。
      - bxutf8: BMP 外の符号値への対応。

    version 0.4a <2009/11/16>
      - bxbase で \UI/\Ux を zxjatype と、\AJ を zxotf と連携させた。
      - zxbase パッケージを追加。

    version 0.4 <2009/07/05>
      - PXbase の v0.4 に合わせた改訂。

    version 0.3 <2008/04/06>
      - bxutf8x を追加。
      - bxutf8 のバグを修正。
      - bxbase でも pxbase の命令 \recordpapersize を使用可能にした。

    version 0.2 <2008/03/28>
      - 最初の公開版。

# EOF