Wiki Navigation

trac-wiki.el -- Emacs で Trac の wiki ページを編集するモード

お知らせ

2008-06-07: Version 1.8 をリリースしました。エンドポイントURLの手動入力時のバグを解消しました。(changes)
また、Debian etch での emacs 22.1 および 23.0.6 での動作を確認しました。

2007-11-14: バージョン 1.7 をリリースしました。バージョン 1.6 で混入した、メモリ使用に関する重大なバグを解消しました。 (変更内容)

2007-11-14: バージョン 1.6 をリリースしました。基本的にバグフィックスのみの更新ですが、Emacs 21.4 および Emacs 22.1 での動作チェックを行い、おかしな挙動を極力解消しました。 (変更内容)

2007-03-24: 本家が xml-rpc.elに対する変更を取り込んでくれたので、そちらを使うようにして trac-wiki に同梱するのは止めました。

2006-12-22: バージョン 1.5 をリリースしました. このバージョンでは多くのバグフィックスとEmacs 21 のサポートを強化が行なわれました (xml-rpc.el の更新による)。またいくつかの新しい機能(C-c C-o)の追加もあります。バージョン1.5での変更点はこちらを参照して下さい。

概要

trac-wiki.el は TracのWikiページを編集するためのEmacsのLISPモジュールです。 XML-RPCを使用してTrac のページの内容を取得し、編集し、更新する事が出来ます。主な機能は以下の通りです:

Emacs 21.4 と 22.1 のサポート
複数のTrac プロジェクトへのアクセスが可能。
リモートのプロジェクトページの編集とハイライトによる色づけ。
更新時のバージョンチェック。
編集前の内容との差分表示機能や変更の破棄
編集中のページの最新版へのマージ(複数人での編集時に効果あり)
ページの修正履歴の表示
Emacs w3m を使用したEmacs バッファ内でのページプレビュー
外部ブラウザでのプレビュー
Trac サイト内の検索
編集中のバッファ内での Wiki ページ名やマクロ名の補完。

ただし以下のような制限があります:

添付ファイルは扱えません
エラーハンドリングに弱いかも知れません (認証エラーやSPAMフィルタによる拒否など)
ページの削除/バージョンの削除は行なえません。
チケットは扱えません。
TagsPluginが提供するタグの機能は扱えません。

ダウンロード

trac-wiki.el -- version 1.8, 2008-06-07

最新のコードはこちらから、あるいはリポジトリから入手可能です。ソースコードはMercurial を使用して管理されています。リポジトリは以下のようにして複製する事が出来ます:

hg clone http://www.meadowy.org/~gotoh/hg/trac-wiki/

必要なもの

Emacs 21.4, 22.1 およびそれ以降のバージョン。あるいは Meadow 3.00-dev
xml-rpc.el (rev. 1.7 以降) が必須です。
emacs-w3m (と w3m プログラム) は必須ではありませんが、 Emacs バッファ内でのプレビューするのに必要です。
https: のサイトにアクセスするには gnutls-cli または openssl が必要です。
Emacs 21 では日本語などのCJK文字を正しく扱うために mule-ucs が必要です。
Emacs 21 では, url ライブラリ(w3 プロジェクトの一部)が必要です。また https: アクセスを行なうには ssl.el も必要です。 (#2 も参照の事)
サーバ側では Trac 0.10.2 または以降のバージョンが必要です。そして XmlRpcPlugin (r1735 以降)が必要です。

設定

XmlRpcPluginを入手し、インストールし、有効化して Trac サイトで使用できるようにします。
あなたの ~/.emacs ファイルにてプロジェクト設定をします。
プロキシを使用するなら ~/.emacs にて url-proxy-services を設定します。

サーバ側の準備

XML-RPCプラグインを入手してプラグインをインストールし、これを有効にします。詳しくは install instruction を参照して下さい。

それからユーザにXML-RPC機能を使用する権限を与えます。例えばログインした(認証された)ユーザのみがXML-RPC機能を使えるようにするには、 XML_RPC アクション(action)を定義済みの仮想ユーザ authenticated に付与します。具体的には trac-admin コマンドを使って以下のようにします:

$ trac-admin your-env permission add authenticated XML_RPC

web-admin プラグインを使っていれば、同じことは Web 上で行なうことも出来ます。

その際、action として XML_RPC が選べない場合は xmlrpc プラグインが正しくインストールされていないか有効になっていないと思われますので、設定などをチェックしましょう。

クライアント側の準備

よく訪問するサイトがあるならば、あらかじめ登録しておくとよいでしょう。これにより略名を使った補完つき選択によりサイトへアクセスできるようになります。登録するには trac-wiki-define-project を次のように使用します:

(trac-wiki-define-project "trac-hacks"
                          "http://trac-hacks.org/" t)

最初の引数は略名で、trac-wikiコマンド実行時のサイト選択に使われる名前です。第2引数は実際のサイトのURLです。省略可能な第3引数は non-nilを与えるとログインが必要であることを指定できます。

同じサイトに複数のプロジェクトがあるならば、 trac-wiki-define-multiple-projectsでまとめて登録することもできます。

(trac-wiki-define-multiple-projects '("proj1" "proj2" "test")
                                    "http://www.foo.bar.org/" t)

上の例は次のような、3つの trac-wiki-define-project による登録と同等です。

(trac-wiki-define-project "proj1" "http://trac-hacks.org/proj1" t)
(trac-wiki-define-project "proj2" "http://trac-hacks.org/proj2" t)
(trac-wiki-define-project "test" "http://trac-hacks.org/test" t)

HTTPプロキシを使用する必要がある場合、trac-wiki.elが利用している url ライブラリパッケージに対する設定を行なう必要があります。

url パッケージの詳細な説明はinfo を参照して下さい。
... Emacs 上で (Info-goto-node "(url)Proxies")を評価する事で参照できます

最後に、trac-wiki プログラムをロードするための autoload を設定します。

(autoload 'trac-wiki "trac-wiki" "Trac wiki editing entry-point." t)

mod_auth_sspi を使用している場合の注意

(2006-11-03 以前のemacs 22.0.50/90 を使用している人向けの情報)

WEBサーバの認証方法が複数提供されている場合は注意が必要です。 WEBサーバの設定によってはアクセスしたいTrac ページの認証に複数の認証方法が許可される事があります。この場合、古い url ライブラリを使用していると認証に失敗する事があります。これはurl-http.elのバグで、症状としては認証のためのユーザ名/パスワードの入力を何度も求められてしまうというものです。このような状況は mod_auth_sspi を使用していてBASIC認証へのフォールバックが許される設定を行なっている場合に発生します。

この問題はこのパッチを url-http.elに当てるか、事前に手動で認証情報を(url-http-real-basic-auth-storage あるいは url-http-real-digest-auth-storage 変数に)設定しておく事で回避する事が出来ます。 BASIC認証を使ってる場合、*scratch*バッファに以下のコードを書いて(C-x C-eで) 評価してみてください：

(eval-after-load "url-auth"
  '(let ((auth (base64-encode-string (format "%s:%s" "yourname" "yourpassword"))))
     (set (symbol-value 'url-basic-auth-storage)
	  `(("www.some.org:80" ("realm string for the site" . ,auth))))))

これでうまくいくようならば、次回起動時のためにこれを.emacsに書いておくとよいでしょう。

このパッチは現在の版(2006-11-03以降)のurl-http.el では不要です

使い方

上で述べた設定が済んだら、Emacs にて M-x trac-wiki とすることで編集を始めます。編集作業の大まかな流れは以下のようになるでしょう:

M-x trac-wikiで起動
プロジェクト名の指定(補完あり)
編集するページ名の指定(補完あり)
ページの内容の編集
編集内容の確認 (C-c C-d)
プレビューにて確認 (C-c C-p または C-u C-c C-p).
更新 (C-c C-c)
他のページの編集 (C-c C-o)

trac-wiki コマンドを起動すると、まずプロジェクト名を聞いてきます。プロジェクト名の入力にはTABキーのよる補完が使えます。登録済みのプロジェクトであれば簡単に選択できます。あるいはプロジェクトを登録せずにこの時点でエンドポイントURLを与える事で、一時的なプロジェクト定義を行なう事も可能です。

プロジェクト名を指定するとエンドポイントURLが確定するのでアクセスが行なわれます。認証が必要な場合はこの時点でユーザ名とパスワードを求められます。そしてプロジェクトが提供しているWiki ページの一覧を取得して、それらを候補としてページ名の入力を促します。既存のページを編集したければ補完を使用してページ名を入力して下さい。新規ページを作成するのであれば、作成したいページ名を入力します。ページ名には漢字も使用可能です。

ページ名の入力後、ページの内容(Wiki 書式)を取得して表示します。バッファの内容を変更し、最後に C-c C-c (trac-wiki-commit<f>) で更新します。バッファはファイルに保存できませんので注意して下さい。そのため、このモードでは C-x C-s キーにはダミーの関数を当ててあります。

ページの編集を行なうバッファは trac-wiki-mode という、text-mode をベースとするモードになっています。このモードが提供するコマンドには以下のものがあります:

trac-wiki-commit

C-c C-c

現在の編集内容でサーバのページ内容を更新(コミット)します。

trac-wiki-edit

C-c C-o

編集するページ名の入力して、同じプロジェクトの別のページを新しいバッファで編集します。この時、ポイントがWiki リンク内やWiki ページ名上にある場合はそのページ名をデフォルトとして使用します。 (ver-1.5 からの機能)

trac-wiki-preview

C-c C-p

現在のバッファの内容をEmacs-w3m を使用してテキストベースでのぷレビューを行ないます。プリフィクス(C-u)を使用した場合は外部のWEBブラウザを起動してグラフィカルなぷレビューを行ないます。

trac-wiki-view-page

C-c C-v

外部ブラウザを使用してプロジェクトサイトにアクセスし、現在編集中のページの実際のページを表示します。この機能は、Emacs での編集を終えてブラウザ操作に移行するのに便利でしょう。 in browser. (ver-1.5 からの機能)

trac-wiki-diff

C-c =

C-c C-d

編集中の内容とオリジナルの内容の差分をdiff 形式で表示します。プリフクィス(C-u)を付けるとediff を使用して差分を表示/編集できます。

trac-wiki-merge

C-c C-m

編集中のページの元のバージョンと、実際のサイトでの最新のバージョンが違うかどうかを調べ、違いのであればediff-mergeを使用して両者をマージします。これにより、変更内容を維持したまま最新のバージョンをベースとした編集状態に移る事が出来ます。あるいは元のバージョンに対して変更を行なっていなければ、バッファの内容を最新のバージョンに更新してそれをベースにした編集状態にします。

trac-wiki-revert

C-c C-u

現在の変更内容を破棄します。破棄を行なう前に変更内容をdiff で表示して確認が行なわれます。

trac-wiki-show-info

C-c C-i

編集中のページのいくつかの情報をエコーエリアに表示します:

エンドポイントのURL
ページの名前と現在の変更状態
編集中のページのバージョンと、その最終変更者と更新日時

trac-wiki-complete-at-point

M-C-i

バッファ内でのマクロ名またはWiki ページ名の補完を行ないます。マクロ名はWikiMacrosページから取得してキャッシュします。したがって最初のマクロ名補完には若干時間がかかりますが、 2回目以降は素早く補完が行なえます。

trac-wiki-history

C-c C-h

別バッファにページ変更履歴を表示します。これはTrac のページでのページ変更履歴に相当しますが、Trac が提供するXML-RPC メソッドの機能不足によりWEB上での変更履歴ほど詳細な内容は得られません。変更履歴は別バッファで表示されます。カーソルを移動して特定のバージョンの項目上にて '=' キーを押すと、そのバージョンとの差分を表示する事が出来ます。

trac-wiki-search

C-c C-s

Tracプロジェクト内での検索を行ないます。検索キーワードの入力とフィルタの選択を行ないます。結果は別バッファにて表示され、ページ名やURLなどはハイライト表示されます。

おまけ情報

FireFox アドオン機能の It's All Text! や MozEx を使うと、XML-RPCをサポートしていないサイトのWiki ページやチケットの詳細/コメントの編集に便利です。これらの機能はページ上のテキストエリアの内容をテンポラリファイルに書き出して外部エディタで編集が出来るようにしてくれるものです。一旦 Emacs で編集が行なえるようになれば、メジャーモードを trac-wiki-mode にすることができます。この場合、XML-RPCでのアクセスは出来ないためtrac-wikiのもつ大部分の機能は使えませんが、バッファが色づけ表示されるため、編集の助けになると思います。
このモード変更の操作が面倒であれば以下のようなフックを仕込む事と良いかも知れません。
```
(defun trac-wiki-auto-mode-function ()
  (if (and (eq major-mode 'text-mode)
	   (member (file-name-extension (buffer-file-name))
		   '("txt" "wiki"))
	   (re-search-forward "^=+ [^=\n]+ =+\\s *$" nil t))
      (trac-wiki-mode)))

(add-hook 'find-file-hook
	  'trac-wiki-auto-mode-function)
```
このフックは、新しく開いたバッファがテキストモードでかつ trac wiki で使用されるヘッダ行の記述が見つかった場合には自動的に trac-wiki-mode を起動するというものです。ただし新規ページのように内容が空の場合には効果がありませんが。

trac-wiki-history でのページ履歴表示には、ページ更新時のコメントが表示されません。これはXmlRpcPlugin が厳密に仕様に従った故のものです。しかし、ほとんどの人はページ履歴でコメントこそが見たい情報だろうと思います。というわけで、ページ情報としてコメントも得られるようにするパッチを作りました。 trac-wiki.el はこのパッチに対応していますので、パッチが当たっている XmlRpcPlugin を使ったサイトに対しては、ページ履歴表示でコメントを表示する事が出来ます。

バグ報告

バグを見つけたら既存のチケットを検索し、該当する症状が見当たらなければ新規チケットを作成して下さい。

参考

Download in other formats:

Plain Text