手っ取り早く答え
-> Vimのhelpに書いてありました。:help tags-file-format
今回話すことは大抵ここに書いてあります、英語が読めればそちらの方が参考になるかと。
又、日本語に翻訳されているものもありますので手間でなければこちらの方がわかりやすいかもです ==> http://vim-jp.org/vimdoc-ja/tagsrch.html#tags-option
こんな事始めた動機
- vimでタグジャンプを覚えたてで、楽しくなってたから
- プロダクトのドキュメントを書くにあたり、manページは時間かかるしSphinxとかわけわかめだったので何か便利なものを探していたから
- Noob-VIMMERなので
- ctagsはあるのわかってるけど、書き方があまりにも見つからなかったから(後述)
- ただ単に興味;)
tagsファイルとは
tagsファイルとは、vimやEmacsでテキストを表示した時に、「タグジャンプ」と呼ばれる機能を追加するためのファイルです。
ファイル中の単語から、説明があるものについてはそこへジャンプすることができるようになります。
例として、以下のようなテキストがあったとします。（適当に作成）
1 *help.txt* For version x.x.x
2
3 mcUI - Main help page
4
5 Overview: mcUI is the world first 3D UI using Minecraft
6 Description: This is a |Minecraft mod| which enable to use 3DUI
7 Required MC version: Anything you like!(If it's supported by |Raspberry Jam mod|
8 Author: Cj.bc_sd
9
. .
. .
. .
50 *Raspberry Jam mod* The main dependency of mcUI
51
52 What's this: The Raspberry Jam Mod(RJM) allows us to use MinecraftAPI like mc Pi Edition.
53 Its Author: arpruss
54 Repository: https://github.com/arpruss/raspberryjammod
. .
. .
. .
上から順番に見ていくことになりますが、Line:7,Raspberry Jam Modって何でしょう？
なんか気になりますね。
そんな時に、Raspberry Jam Modの文字の上で<Ctrl>+]（default）を押すことでLine50のRaspberry Jam Modの説明までジャンプできるんです！！便利！！
ちなみに<Ctrl>+tでジャンプ前の場所まで帰る事ができます。
という事でこのジャンプを実現するためのファイルを書いていきます。
（ちなみに身近な例で言えば、vim使用中の:help <commands>系は大抵tagジャンプを使って開かれているようです)
え？tagsファイルならctagsあるでしょ？？？
え??あれC言語用じゃないの？？
って事で、ctagsはc言語特化だと思っているので使わないです。普通にテキストにリンクを貼りたいんです！！
【早期解決したい人向け】便利なツールたち
このtagsファイルを生成するツールはたくさんあります。
それぞれについては把握してないので興味があれば各自調べて見てください。
:help tags-file-formatの受け売りになりますがまぁ
| tool名 | 特徴など | 対応言語 | URL/Path |
|---|---|---|---|
| ctags | 一番基本的なツール。殆どのUNIXにある | C言語のみ | - |
| Exuberant_ctags | ctagsの上位互換的な？「めっちゃいいやつ」 | C,C++,Java,Fortrun,Eiffel等 |
|
| etags | Emacs互換っぽい。 | 色んな言語(by help:) |
- |
| JTags | JavaによるJavaのためのツール | Java | http://www.fleiner.com/jtags/ |
| ptags.py | Pythonによるpythonのための(ry | Python | pythonのソースディレクトリーの Tools/scripts/ptags.py |
| ptags | PerlによるPerlのたm(ry | Perl | http://www.eleves.ens.fr:8080/home/nthiery/Tags/ |
| gnatxref | gnatパッケージの一環らしい | Ada | http://www.gnuada.org/ (なんか移動したっぽい？情報求) |
今回はこれらのツールなしで手動で作っていこうかなと思います。
【本題】tagジャンプができるようにするまでの流れ
- 元のドキュメントのファイルを作る
- 新たにテキストファイルを作り、tagsファイルとする
- 元のドキュメントのファイルを開き、
:set tags=<file_name>でtagsファイルの指定を行う - そうするとほら、
<Ctrl>+]で飛べるはずでっせ！！
1.元のドキュメントのファイルを作る
これは特にいうことないですね。ただ単に、お好きなエディタ（話の流れ的にVimかEmacsの人が多そうですが）でドキュメントを書きます。
:helpを見ている限り、の話にはなりますが、tagジャンプ元はpipe|で囲っている場合が多いようです(|tags-file-format|等)
2. tagsファイルを作成する
ここが本題となります。
tagsファイルは基本的に次の書式で書かれます。
1. {tagname} {TAB} {tagfile} {TAB} {tagaddress}
2. {tagfile}:{tag name} {TAB} {tagfile} {TAB} {tagaddress}
3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} ..
{tagname} => タグの識別子です。何でも良いそうな。ただし<TAB>は入ってこれないそうです
{tagfile} => tagnameを定義している部分の入ったファイルです。同じく<TAB>ダメ、絶対
{tagaddress} => タグが見つかった際の処理をExコマンドで書きます。いくつか制限はあるものの、ある程度は自由なコマンドが使えます。ただし、Posixは、ラインナンバーと検索のみを提供するようです。
{term} => ;"である。たったこれだけ。viとの互換性を図るため、その行のこれ以降をコメントアウトしている。
{field} => なんかよくわかんなかった
とりあえずまあ、これで作成してみます。ファイル名は何でもいいですが、後述しますがtags若しくはtagだと楽です
3.ドキュメントを開き、tagsファイルを指定する
$vim document.mdなどで開き、:を打ってコマンドモードにしてからset tags=<あなたのtagsファイルのパス>とします。
ちなみにデフォルトのtagsは./tags,tagとなっているため、2.の時点でtagsファイル名をtags若しくはtagにしていた場合、この作業をせずともtagsファイルが認識され、<Ctrl>+]で動くはずです。（戻るときは<Ctrl>+tです）
4.Fin!!
やったね！！これでtagsファイルがとりあえずできましたよっと。
これでもう、vimで上下する苦労は（少しは）無くなりますね（きっと）！！
今回のポイント
- tagsファイルの書式を覚える！
- なるべくなら
tagsかtagという名前でtagsファイルを作成して、自動で使えるようにする！ - 自動でtagsファイルを使ってもらうためには、tagsファイルとドキュメント本体を同じ階層におく！
-
:helpをもっときちんと読む。ggrよりもはるかに高品質な情報がある。
続きの記事
ちなみに現段階だと色が全くなくて殺風景というかなんか読みづらいので、次の記事ではその色関連を少し書きます！（.vimファイルとかの作成はしないので悪しからず）
続きの記事 -> Vimで折角tagsファイルを作成したドキュメントに色をつけたい！！
現状わからないこと、課題
- tagの名前を複数単語に対応させる方法
悪ガキのあとがき
今回例で出てきたmcUIというのは、実際に現在絶賛開発中の、Minecraftを用いてパソコンに新たなUIを作ろうというプロジェクトです。現段階ではまだ形になっていなさすぎてわけわかめな説明だと思いますが興味があればぜひ見ていってください -> Cj-bc/mcUI
-
http://ctags.sourceforge.net が本家なのですが、更新されない可能性が高いということでUniversal ctagsのURL( https://ctags.io/ )を置き換えていれました。@mattnさんありがとうございます！ ↩