yogosyu拡張(日本語版説明書)

Note

日本語版(本頁)は公式サイトとこのパッケージのdocフォルダでご覧になれます。

はじめに

2015年6月7日現在、Sphinx 1.3.1は ‘正規化形式D’(Normalization Form Canonical Decomposition, NFD) に基づく並べ替えしか行いません。さらにまずいことに、索引の見出しは英字に対してしか行われません。

英語に似た言語では、NFDの効果もあって問題が少ないか全くないことが多いのですが、英字を共有しない言語では悲惨なことになります。ほとんど全部の文字が記号扱いとなり、索引の見出しが機能しないからです。

日本語においてはさらにまずいことになります。漢字を使った用語に対する読み方を提供できないため、並べ替えの結果はUnicodeの漢字並び順という全く役に立たない結果をもたらします。

この拡張機能では、これらの解決を試みています。並び順は別途配布している sortorder moduleを使います。日本語などには事前に並べ方が定義されているほか、任意の言語に対し自前の並べ方を定義することもできます。

残念ながら現在は .. glossary:: directive を置き換える .. yogosyu:: 以外は未解決です。index などを含むの他のものは将来の版で解決する…かもしれません。

利用条件

Sphinxと同じく二項BSDです。

設置について

他のPythonパッケージと同様に設置・撤去できます。また他のSphinx拡張と同様に必要なファイルだけ各自の管理下に複製し、そのフォルダをconf.pyで指定することでも利用いただけます。

動作条件

32ビット版のPython 2.7.10と64ビット版のPython 3.4.3をマイクロソフトウィンドウズ 8.1上で動かして挙動を確認しました。特段の依存性はないので、他のPython実装や他のOSでも動作すると思います。

Unicodeで定義された全文字への対応はPython 3が必須です。Python 2ではその標準符号化法かファイルシステムの符号化法に利用できる文字が限定されます。

Caution

また、この拡張はSphinx 1.3.1とdocutils 0.12の実装コード内容に依存しています。パッチ先の関数類に互換性のない変更があると動作しなくなります。

この点については、もう少し安定している別の拡張 gosyu があります。ただしこちらではgenindex.html ではなく std-gosyu.html が索引に用いられます。

設置方法

前述の通り、通常のPythonパッケージと同様の方法で設置できます。

  1. コンソールを開きpip install yogosyuを実行してください。

    マイクロソフトウィンドウズではpythonを設置したフォルダ\Scripts\pip.exe install yogosyuを実行してください。

  2. あるいはyogosyu-2.0.5(.zip)(2.0.5はバージョン番号)というファイルを入手し、このファイルがあるフォルダへ移動した後pip install yogosyu-2.0.5.zipを実行してください。

    同様にウィンドウズでは代わりにpythonを設置したフォルダ\Scripts\pip.exe install yogosyu-2.0.5.zipを実行してください。

  3. 最後の別の方法として、これはSphinx特有の方法ですが、単にzipファイルを任意のフォルダに展開して使うという手段があります。Sphinxで使うconf.pyを適切に編集することで利用可能です。

依存関係を解決しなかった場合は、別途 sortorder が必要となります。

使い方

1) パスの追加

他のSphinx拡張同様、conf.pyの編集によって使えるようになります。

まず、次のコードを追加してください:

# 次の4行を追加
import distutils.sysconfig
site_package_path = distutils.sysconfig.get_python_lib()
sys.path.insert(0, os.path.join(site_package_path, 'sortorder'))
sys.path.insert(0, os.path.join(site_package_path, 'sphinxcontrib/yogosyu'))

ただし、もしpipで設置していないのであれば代わりに次を追加してください:

# 代わりに次の2行を追加
sys.path.insert(0, '<sortorder.__init__.pyがあるフォルダへのパス>')
sys.path.insert(0, '<yogosyu.pyがあるフォルダへのパス>')

さらに独自の並び順を提供するPythonファイルがある場合は、それへのパスも追加してください:

# 上記のいずれかに加えて次の行を追加
sys.path.insert(0, '<用意した独自sort_order_xx.pyがあるフォルダへのパス>')

Note

sortorder には日本語を含めいくつかの言語用に予め用意された並び順提供module が含まれています。それらの使い方や独自の並び順を定義する方法については、 sortorder の説明書をご覧ください。

2) 使う拡張の宣言

次に当拡張を extension の中で宣言してください:

language = 'xx' # 自動読み込みを使う場合は言語指定を確認して下さい

#
# (中略)
#

extension = [
  'sort_order_xx', # 自動検出かsortorderで提供するものを使う場合は省きます
  'sortorder', # yogosyu拡張が自動的に読み込むので省略できます
  'yogosyu', # 総合索引を出力する場合は省略できます
  'user_ordered_index_patch', # 総合索引を出力しない場合は省略できます
] # もちろん他の拡張も任意で追加できます

3) ‘glossary’ を ‘yogosyu’ に置き換え

ここまでできましたら、.. glossary:: directiveを .. yogosyu:: に置き換えるだけです。:sorted: はそのままで使えます。

genindex.html では常に指定された並び順とグループ化が行われるようになります。

4) 読みがなを加える

日本語のような言語で使うために .. yogosyu:: directive は :yomimark: <区切り文字> という option も用意しています。:yomimark: で指定した文字の前が本来の用語、後ろが読みがなという形になります。

日本語での使用例を示します。conf.pyで次のように記述してください:

language = 'ja'

#
# (中略)
#

extension = [
  'user_ordered_index_patch',
]  # 省略された拡張は前述のとおりすべて自動的に読み込まれます

その上で次のように用語集を記述した場合を考えます:

.. yogosyu::
  :sorted:
  :yomimark: 、

  ひらがな

    比較的曲線が多い日本語の表音文字

  カタカナ

    比較的直線が多い日本語の表音文字

  漢字、かんじ

    日本語でも使われる表意文字

  英字、えいじ

    義務教育で教わるため、日本語でもよく使われる表音文字

  記号、きごう

    国内国外を問わず多種多様な記号が携帯電話などでも使えるようになってきた

ここでは区切り記号を読点 、 (U+3001) にしています。

単語は 英字→カタカナ→漢字→記号→ひらがな の順で並べられます。 sortorder.ja module が読みがなである えいじ, カタカナ, かんじ, きごう, ひらがな にもとに判断するからです。

また genindex.html においては カタカナ, 漢字, 記号 が単一の見出し か にまとめられます。やはり同じ module が指定された読みがなに基いて振り分けを行うからです。

関連配布物

  • unicode_ids
    • Sphinxが出力するHTMLファイルに非ASCII文字を含まれるように修正します
  • sortorder
    • この拡張の基盤moduleです
  • gosyu
    • 同じ目的の他の実装です。Sphinxの更新に対する安定性は増しますが、総合索引の代わりにドメイン索引に用語が入ります。

著者

Suzumizaki-Kimitaka(鈴見咲 君高), 2011-2015

履歴

2.0.5(2015-07-04):

2013-12-07:

Sphinx に合わせて Python 3 にも対応しました。

2013-12-06:

Sphinx 1.2 へパッチ対象を変更しました。

2011-05-24:

初回公開。sortorderとunicode_idsを含んでいました。