------------------------------------------------------------------------
			野鳥用付加関数の作成方法
------------------------------------------------------------------------


【付加関数とは】

	  begin 型補完で、「tabular 環境を入力している時に、わたしの好み
	のスタイルが入らないなあ」などと思うことはありませんか。tabular 
	環境に限らず、LaTeX の環境の引数には、各人お決まりのフォーマット
	があるものです。たとえば凝った表を書く時の tabular環境の引数は、
	かなり複雑なので、デフォルトの自動入力関数よりも、

		"{@{\vrule width 1pt\ }|||@{\ \vrule width 1pt}}"

	を挿入するだけの単純な関数のほうが、嬉しい人もいるでしょう。あるい
	は、「そんなの要らない。他の tabular をコピーして来たほうが早い。」
	と思う人もいるでしょう。

	  YaTeX の付加関数は、あらかじめ○○環境用のお仕着せの特別関数を用
	意しておくのではなく、○○環境用の特別関数が欲しくなったら独自の関
	数を定義する、というコンセプトに基づくもので、付加関数の登録のため
	の手続きをすることなく、関数を定義したその瞬間から使えるようになり
	ます。「必要なのは、defun だけ」です。


【準備】

	  さすがに、関数を書くだけでは使えません:-)。yatex-mode 起動時には、
	その関数を定義したファイルがロードされていなくてはなりません。関数
	を定義するファイル名を yatexhks.el(またはバイトコンパイルした形式
	の yatexhks.elc)にし、そのファイルを load-path 中に置いておけば、 
	野鳥が自動的にロードします。それ以外のファイル名にする場合は、
	yatex-mode-load-hook に付加関数を定義する Emacs-Lisp ファイルをロー
	ドするような仕掛けを書いておくのがよいでしょう。


【関数定義】

	  付加関数には、各LaTeXコマンドのオプション引数を返す形式のもの、
	section型補完の引数を返すもの、リジョン括りsection型補完の引数該当
	部を処理するためのもの、三種類があります。ここでは便宜上その三つを、

		a. 追加型付加関数
		b. 引数型付加関数
		c. 括り補完時付加関数

	と呼ぶことにします。

	  a は、以下の例のように、begin型補完では\begin{環境名}の直後に付
	加する文字列、section型補完では LaTeX コマンド名と第一引数の間に位
	置する文字列、maketitle型補完では LaTeX コマンド名の直後に位置する
	文字列を返すような関数です。

	(例)	\begin{table}[ht]	(付加関数名 YaTeX:table)
		             ~~~~
		\put(100,200){}		(付加関数名 YaTeX:put)
		    ~~~~~~~~~
		\sum_{i=0}^{n}		(付加関数名 YaTeX:sum)
		    ~~~~~~~~~~

	追加型付加関数は『LaTeXコマンド名の前に YaTeX: をつけた名前』で定
	義します。

	  b は、以下のようにsection型コマンドの引数となる文字列を返す関数
	です。

	(例)	\newcommand{\foo}{bar}	(付加関数名 YaTeX::newcommand)
			    ~~~~  ~~~

	引数型付加関数は『LaTeXコマンド名の前に YaTeX:: をつけた名前』で定
	義します。また引数型付加関数が呼ばれる時にはsection型コマンドの何
	番目の引数を入力しているのかが関数への引数として渡されます。したがっ
	て、引数型付加関数は整数の引数を一つ取るものとして定義し、その引数
	の値により処理を決定することになります。

	(yatex.1.72の新機能)
	  c は、既存テキストの一部をsection型コマンドの引数として括るとき
	に、指定したりジョンの先頭と末尾の各ポイントを引数として呼ばれます。
	たとえば、

		5/3

	というテキストをリジョン指定して [prefix] S でセクション型コマンド
	で括りたいときに、括られるテキストに対してなんらかの処理をほどこし
	たいときに呼ばれます。

	(例)	5/3		←5/3をリジョン指定し \frac で括る
		\frac{5/3}	←5/3のポイント位置を引数に呼ばれる
		      ~~~	(付加関数 YaTeX::frac-region)
		

【定義例】

	  例えば、tabular環境のフォーマットとして、いつでも {|c|c|c|} を入
	れるだけで良いのなら、

		(defun YaTeX:tabular ()
		  "{|c|c|c|}")

	とだけ書けばよく、前述の、複雑な定型 tabular フォーマットを挿入す
	るための関数を定義する場合は次のようにします。

		(defun YaTeX:tabular ()
		  "{@{\\vrule width 1pt\\ }|||@{\\ \\vrule width 1pt}}")

	この時、Emacs-Lisp 中の文字列では、\ 自身は \\ と表記することなど
	に注意して下さい。

	  また、{} の中を、補完時に直接キーボードから読み込ませたい時は、

		(defun YaTeX:tabular ()
		  (concat "{" (read-string "Rule: ") "}"))

	などとすれば良いでしょう。

	  次に、引数型付加関数として \newcommand の引数を読み込む関数を定
	義する場合を例示します。\newcommand の第一引数は新たに定義するコマ
	ンド名なので、必ず先頭に \ が来ます。第二引数はたいていの場合ミニ
	バッファでは編集しづらいような複雑な定義を書くので、何も補完しない
	方が良いでしょう。これを考慮して付加関数を定義すると以下のようなも
	のになるでしょう。

		(defun YaTeX::newcommand (n)	;nは引数の位置
		  (cond
		   ((= n 1)			;第一引数ならコマンド名
		    (read-string "Command: " "\\")) ;\を初期入力とする
		   ((= n 2) "")			;第二引数なら何もしない
		   (t nil)))

	なお、引数型付加関数が nil を返した場合は、通常の引数入力関数が呼
	ばれます。

	  最後に括り補完時付加関数の例として、既存テキストを \frac で括
	る場合の例を示します。\frac は2つの引数を取り、\frac{a}{b} のよ
	うにして、分数を表すときに利用するコマンドです。数学的には

				a
		a/b        ⇔  ----
				b

	と置き換え可能な記法です。LaTeXソースにa/bと書いたものを野鳥の括
	り補完で\fracに括ると、以下のようになります。

		\frac{a/b}

	/の部分を }{ に置き換えれば正しい書き換えになります。このような
	ことを対話的に半自動で行なうアドイン関数は以下のようにします。

		(defun YaTeX::frac-region (beg end)	;リジョンの先頭と末尾
		  (catch 'done
		    (while (search-forward "/" end t)	;/がある間繰り返す
		      (goto-char (match-beginning 0))	;/の位置に移動
		      (if (y-or-n-p "Replace this slash(/) to `}{'")
			  (throw 'done (replace-match "}{"))) ;置き換えて終了
		      (goto-char (match-end 0)))))


【呼ばれ方】

	  野鳥本体は、begin型補完とsection型補完、およびmaketitle型補完の
	入力時に付加関数の存在を調べてから呼び出します。begin型補完の場合 
	\begin{環境名} が自動入力された直後に呼び出されます。section型補完
	では第一引数の補完の直前、maketitle型補完の場合は、コマンド名の直
	後(一つのスペースを挿入する直前)に呼び出されます。引数型付加関数は、
	section型コマンドの引数の入力時にその都度呼ばれます。括り補完時付
	加関数は、LaTeXコマンドと{}がテキストに挿入された直後に呼ばれます。


【参考】

	  付加関数の定義の例を yatexadd.el に用意しました。実際に独自の付
	加関数を定義する時の参考として下さい。

	  有用と思われる関数について、簡単に説明します。

	・関数	YaTeX:read-position
	  引数	[] の中に入れてもよい文字を羅列した文字列。
	  説明	[htb] などのような location 指定を作成します。何も入力せず
		リターンを押すと、[]自体も省略されます。[]の中に来るべき文
		字が htbp に限られているなら、(YaTeX:read-position "htbp")
		と呼び出します。

	・関数	YaTeX-cplread-with-learning
	  引数	プロンプト
		デフォルト補完テーブル変数シンボル
		ユーザ補完テーブル変数シンボル
		ローカル補完テーブル変数シンボル
	  説明	「プロンプト」というプロンプトを出し、補完入力を行います。
		三つの変数のテーブルの値を結合したものが補完候補として用
		いられ、新しい単語を入力すると自動的に学習されます。学習
		結果は ~/.yatexrc か ./.yatexrc に保存されます。使用例と
		して YaTeX::documentstyle 関数の定義をごらんください。

	・関数	YaTeX:read-coordinates
	  引数	基本プロンプト、X座標プロンプト、Y座標プロンプト(全て省略可)
	  説明	「基本プロンプト X座標プロンプト:」というプロンプトを出し
		て、X座標を読み込み、「基本プロンプト Y座標プロンプト:」を
		出して、Y座標を読み込み、(X座標,Y座標) の様な形式を作成します。
		何も入力せずリターンを押しても、(,)が返されます。
		各プロンプトのデフォルトはそれぞれ、Dimension, X, Y です。

	・関数	YaTeX:check-comletion-type
	  引数	'begin または、'section または、'maketitle
	  説明	付加関数が呼ばれる時に、行われている補完の形式が、引数で与
		えたものであるかどうか調べ、そうでない場合にエラー終了する。
		なお、変数 YaTeX-current-completion-type に現在の補完の型
		を表わすシンボル(この関数の引数と同様)が格納されています。


【最後に】

	  快適な関数を定義したなら、そしてそれを公開してもよいと思われたな
	ら、筆者までお送り下さい。次の yatexadd.el に取り込んで行きたいと
	思います。


								広瀬雄二
							yuuji@yatex.org