includexの活用 Edit Edit



includex とは Edit Edit

includex は、指定したページのテキストを grep でパイプして表示するような PukiWikiプラグインである。適切に利用することで、再利用性の高いページ、編集コストの少ないページ、閲覧者にとって読み取りやすいページを構築することができる。オプションが比較的複雑であり、またプラグイン製作者のマニュアルサイトがダウンしているため、補足事項を説明するページを作成した。

背景情報 Edit Edit

  • sonots
    コミッターsonots により、2006年ごろ includex をはじめとする高機能なプラグイン群が作成された。
    2022年の秋頃からsonotsの個人サイトが閲覧できなくなっている。whoisを見る限り、2027年まではドメイン名自体が別のページに飛ぶことはない。
    ライセンスは概ねGLP2.0で配布されている。(個別のライセンスを確認すること)
  • wikiru.jp
    wikiru.jpには2022年の秋ごろに導入された。
    他に[wikiru, wikcurio, wikiwiki]で導入されている。[@wiki, seesa wiki, fc2 wiki, swiki]では2022年10月時点で利用不可。

拡張の系譜 Edit Edit

  • include
    初めに作られたプラグイン。マニュアルによれば、記述した位置に指定したページを挿入して、複数のページをあたかも1つのページであるかのように表示するもの。ページ名の指定ができ、ページTITLE をオプションで非表示にできる。
  • include2
    include の挙動を参考にフルスクラッチで作成された。include の他ページの表示機能に加えて、行数オプションで表示範囲を限定することができる。
  • includex
    ページを取り込むプラグイン include の拡張とされ、次に示す比較的高度な抽出機能が追加された。簡易な DOM的な挙動、見出し行と本文行それぞれに対する egrep での抽出、表示範囲の行数での指定、TITLE の表示制御など。

includex のマニュアル Edit Edit

Semantic MediaWiki や Google Spreadsheet Edit Edit

  • Semantic MediaWiki
    MediaWiki:wp において RDF のようなセマンティックな形式のデータを扱えるようにするプラグイン。例えばこのページでは、Key-Valueの型 でいくつかのページにまたがって記述された人口と面積が、#ask 関数によりテーブルの形でとりまとめて表示されている。とはいえ PukiWiki と MediaWiki は互換性がほぼないため隣の芝生になってしまう。もしもまだ wiki を立ち上げていないならば採用の検討に値するだろう。
    またPukiwikiベースのwiki3にはWikiDBという似たような実装がある。
  • Google Spreadsheet
    みんなで編集できるエクセルライクな webサービスの定番。似たようなサービスにprts.wikiでも使われている中国語向けの 石墨文档/Shimo がある。PukiWiki系wikiに Google Spreadsheet を埋め込み表示するプラグインもあるものの、いまいち体験が洗練されていない。アカウントに関して、おおよそ管理者は wiki 専用のメールアドレスを gmailアドレスで新規に作成しているだろうから (@2023) 問題にはならないはず。ドメインの外部にデータが置かれることになるため釈然としないが、活用できる場面もあるかもしれない。

includex の基本的な利用 Edit Edit

オプションの説明 Edit Edit

わかりやすい利用例 Edit Edit

```source
?食品 (ページタイトル)
* FRUIT
くだもの
** APPLE
りんご
** BANANA
ばなな
*** Cavendish
きゃべんでぃっしゅ
*** Gros Michel
ぐろすみっちぇる
** CHERRY
さくらんぼ
```code
#includex( 食品, section=(filter=Cavendish), except=^\*, titlestr=off)

食品ページを指定し、見出しの「Cavendish」と直下の本文を抽出し、見出し行を except で排除して、ページタイトルを非表示にしている。

```result
きゃべんでぃっしゅ

filter / except の対象 Edit Edit

━┳ ページ (http://pukiwiki.osdn.jp/?{PAGE_NAME})
 ┗┳ 見出し行 (*,**,***)
  ┗━ 本文行

「見出し行」と「本文行」それぞれに「grep -E (-v)」のような filter (except) オプション(実際にはphpのpreg_match)を実行することができる。

DOMライクな挙動 Edit Edit

━┳ ページ
 ┣┷┳ * FRUIT
 ┃ ┗━ くだもの
 ┣┷┷┳ ** APPLE
 ┃  ┗━  りんご
 ┣┷┷┳ ** BANANA
 ┃  ┗━  ばなな
 ┣┷┷┷┳ *** Cavendish
 ┃   ┗━  きゃべんでぃっしゅ
 ┣┷┷┷┳ *** Gros Michel
 ┃   ┗━  ぐろすみっちぇる
 ┣┷┷┳ ** CHERRY
 ┇  ┗━  さくらんぼ

見出しには深さがある。具体的には「depth」オプションで参照できる。だだし1つの見出しから次の見出し直前までが一塊と判断され、見出しの階層構造は本文の階層構造に適用されない。つまり例えば「**BANANA」を選択したとき、「ばなな」は表示されるが、「きゃべんでぃっしゅ」や「ぐろすみっちぇる」を下位の要素としてアクセスすることはできない。
また「depth=2」とすると以下のテキストになる。

```result
** APPLE
りんご
** BANANA
ばなな
** CHERRY
さくらんぼ

includex の応用 Edit Edit

aname と組み合わせる Edit Edit

anameプラグインは、指定した位置にアンカー(リンクの飛び先)を設定するプラグイン。アンカー名はHTMLで表示されないが、filterの評価対象にはなる。

```source
ジョナゴールド   &aname(apple);
キャベンディッシュ &aname(banana);
グロスミッチェル  &aname(banana);
```code
#includex(source_page_name,filter=banana,titlestr=off)
```result (見かけ)
キャベンディッシュ
グロスミッチェル

表を扱う Edit Edit

PukiWikiの表は先頭が「|」で始まるため「filter=^\|」とマッチさせる。

```code
#includex(source_page_name,filter=^[|],titlestr=off)

これにanameを組み合わせることで、以下のように2つに分かれた表を、一つのテーブルにまとめることができる。

```source
|品種名    |分類 |産地 &aname(tag);|h
|ジョナゴールド|りんご|アメリカ|

|品種名      |分類 |産地    |h
|キャベンディッシュ|ばなな|フィリピン |
|グロスミッチェル |ばなな|中央アメリカ|
品種名分類産地
ジョナゴールドりんごアメリカ
 
品種名分類産地
キャベンディッシュばななフィリピン
グロスミッチェルばなな中央アメリカ
```code
#includex(source_page_name,filter=(^[|].*[|]$)|(^[|].*tag.+h$),titlestr=off)

```result

品種名分類産地
ジョナゴールドりんごアメリカ
キャベンディッシュばななフィリピン
グロスミッチェルばなな中央アメリカ

細かな技法 Edit Edit

  • プラグインのうち、先頭が記号で始まる文法であれば、概ね抽出することができる。
    • 引用であれば「^>」
    • regionであれば「^#.*region」
    • 閉じタグ「}}」を狙って抽出するのは難しい。
  • filter で表示要素を抽出するのではなく、exceptオプション(grep -v)を用いて表示しない要素を指定するアプローチの方が、記述がすっきりする場合もある。もちろん両者を組み合わせることも有効。
  • nullプラグインは、表示されないが評価されるテキストとして活用できるかもしれない。
  • 具体的な利用例は「includex」と調べることで見つけることができる。
  • 他のwikiでの利用例として、ソレナリの冒険録Wiki 2nd*アリスギア - アリス・ギア・アイギス 攻略 Wiki*など。

バッドパターン Edit Edit

num オプションはできるだけ使用しない Edit Edit

以下のようなソースからバナナのみを抽出するケースを考えてみる。

```source_1
[0] ジョナゴールド   &aname(apple);
[1] キャベンディッシュ &aname(banana);
[2] グロスミッチェル  &aname(banana);
```code_A
#includex(source_page_name,num=1:2,titlestr=off)
```result_1A (見かけ)
キャベンディッシュ
グロスミッチェル

バナナだけを抽出できている。さてここに 紅の夢(リンゴ) を追加してみよう。

```source_2
[0] ジョナゴールド   &aname(apple);
[1] 紅の夢       &aname(apple);
[2] キャベンディッシュ &aname(banana);
[3] グロスミッチェル  &aname(banana);
```result_2A (見かけ)
紅の夢
キャベンディッシュ

バナナとリンゴが混ざってしまった。なぜなら単に行数を示す「num」と抽出したいカテゴリ「ばなな」との間には意味のある関係性がないからだ。
ここで source と code は別々のページに記述されていることを思い出してほしい。1つのレコードを追加した際に2つのページを編集しなければいけないのだ。レコードを追加したときに、もし引用先のページが存在することを忘れていたり、そもそも引用先のページを知らなかったりしたら、崩れた表示が放置されてしまう。
したがって以下のcode_Bのように意味のつながりがある書き方をすることで、1つのページに単純にレコードを追加するだけで作業が終わる。表示が不用意に崩れることはなく、いわば再利用性が高くなるわけだ。

```code_B
#includex(source_page_name,filter=banana,titlestr=off)
```result_2B (見かけ)
キャベンディッシュ
グロスミッチェル

平文を捌くときなど num を使わざるを得ない場面があるかもしれない。ただ基本的には、「*(見出し)」を section/filter で選択する、プラグインの「#」や「>」を filter で選択する、共通して出てくる単語を filter する、などの方法を取るのが良い。

既知のバグ Edit Edit

  • php5.3で inecludex を導入すると「\」がいずれの箇所でも利用できない。「[$]」角カッコをエスケープとして利用する方法、「[:alpha:]」のようなPOSIX文字クラスを利用する方法が回避策となる。
  • php7以降であれば「\」は普通にエスケープとして利用できる。
  • 正規表現の方言は PCRE であり、詳しい挙動は preg_match - php を参照のこと。

その他 Edit Edit

contentsx の応用 Edit Edit

  • contentsx では includex と同じようなオプションが利用可能。numオプションで見出しを抽出する方法、anameを仕込むことで制御する方法などが使える。

lsx について Edit Edit

  • includex では1つのページしか指定できなかったところ、すべてのページを対象にしてページ名を egrep して集められるようになったもの。ページ名をあらかじめ規則的に命名していないと、満足する結果を得にくい。また表示行数を増やしすぎると処理が重くなりがち。

ecacheの活用 Edit Edit

  • ecathe は Wiki文法の 出力HTML をキャッシュし、負荷軽減を試みるもの。毎回 preg_match が走るのは、リソース消費の面からも、表示速度の面からもあまり望ましくないため、対策として有効なプラグインといえる。


トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2023-04-26 (水) 00:31:59