toc.xbl : 目次の自動生成

概要

toc.xblHTML 文書の目次を自動的に生成します。 XBL に対応した Web ブラウザで CSS に記述を加えるだけで HTML 文書に目次を付け加えることができます。この文書では toc.xbl の使い方を説明します。

はじめに

HTML では見出しを表す hn 要素型が6種類用意されており、文章の構成を記述することができます。 この見出し情報を利用して文書の輪郭を利用者に提示して閲覧の便を図っている利用者エージェントもありますが、 残念ながらそれほど一般的ではありません。

toc.xbl は、 HTML 文書から目次を動的に生成します。 XBL 1.0 によって一つのパッケージにまとめられているので、 著者はスタイル・シートに記述を足すだけで目次を文書に加えることができます。

使い方

簡単な使い方

CSS スタイル・シートの先頭 (@charset 規則を使用している場合はその後) に、次の例のような記述を加えて下さい。

@import 'https://suika.suikawiki.org/www/style/ui/toc-after-h1.css';
@import 'https://suika.suikawiki.org/www/style/ui/toc-style-float-compact.css';
目次を付けるための CSS の指定

なお、このスタイル・シートを適用する文書で h1 要素が使われていることを確認して下さい。

CSS の規定により、 @import 規則の指定は他の規則よりも前になければなりません。

より高度な使い方

目次を有効にするために必要な CSS スタイル・シートの記述は、
  • 目次を生成する toc.xbl の指定
  • 生成された目次の見た目を整えるための指定
の2種類に分けることができます。

toc.xbl の束縛

目次を生成するための toc.xbl を文書に束縛するためには、 -moz-binding 特性を使用します。この特性の値は束縛する XBL の文書と、その中に含まれる束縛 (binding) 要素を識別する URI 参照です。

h1 {
  -moz-binding: url(https://suika.suikawiki.org/www/style/ui/toc#after);
}
h1 要素の後に目次を挿入する指定

この例では、 XBL 文書として <https://suika.suikawiki.org/www/style/ui/toc> を、その中の束縛として after を指定しています。 前者は XBL 文書を別の場所に保存する場合は適当に書き換えて下さい。 後者は現時点では after 以外指定できません。

-moz-binding 特性は Gecko の拡張です。しかし、 Gecko 以外の利用者エージェントにはほぼ無害と考えられます。

-moz-binding 特性を使用したスタイル・シートの例を2種類用意しました。 是非お使い下さい。

もちろん、これらを使わずに先の例のような特性の指定を直接お使いのスタイル・シートに追加していただいても構いません。

生成した目次へのスタイル指定

目次は、次の図のような構造で生成されます。

  1. xhtml1:div[@toc:toc]
    1. xhtml2:nl
      1. xhtml2:label
      2. xhtml2:li
        1. xhtml2:nl
          1. xhtml2:label
          2. xhtml2:li
          3. ...
      3. xhtml2:li
      4. ...
目次の要素構造

色々な本質的ではない理由により、最上位の要素は xhtml1:div にしています。ただし、元々文書に存在していた xhtml1:div 要素と区別できるように、 toc:toc 属性を加えています。この要素は束縛した要素の弟として追加されます。

最初の要素である xhtml2:h は目次部分の見出しで、目次という文字列が含まれます。 その弟として xhtml2:nl 要素を使って文章中の見出しに対応するリストが作られています。 このリストは文章中の見出しの深さに対応しています。 ただし、文章中に章節に対応する要素があるかどうかで構造がやや異なります。

章節に対応する要素がある場合
章節構造にあわせて入れ子になったリストが作られます。 リストの深さが章節の深さです。
章節に対応する要素がない場合
要素型名の数字に関わらず、同じ深さの平らなリストが作られます。 リストの深さと章節の深さが一致しません。ただし、 リスト項目 (xhtml2:li 要素) の属性 toc:element-type に要素型の局所名 (XHTML でない HTML の場合、小文字化済み) を、属性 toc:element-type-ns-uri に要素型の名前空間 URI を与えています。これを使ってスタイル・シートの側で見かけの深さを変えることができます。

先の図よりもう少し厳密に、 DTD 風に構造を記述すると次の図のようになります。

<!-- 目次 -->
<!ELEMENT xhtml1:div (xhtml2:h, xhtml2:nl)>
<!ATTLIST xhtml1:div
  toc:toc  CDATA  #REQUIRED>

<!-- 目次の見出し -->
<!ELEMENT xhtml2:h ANY>

<!-- 章名リスト -->
<!ELEMENT xhtml2:nl (xhtml2:label, xhtml2:li+)>

<!-- 章名 (節あり) -->
<!ELEMENT xhtml2:label ANY>

<!ATTLIST xhtml2:li
  href  CDATA  #REQUIRED>

<!-- 章名 (節なし) -->
<!ELEMENT xhtml2:li ANY>

<!ATTLIST xhtml2:li
  href  CDATA  #REQUIRED
  toc:element-type  NMTOKEN  #IMPLIED
  toc:element-type-uri  CDATA  #IMPLIED>
目次の要素構造 (DTD)

XHTML 2 に対応した利用者エージェントやスタイル・シートを使っていれば、 何もしなくてもこの構造を適切にレンダリングできるはずです。 そうでない場合や、対応していても目次の部分だけ違ったレンダリングをさせたい場合には、 著者が適当なスタイル・シートで指定する必要があります。

スタイル・シートの例として、この文書でも使用している、 閲覧領域の右上に移動可能な箱として表示するためのスタイル指定を紹介します。

URI
<https://suika.suikawiki.org/www/style/ui/toc-style-float-compact>

このスタイル・シートは、 要素に対応する箱を移動可能にするための XBL 部品を利用しています。目次の位置を閲覧領域の右上に固定し、 邪魔にならないように読者が自由に移動可能にしています。 更に、普段は半透明で裏の文章が透けて見えるようにしています。

このスタイル・シートを使うためには、お使いの CSS スタイル・シートの先頭 (@charset 規則を使用している場合はその後)
@import 'https://suika.suikawiki.org/www/style/ui/toc-style-float-compact.css';
と指定してください。あるいは、 このスタイル・シートを参考に適当な記述を加えて下さい。

この節で使用した修飾名の名前空間接頭辞は、 次の名前空間名を表します。

xhtml1
<http://www.w3.org/1999/xhtml>
xhtml2
<http://www.w3.org/2002/06/xhtml2/>
toc
<http://suika.fam.cx/~wakaba/archive/2005/3/toc#>

なお、古い版 (1.2 まで) では XHTML 2 の名前空間名として <http://www.w3.org/2002/06/xhtml2> を使っていました。

対応している要素型

次の要素型は、見出しを表す要素型として扱います。

  • xhtml1:h1
  • xhtml1:h2
  • xhtml1:h3
  • xhtml1:h4
  • xhtml1:h5
  • xhtml1:h6
  • xhtml2-2002:h
  • xhtml2-2005:h

次の要素型は、頭を表す要素型とみなします。

  • html5:header
  • xhtml1:div (ただし、 classheader が含まれている要素に限ります。)

次の要素型は、章節を表す要素型とみなします。

  • xhtml1:body
  • xhtml1:div (ただし、 classsection, article, wiki-section のいずれかが含まれている要素に限ります。)
  • xhtml2-2002:body
  • xhtml2-2002:section
  • xhtml2-2005:body
  • xhtml2-2005:section
  • html5:section

この節で使用した修飾名の名前空間接頭辞は、 次の名前空間名を表します。

html5
<http://www.w3.org/1999/xhtml>
xhtml1
<http://www.w3.org/1999/xhtml>
xhtml2-2002
<http://www.w3.org/2002/06/xhtml2>
xhtml2-2005
<http://www.w3.org/2002/06/xhtml2/>
toc
<http://suika.fam.cx/~wakaba/archive/2005/3/toc#>

ただし、 XHTML でない HTMLXHTML 1 と同じとみなします。

Bookmarklet として使う

Bookmarklet として、 読者が任意の HTML 文書に目次を付けることができます。

実際の使用例

次のサイトで実際に使用しています (順不同)。

制限事項

将来の予定:

関連ファイル

この階層toc から始まる名前のファイルが関連する実装やスタイル・シートの例です。

各ファイルは Git で版管理しています。

License

関連するファイルMPL 1.1/GPL 2.0/LGPL 2.1 で配布しています。詳しくは各ファイルの注釈をご覧下さい。