リンクを辿ったときの表示方法が増えました
HTMLクラス
HTMLクラス
Initial release
langhelpはあらゆるプログラミング言語やコマンドのドキュメント情報源の目次を作成し、Emacs内で瞬時に検索することを目的としたツールです。 プログラミング中、「この関数の使い方、どうだったかな」と疑問に思うことはよくありますね。 あるコマンドを使いたいけど、使い方がわからなくなることもよくありますね。 langhelpが答えへ直行してくれます。
Rubyプログラミングを助ける類似のツールとして、拙作RDindexがありますが、langhelpはその後継となるよう開発しています。 RDindexはRD形式のドキュメントしか検索できませんが、langhelpは加えてRDoc、Refe、RubyDocなどの形式も扱えます。
現在langhelpがサポートしている言語・コマンドは以下のものです。
planner, xnee, html, svn, bison, cvs, libtool, latex, ratpoisonrc, java, id-utils, gengetopt, wget, lua, php, texinfo, c++, c, standards, grep, rb, gdb, diff, octave, scheme, python, global, flex, tcl, m4, sed, screenrc, xmms-shell, gzip, perl, emacs-lisp, ruby, autoconf, sgrep, hurd, el4r, binutils, awk, graphviz-dot, makefile, sh,
langhelpはEmacsRubyで書かれたおそらく世界初のツールです。 langhelpはEmacsRubyの実用的な例のひとつとも言えます。
動作には以下の環境が必要です。
筆者の環境はDebian GNU/Linux & Emacs21*1です。 他のGNU/Linux、Unix系OSでも問題なく動くと思われます。 Windows環境（Meadow + Cygwin）でも動作報告されました。
langhelpは他の検索ツールを排除するものではありません。 さまざまなツールの助けを得てこそ力を発揮します。 以下のツールは必須ではありませんが、あればlanghelpはパワーアップします。 langhelpは幾多の検索ツールを有機的に統合するツールなのです。
Info形式のドキュメントはとても簡単にlanghelpに取り込めます。
HTML形式のドキュメントを処理・表示するのに使います。
Rubyのメソッドの説明を英語で出力します。これはRuby標準添付です。
あるとriの呼び出しが高速化されます。
Rubyのメソッドの説明を日本語で出力します。
RubyDoc形式のドキュメントを処理します。
Luaのドキュメントを検索します。
Info形式のドキュメントの日本語訳。
EmacsLispがたくさん登録されています。
screenrcの編集を行うメジャーモードです。
ratpoisonrcの編集を行うメジャーモードです。ratpoison標準添付です。
バッファ内のブックマークです。 ブックマークを設定した行にはわかりやすく色がつけられ、ブックマーク間のジャンプも可能です。 langhelpに限らずいろんな場面で使えるため、おすすめです。
まず、EmacsRubyを動かすためにel4rをインストールします。
ruby -ropen-uri -e 'URI("http://www.rubyist.net/~rubikitch/archive/el4r-1.0.4.tar.gz").read.display' > el4r-1.0.4.tar.gz
tar xzf el4r-1.0.4.tar.gz
cd el4r-1.0.4
ruby setup.rb
ruby -S el4r-rctool -p
ruby -S el4r-rctool -i
次はlanghelpをインストールします。 以下のコマンドを実行してください。
ruby -ropen-uri -e 'URI("http://www.rubyist.net/~rubikitch/archive/langhelp-0.9.8.tar.gz").read.display' > langhelp-0.9.8.tar.gz
tar xzvf langhelp-0.9.8.tar.gz
失敗する場合は次のリンクからダウンロードしてください。
それから次のコマンドでインストール。
cd langhelp-0.9.8 ruby setup.rb
Victor BorjaさんがGentoo ebuildを作成してくれました。 ありがとうございます。
Boris DaixさんがDebian packageを作成してくれました。 ありがとうございます。 /etc/apt/sources.listに次の設定を加えてください。
deb http://alysse.dyndns.org/~bdaix/debian/packages unstable/ deb-src http://alysse.dyndns.org/~bdaix/debian/packages unstable/
インストールが終わったら設定ファイルを書きます。
個人設定ファイルは ~/.langhelp/config です。 純粋なRubyスクリプトです。 ややこしいですががんばってください。
初めてインストールする人は、 data/langhelp/config.sample を ~/.langhelp/config へコピーしてください。
設定に必要な情報は config ファイルに書かれています。 configファイルの中のパス等の記述は筆者の環境のものです。 info 等のファイルが別のパスに置かれているのなら適宜に修正してください。 特に Windows 環境では、まずほとんどの場合パスを書き換える必要があるかと思います。 詳細についてはconfigファイル中のコメントに書いてあります。
configファイルの修正を助けるために、[EVAL IT] マークがつけられた行を用意しています。 [EVAL IT]マークの後ろに書かれているのがS式です。 その行に移ってC-e C-x C-eを押してS式を評価してください。 ドキュメントのありかや公式サイトへ飛んでくれたりします。 もし、Debian GNU/Linux環境ならば debian: 行に書いているパッケージを apt-get install するだけでドキュメントがインストールされます。
設定ファイルを1から書くのは大変なのでインストール後もシステム上に置くようにしています。 次のコマンドでconfig.sampleのありかを出力します。 *2
ruby -rrbconfig -e 'puts "#{Config::CONFIG["datadir"]}/langhelp/config.sample"'
さっさと進みたい人は常用の言語ひとつのみ設定してください。
まず
mklanghelp --all
を実行してください。ハイフンは2つです！ Windowsの人は
ruby -S mklanghelp --all
とする必要があるでしょう。
多分多くのエラーメッセージがでますが、ほとんどの場合 config に書かれた場所にドキュメントが存在しないからです。 エラーが起きた部分は無視され、できる限り最大限の努力をします。
エラーが起きた箇所については、後でドキュメントをインストールしたり、パスを修正するなり、その部分をコメントアウトするなりしてください。
GNUjdocはたくさんのInfoファイルを日本語訳しているGNU公認プロジェクトです。 日本人には心強い味方となるでしょう。 ただし、Infoファイルへ変換するにはautomake, autoconfをインストールする必要があります。 *3
以下の手順で ~/.langhelp/gnujdoc/ 以下にドキュメントが配置されます。 configのパスもそうなっています。
展開します。
Infoファイルへ変換します。
autoreconf -fi ./configure make
langhelpはEmacs上で動きます。 Emacsには御存知の通り、さまざまな言語用のメジャーモードが存在します。 プログラミング言語に限らず、設定ファイル専用のメジャーモードさえ存在します。 通常メジャーモードの名前は -mode で終わります。
langhelpはメジャーモードで言語を判断します。 ここでlanghelpの「言語名」とはメジャーモード名から -mode を取り除いた文字列と定義します。 たとえばRubyに対してはruby-modeがメジャーモードで言語名はrubyです。 GraphvizのDOT言語に対してはgraphviz-dot-modeがメジャーモードなので、graphviz-dotが言語名です。
もしメジャーモードが存在しないのであれば、 define-generic-mode や define-derived-mode などででっちあげてしまいましょう。 ただ、メジャーモードが存在してればいいのです。
例 (define-generic-mode 'foo-mode (list ?#) nil nil nil nil) (define-derived-mode baz-mode fundamental-mode "baz")
言語ごとの設定とは、 @lang 変数を適切に設定することです。
@lang変数は、言語名（String）をキーとし、「Hash要素のみを持つ配列」を値に持つHashです。 配列内部のHashをここでは「ドキュメント定義」と呼びます。
こういう感じで設定します。
@lang["言語名が入ります"] = [
{ ... },
{ ... },
]
[から]までがその言語の設定部分です。 なお、スペースの量は任意です。 行中の # から後ろはコメントなので無視されます。
{から}までが「ドキュメント定義」です。
バージョン0.9.8より設定の動作確認ができるようになりました。 ドキュメント定義の行にカーソルをあわせて
M-x langhelp-test-definition-this-line
を実行すると、そのドキュメント定義が出力する目次を確認できます。
次のコマンドで文法が正しいかチェックしてください。
ruby -c ~/.langhelp/config
langhelpは言語ごとに目次を持ちます。 設定ファイルに基いて目次を作成するのが mklanghelp コマンドです。
引数なしで起動すると、使い方を表示します。
mklanghelp
筆者の環境では次のように出力されます。
Usage: mklanghelp [options] [languages]
Supported languages: planner, xnee, html, svn, bison, cvs, libtool, latex, ratpoisonrc, java, id-utils, gengetopt, wget, lua, php, texinfo, c++, c, standards, grep, rb, gdb, diff, octave, scheme, python, global, flex, tcl, m4, sed, screenrc, xmms-shell, gzip, perl, emacs-lisp, ruby, autoconf, sgrep, hurd, el4r, binutils, awk, graphviz-dot, makefile, sh
-a, --all Output index of all languages.
--home=DIR Output directory of index files.
--suffix=SUFFIX Suffix of index files [default: .e]
-c, --init-script FILE Initialize script name [default: /home/rubikitch/.langhelp/mklanghelp-init.rb]
-f Suppress read of init script.
--langs Output supported languages.
--stdout Output index into stdout.
-e, --eval=EXP Evaluate.
-d, --debug Output stack trace when error occurred.
引数に言語名を並べると、それぞれの言語の目次を作成します。 --allで全ての言語の目次を作成します。
mklanghelp ruby emacs-lisp mklanghelp --all
langhelpで管理されているドキュメントにアクセスしたくなったら、
C-c s
でlanghelpを起動してください。 0.9.0よりアップグレードする人はconfigファイルに次の行を加えてください。もちろんお好きなキーに変えても構いません。
@langhelp_key = '\C-cs'
すると、画面が切り替わり、 *langhelp:言語名* というバッファが出てきます。 そのときすでにincremental searchに入っているので、そのまま検索してください。
langhelpを呼出したときに、
# (lh-ri "Array#pack")
などカッコで包まれた行がたくさん出てきます。 最初はぎょっとすると思いますが、実はEmacsLisp式（S式）です。 S式を評価することで、情報源にアクセスしているのです。 いってみれば、S式ハイパーリンクです。 これは、EmacsLisp関数を適宜定義してやれば、どんな情報にもアクセスできることを意味しています！ langhelpが高い柔軟性を持ち、「統合」ドキュメント検索器と名乗っているのは、そういうわけなのです。
カーソルの上下移動はp, nに加えてvi風のk, jも使えます。
リンクへ飛ぶにはl, RETです。 リンクには行を指定している（行番号か行の内容）場合がありますが。 l, RETは指定された行をウィンドウ最上部に表示します。 ;, L, Cは指定された行をウィンドウ中央部に表示します。 そのとき、指定された行がわかるように一瞬ハイライトされます。 oでリンク先のウィンドウへフォーカスを移します。
リンクをどんどん開いていると、バッファがどんどん増えていきます。 K, Dでリンク先のバッファを削除できます。
検索中にC-oを押すと検索中の単語が含む行のみを表示する絞り込み検索ができます。 絞り込み検索中にさらに絞り込み検索もできます。
bm.elがインストールしてあれば、mでその行に「しおり」をつけられます。P, N(K, J)でしおり間をジャンプできます。
C-c C-nで現在表示中のセクションのみを表示・全体を表示を切り換えます。
langhelpから抜けるにはC-c C-cです。呼び出す前のウィンドウ構成に戻ります。 人によっては、ウィンドウ構成を保存するEmacsLispと併用することを好むかもしれません。 そういうEmacsLispはwindows.el、 escreen.el、elscreen.elなどがあります。 独立したフレームに表示することを好むかもしれません。
その他キー割り当ての詳細はconfigファイルの@KEY_BINDINGを見てください。 修正することで好きなキーに機能を割り当てられます。
langhelp起動後に目次を再生成したり config ファイルを変更した場合は、el4rを再起動してください。 すかさず反映されます。
M-x el4r-boot
langhelpを使っていると、今編集している言語以外の項目を見たいときがあります。 そのときはC-uをつけて起動してください。
C-u C-c s
すると、langhelpが管理している全言語の目次が出て来ます。 通常同様incremental searchに入っているので、すかさず目的の言語へ移動できます。
また、*langhelp:言語名* バッファ中でもdを押すことで、全言語の目次へ移動できます。
バージョン0.9.7より、カーソル上の単語を検索することができるようになりました。
C-u C-u C-c s
あるいは
M-x langhelp-at-point
で目次からカーソル位置の単語を検索してくれます。
カスタマイズするにはまずconfigファイルのコメントに書かれている説明を熟読してください。
使いこんでくると、そのうち自分用の目次作成クラスや、目次から呼出されるEmacsLisp関数を書きたくなってくるでしょう。 当然、それなりのRubyの知識が必要です。
しかし、そこまでする必要があることは稀です。
config ファイルに説明があるように Grep や W3MGrep などの汎用目的のクラスが存在します。 Grepクラスはファイル中で正規表現にマッチする行のみを抜き出し、それを目次にします。 W3MGrepクラスはGrepとほとんど同じですが、w3mによりplain text化されたものが処理対象です。 HTMLクラスはHTMLファイル中の重要な要素（H1〜H6、DT）を抜き出して目次にします。 正規表現の設定次第でplain textやHTMLによるマニュアルは問題なくlanghelpに取り込むことができるでしょう。
~/.langhelp/mklanghelp-init.rbはmklanghelpで処理する前に呼ばれるRubyスクリプトです。 これに自作目次作成クラスを記述してください。
目次作成クラス FooIndex は次のように定義します。
Foo#init(x={}) は初期化を行う
Foo#normalize_filename!(*filenames) は指定された各々のファイル名を正規化
Foo#arg1 はクラス名のシンボル（:Foo）の値
Foo#to_e(out) はリンクの書き出し
詳しくはlanghelp/lh_*.rbを見てください。 一番簡単な目次作成クラスは LuaHelp です。
目次作成クラスを定義できたら、 config ファイルに設定を記述します。
@lang["foo"] = [
{:FooIndex => true, :title=>"Foo", :cmd=>"fooindex"},
]
configに設定を書いたら
mklanghelp foo
でfooの目次を作成します。そして el4r を再起動します。
M-x el4r-boot
Emacs内でfoo-modeのとき、langhelpを起動すると、FooIndexによる目次が表示されます。 上の指定の場合、 lh-fooindex 関数を呼び出すようになります。 lh-fooindex関数はcmdで指定されている fooindex シェルコマンドを呼出します。
el4r起動時に（つまりlanghelpも起動）定義されるEmacsLisp関数は ~/.el4r/init.rb に書きます。 当然このファイルはEmacsRubyとして実行されます。
langhelpでは任意の名前のEmacsLisp関数が使えます。 が、 lh- というprefixをつけると font-lock により色がつくようになります。
バージョン0.9.7よりウィンドウシステム上の（つまり-nwではない）Emacsはデフォルトでlanghelpフレームを使うようになりました。 フレーム嫌いな人は ~/.langhelp/config に
@NO_FRAME = true
と書いてください。
mklanghelpコマンド及び lib/langhelp/*.rb は、エディタの特性には全く依存していません。 それらの仕事は、ただ目次を書き出すだけです。 唯一Local Variablesを書き出すところのみ、Emacsに関係あるところです。
lib/el4r/emacsruby/langhelp.rb 相当のプログラムを書けば（つまり、目次に登場するすべての関数を実装すれば）、xyzzyなど他のLisp系エディタでも動くと思います。 目次に登場するS式はほとんどすべてネストしていない（一組の()のみ）ので、()の中身を読み取れば非Lisp系エディタにも移植できると思います。
もし移植してくれる人がいるならば、喜んで取り込みます。
なにかわからない点がありましたら、ruby-listメーリングリストかページ最下部にある投書箱から遠慮なく質問してください。 同じ問題に悩んでいる人がいるかもしれないので、ruby-listの方がおすすめです。 langhelpが未サポートの言語の設定、よりよい設定例も大歓迎です。
GPLとします。
*1現在はEmacs22へ移行しました。
*2筆者の環境では /usr/local/share/langhelp/config.sample と出ます。
*3MeadowだとNetInstallがあるので実は問題ない？