unicode_ids拡張(日本語版説明書)¶

Note

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

はじめに¶

2015年6月4日現在、Sphinx 1.3.1のHTML出力は、id属性に対してASCII限定の文字だけを使うように動作します。これはHTML4.01の仕様書に厳密に従おうとするためですが、今日ではUnicodeで定義された文字を使えます。

同様に、ASCII外の文字を名前に持つファイルはSphinx独自の変換を行ってしまいます。このため生成するHTMLファイル名は非常にわかりにくいものになります。

この拡張は、実行のたびにSphinxとその基盤であるdocutilsへパッチをあてる形で、指定通りの文字を使わせるようにするものです。

利用条件¶

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ではその標準符号化法かファイルシステムの符号化法に利用できる文字が限定されます。

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

設置方法¶

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

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

マイクロソフトウィンドウズではpythonを設置したフォルダ\Scripts\pip.exe install unicode_idsを実行してください。
あるいはunicode_ids-2.0.5(.zip)(2.0.5はバージョン番号)というファイルを入手し、このファイルがあるフォルダへ移動した後pip install unicode_ids-2.0.5.zipを実行してください。

同様にウィンドウズでは代わりにpythonを設置したフォルダ\Scripts\pip.exe install unicode_ids-2.0.5.zipを実行してください。
最後の別の方法として、これはSphinx特有の方法ですが、単にzipファイルを任意のフォルダに展開して使うという手段があります。Sphinxで使うconf.pyを適切に編集することで利用可能です。

使い方¶

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

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

# 次の3行を追加してください
import distutils.sysconfig
site_package_path = distutils.sysconfig.get_python_lib()
sys.path.insert(0, os.path.join(site_package_path, 'sphinxcontrib/unicode_ids'))

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

# 上記のimportやsite_package_pathの二行は使わないのでなくても構いません
sys.path.insert(0, '<unicode_ids.pyがあるフォルダへのパス>')

次に当拡張をextensionに追加してください:

extension = ['unicode_ids', ] # 他の拡張も無論同時に利用できます

HTMLなどでUnicodeを使って良いと考える根拠¶

本節は2015年6月4日(日本時間)にかかれています。

本書末に参考文献としてリンクを示しているほか、CSSについてはmomdo/もんどさんのCSS3の日本語訳集が便利です。

HTMLにおけるURI一般¶

HTML4.01 [HTML401J]ではURLに使える文字をA-Za-z0-9_:.および -に限定しています。

しかし同時に本文中でそれ以外の文字が来たら同処理すべきかについての指標も示されており、B.2.1 Non-ASCII characters in URI attribute values節に詳細があります(B.2.1 URI属性値の非ASCII文字)。この処理を介してURIをASCIIの7bit文字のみに修正して利用できるという仕組みです。

HTML4.01においてはこの処理、つまり百分率記号を使った符号化は常にUTF-8で行うこととする一方、古い文書では他の符号化法によることを期待している可能性にも触れています。

HTML5 [HTML5J] [HTML51J]においてはもう少しややこしい方法が定義されており、2.5 URLs節に詳細があります(2.5 URL(邦訳))。もしURLを解析する段階で符号化法が定められていたり、もともとのHTML文書がUTF-8以外で符号化されていた場合はそちらのもとにURLを再構成することとされています。

両方の仕様を考慮すると、HTMLファイルは常にUTF-8で符号化するのが安全と思われます。百分率記号による符号化がいずれにせよUTF-8を前提とできるからです。

このほか、W3C URL [W3CURLJ]およびWHATWG URL Living Standard [WHATWGURLJ]という仕様もあり、こちらでも常にUTF-8を使うことを期待する文面があります。

HTMLにおける識別子(アンカー)¶

HTML5ではid attributeをunique identifier(‘一意識別子’)と定義しています(3.2.5.1 id属性)。

この語は同書の2.2.2 Dependencies(‘依存先’)節にて、用語DOMの説明文中でDOM仕様の定義をそのまま運用することとされています。

DOM4 [DOM4J]の5.8 Interface Element(4.8 インターフェイス Element)において、各要素のid属性はDOMString型であり、これによって要素のunique identifier(ID)(一意的な識別子)を持つことができると記されています。

DOMStringはWebIDL [WebIDLJ]の定義によることが9 Historical/9.2 DOM Core節で示されています(8 歴史(変更点)/8.2 DOM Core)。

3.10.15 DOMString 節でDOMStringは符号単位(code unit)の直列であることが示されています(3.10.15. DOMString(邦訳))。

code unitも同書で定義され、 16ビット符号なし整数であり、またUTF-16符号化法と対応付けるとされています(符号単位)。

以上のことから、HTMLにおける要素の識別子にUnicodeの文字を使うことができ、内部ではUTF-16の扱いになることがわかります。ただしCSS3では数字・ハイフン二つ・ハイフンと数字のいずれかを先頭にはできません。次の節をごらんください。

DOM3においてはDOMStringがDOM3CORE [DOM3COREJ]で定義されています。1.2.1 The DOMString Type節を参照ください。

CSSにおける識別子¶

CSSは現在level 3が議論されています。その安定性はCSS2.1の区分によりモジュール単位で異なるものになっています。この件についてはCSS Snapshot 2010 [CSSSnapshotJ]の1.1 Introduction節をお読みください(1.1 はじめに)。

CSS2.1 [CSS21J] [CSS22J] においては4.1.3 Characters and case 節で識別子にどの文字が使えるかを説明しています。第二段落に次の記述があります(4.1.3 文字と活字ケース):

CSSでは、（要素名、クラス、およびセレクタ内のIDを含む）識別子は、文字[a-zA-Z0-9]およびISO 10646でU+00A0以上の文字、またハイフン（-）およびアンダースコア（_）のみを含むことができる。識別子は、数字、2つのハイフン、ハイフンの直後の数字で開始できない。また、識別子は、エスケープされた文字および数字コードとして任意のISO 10646文字を含めることができる…(後略)

従って、識別子に非ASCII文字を使えます。そのすぐ下にISO 10646はUnicodeと文字符号が一対一で対応する旨も記されています。CSS3でもこれを覆す記述は見当たらず、CSS2.1の定義を踏襲していると思われます。

JavaScript/ECMAScriptにおける識別子¶

ECMAScript [ECMAScriptJ]は大雑把にいうとJavaScriptの標準仕様です。

ECMAScriptの仕様では、7.6 Identifier Names and Identifiers 節が識別子に使える文字を定義しています( 7.6 識別子名と識別子)。そこでは明瞭にUnicodeの文字が利用可能とされています。一見いくつかの文字種は使えないように思えますが、 Unicode escape sequenceによって最終的にすべての文字が使えるという定義のようです。