Emacsは種々のグループにもとづいて関数をリストできます。たとえばstring-trimやmapconcatなどは“string(文字列)”の関数ですが、M-x
shortdoc RET string RETによって文字列を操作する関数の概要を得ることができます。
ドキュメンテーショングループはdefine-short-documentation-groupマクロにより作成されます。
関数グループとしてgroupを定義して、それらの関数の使用に関する短いサマリーを提供する。オプション引数functionsは要素が以下の形式であるようなリスト:
(func [keyword val]...)
以下のキーワードが認識される:
:eval値は評価時の副作用をもたないフォームであること。このフォームはドキュメント内でprin1でプリントして使用されることになる(出力関数を参照)。しかしこのフォームが文字列ならそのまま挿入されてから、フォームを生成するためにreadされる。いずれのケースでも、その後にフォームは評価されて結果が使用される。たとえば:
:eval (concat "foo" "bar" "zot") :eval "(make-string 5 ?x)"
は以下の結果になる:
(concat "foo" "bar" "zot") ⇒ "foobarzot" (make-string 5 ?x) ⇒ "xxxxx"
(Lispフォームと文字列の両方を受け付けるのは、特定のフォーム表現が望まれるいくつかのケースにおいてプリントのコントロールを可能にするのが理由。この例では‘?x’が文字列に含まれていなければ‘120’としてプリントされるだろう。)
:no-evalこれは:evalと似ているが、フォームを評価しない点が異なる。この場合では何らかの類の:result要素が含まれている必要がある。
:no-eval (file-symlink-p "/tmp/foo") :eg-result t
:no-eval*:no-evalと同様だが、常に‘[it depends]’を結果として挿入する。たとえば:
:no-eval* (buffer-string)
は以下の結果になる:
(buffer-string) → [it depends]
:no-value:no-evalと同様だが、対象となっている関数が明確に定義されたリターン値をもち、副作用のためだけに使用される際に用いられる。
:result評価されないフォーム例の結果を出力するために使用される。
:no-eval (setcar list 'c) :result c
:eg-result評価されないフォーム例の結果例を出力するために使用される。たとえば:
:no-eval (looking-at "f[0-9]") :eg-result t
は以下の結果になる:
(looking-at "f[0-9]") eg. → t
:result-string:eg-result-stringこれら2つはそれぞれ:resultや:eg-resultと同じだが、そのまま挿入される。これは結果が読めなかったり、特定の形式が要求される際に有用:
:no-eval (find-file "/tmp/foo") :eg-result-string "#<buffer foo>" :no-eval (default-file-modes) :eg-result-string "#o755"
:no-manualその関数がマニュアルにドキュメントされていないことを示す。
:argsデフォルトではその関数の実際の引数リストが表示される。:argsが与えられたら、かわりにそれらが使用される。
:args (regexp string)
以下に非常に短い例を示す:
(define-short-documentation-group string "Creating Strings" (substring :eval (substring "foobar" 0 3) :eval (substring "foobar" 3)) (concat :eval (concat "foo" "bar" "zot")))
1つ目の引数は定義するグループ名、その後に任意個数の関数説明が続く。
関数は任意個数のドキュメンテーショングループに所属できます。
このリストは関数説明に加えて、ドキュメントからセクションへの分割に使用される文字列要素ももつことができます。
この関数によりLispパッケージは関数をグループに追加できる。elemはそれぞれ上述したような関数説明であること。groupは関数グループ、sectionは関数を挿入する関数グループのセクション。
groupが存在しなければ作成する。sectionが存在しなければ、その関数グループの最後に追加される。
shortdocのグループで定義された関数の使用例の問い合わせもできます。
この関数はfunctionのshortdocすべての例をリターンする。リターン値はアイテムが(group . examples)という形式のalist。ここでgroupはfunctionが記載されたドキュメントグループ、examplesはgroupにおいて定義されているfunctionの使用例(文字列)。
functionが関数ではない、あるいはshortdocに例がなければshortdoc-function-examplesはnilをリターンする。
この関数は登録済みのshortdocグループにたいして問い合わせを行い、与えられたEmacs
Lispのfunctionの使用例をカレントバッファーに挿入する。これはhelp-fns-describe-function-functionsフックに追加するのに適している。そうすれば関数のドキュメントを要求された際に*Help*の使用例が*Help*バッファーに表示されるだろう。