help.texi

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/help
@node Documentation, Files, Modes, Top
@c @chapter Documentation
@chapter 説明文
@c @cindex documentation strings
@cindex 説明文字列

@c   GNU Emacs Lisp has convenient on-line help facilities, most of which
@c derive their information from the documentation strings associated with
@c functions and variables.  This chapter describes how to write good
@c documentation strings for your Lisp programs, as well as how to write
@c programs to access documentation.
GNU Emacs Lispには、便利なオンラインのヘルプ機能があります。
そのほとんどは、関数や変数に付随した説明文字列から取り出したものです。
本章では、説明文を参照するプログラムの書き方に加えて、
読者のLispプログラムに適切な説明文字列を書く方法を説明します。

@c   Note that the documentation strings for Emacs are not the same thing
@c as the Emacs manual.  Manuals have their own source files, written in
@c the Texinfo language; documentation strings are specified in the
@c definitions of the functions and variables they apply to.  A collection
@c of documentation strings is not sufficient as a manual because a good
@c manual is not organized in that fashion; it is organized in terms of
@c topics of discussion.
Emacsの説明文字列は、Emacsマニュアルと同じものではないことに注意願います。
マニュアルには言語texinfoで書いた独自のソースファイルがありますが、
説明文字列は関数や変数の定義の中で指定されています。
説明文字列を集めても、よいマニュアルとは構成が違いますので、
マニュアルとしては十分ではありません。

@menu
* Documentation Basics::      Good style for doc strings.
                                Where to put them.  How Emacs stores them.
* Accessing Documentation::   How Lisp programs can access doc strings.
* Keys in Documentation::     Substituting current key bindings.
* Describing Characters::     Making printable descriptions of
                                non-printing characters and key sequences.
* Help Functions::            Subroutines used by Emacs help facilities.
@end menu

@node Documentation Basics
@comment  node-name,  next,  previous,  up
@c @section Documentation Basics
@section 説明文の基本
@c @cindex documentation conventions
@c @cindex writing a documentation string
@c @cindex string, writing a doc string
@cindex 説明文の慣習
@cindex 説明文字列を書く
@cindex 文字列、説明文字列を書く

@c   A documentation string is written using the Lisp syntax for strings,
@c with double-quote characters surrounding the text of the string.  This
@c is because it really is a Lisp string object.  The string serves as
@c documentation when it is written in the proper place in the definition
@c of a function or variable.  In a function definition, the documentation
@c string follows the argument list.  In a variable definition, the
@c documentation string follows the initial value of the variable.
説明文字列は、文字列に対するLisp構文、
つまり、文字列のテキストをダブルクォートで囲って書きます。
これは、説明文字列が実際にはLispの文字列オブジェクトだからです。
関数や変数の定義の正しい箇所に文字列を書くと、
説明文としての役割を果たします。
関数定義においては、説明文字列は引数のつぎにあります。
変数定義においては、変数の初期値のつぎにあります。

@c   When you write a documentation string, make the first line a complete
@c sentence (or two complete sentences) since some commands, such as
@c @code{apropos}, show only the first line of a multi-line documentation
@c string.  Also, you should not indent the second line of a documentation
@c string, if it has one, because that looks odd when you use @kbd{C-h f}
@c (@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}) to
@c view the documentation string.  @xref{Documentation Tips}.
説明文字列を書くときには、
最初の1行は1つの（あるいは2つの）完全な文にしてください。
@code{apropos}などのある種のコマンドは、
複数行にまたがる説明文字列の最初の1行だけを表示するからです。
また、説明文字列の2行目以降を字下げしないでください。
字下げがあると、
@kbd{C-h f}（@code{describe-function}）や
@kbd{C-h v}（@code{describe-variable}）で説明文字列を表示すると
不恰好になります。
@xref{Documentation Tips}。

@c   Documentation strings can contain several special substrings, which
@c stand for key bindings to be looked up in the current keymaps when the
@c documentation is displayed.  This allows documentation strings to refer
@c to the keys for related commands and be accurate even when a user
@c rearranges the key bindings.  (@xref{Accessing Documentation}.)
説明文字列には、特別な部分文字列、つまり、
説明文を表示するときに現在のキーマップからキーバインディングを探す
ことを表すものがあります。
これにより、ユーザーがキーバインディングを変更していても
説明文字列から関連するコマンドのキーを参照できます。
（@pxref{Accessing Documentation}）。

@c   In Emacs Lisp, a documentation string is accessible through the
@c function or variable that it describes:
Emacs Lispでは、説明文字列はその説明対象である関数や変数を介して参照します。

@itemize @bullet
@item
@c The documentation for a function is stored in the function definition
@c itself (@pxref{Lambda Expressions}).  The function @code{documentation}
@c knows how to extract it.
関数の説明文は、関数定義自身に収められている
（@pxref{Lambda Expressions}）。
関数@code{documentation}がその取り出し方を知っている。

@item
@kindex variable-documentation
@c The documentation for a variable is stored in the variable's property
@c list under the property name @code{variable-documentation}.  The
@c function @code{documentation-property} knows how to retrieve it.
変数の説明文は、変数の属性リストに
属性名@code{variable-documentation}で収められている。
関数@code{documentation-property}がその取り出し方を知っている。
@end itemize

@c @cindex @file{DOC} (documentation) file
@cindex @file{DOC}（説明文）ファイル
@cindex @file{emacs/etc/DOC-@var{version}}
@cindex @file{etc/DOC-@var{version}}
@c To save space, the documentation for preloaded functions and variables
@c (including primitive functions and autoloaded functions) is stored in
@c the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs.  The
@c documentation strings for functions and variables loaded during the
@c Emacs session from byte-compiled files are stored in those files
@c (@pxref{Docs and Compilation}).
場所を節約するために、あらかじめロード済みの関数や変数
（基本関数や自動ロード対象の関数を含む）に対する説明文は、
Emacs本体にではなく、ファイル@file{emacs/etc/DOC-@var{version}}に
収めてあります。
Emacsセッションの最中にバイトコンパイル済みのファイルから
ロードされる関数や変数の説明文字列は、当該ファイルに収めてあります
（@pxref{Docs and Compilation}）。

@c The data structure inside Emacs has an integer offset into the file, or
@c a list containing a file name and an integer, in place of the
@c documentation string.  The functions @code{documentation} and
@c @code{documentation-property} use that information to fetch the
@c documentation string from the appropriate file; this is transparent to
@c the user.
Emacs内部のデータ構造では、説明文字列のかわりに、
ファイル内の位置を表す整数かファイル名と整数を含むリストで表します。
関数@code{documentation}や@code{documentation-property}は、
この情報を用いて適切なファイルから説明文字列を取り出します。
この処理はユーザーには見えません。

@c   For information on the uses of documentation strings, see @ref{Help, ,
@c Help, emacs, The GNU Emacs Manual}.
説明文字列の利用に関する情報は、
@ref{Help,, ヘルプ機能, emacs, GNU Emacs マニュアル}を参照してください。

@c @c Wordy to prevent overfull hbox.  --rjc 15mar92
@c   The @file{emacs/lib-src} directory contains two utilities that you can
@c use to print nice-looking hardcopy for the file
@c @file{emacs/etc/DOC-@var{version}}.  These are @file{sorted-doc} and
@c @file{digest-doc}.
ディレクトリ@file{emacs/lib-src}には、
ファイル@file{emacs/etc/DOC-@var{version}}を美しく印刷するための
コマンドが2つあります。
@file{sorted-doc}と@file{digest-doc}です。

@node Accessing Documentation
@c @section Access to Documentation Strings
@section 説明文字列の参照

@defun documentation-property symbol property &optional verbatim
@c This function returns the documentation string that is recorded
@c in @var{symbol}'s property list under property @var{property}.  It
@c retrieves the text from a file if necessary, and runs
@c @code{substitute-command-keys} to substitute actual key bindings.  (This
@c substitution is not done if @var{verbatim} is non-@code{nil}.)
この関数は、シンボル@var{symbol}の属性リストに
属性@var{property}で記録されている説明文字列を返す。
必要ならばファイルからテキストを取り出し、
実際のキーバインディングに置き換えるために
@code{substitute-command-keys}を実行する。
（@var{verbatim}が@code{nil}以外であると、置換を行わない。）

@smallexample
@group
(documentation-property 'command-line-processed
   'variable-documentation)
     @result{} "Non-nil once command line has been processed"
@end group
@group
(symbol-plist 'command-line-processed)
     @result{} (variable-documentation 188902)
@end group
@end smallexample
@end defun

@defun documentation function &optional verbatim
@c This function returns the documentation string of @var{function}.  It
@c reads the text from a file if necessary.  Then (unless @var{verbatim} is
@c non-@code{nil}) it calls @code{substitute-command-keys}, to return a
@c value containing the actual (current) key bindings.
この関数は、関数@var{function}の説明文字列を返す。
必要ならばファイルからテキストを取り出す。
続いて、（@var{verbatim}が@code{nil}ならば）
実際の（現在の）キーバインディングを含んだ値を返すために
@code{substitute-command-keys}を実行する。

@c The function @code{documentation} signals a @code{void-function} error
@c if @var{function} has no function definition.  However, it is OK if
@c the function definition has no documentation string.  In that case,
@c @code{documentation} returns @code{nil}.
関数@code{documentation}は、@var{function}に関数定義がないと
エラー@code{void-function}を通知する。
しかし、関数定義に説明文字列がなくてもエラーではない。
その場合、@code{documentation}は@code{nil}を返す。
@end defun

@c @c Wordy to prevent overfull hboxes.  --rjc 15mar92
@c Here is an example of using the two functions, @code{documentation} and
@c @code{documentation-property}, to display the documentation strings for
@c several symbols in a @samp{*Help*} buffer.
2つの関数@code{documentation}と@code{documentation-property}を用いて、
数個のシンボルの説明文字列をバッファ@samp{*Help*}に表示する例を示します。

@smallexample
@group
(defun describe-symbols (pattern)
  "Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function 
          (lambda (s)
@end group
@group
            ;; @r{Print description of symbol.}
@c             (if (fboundp s)             ; @r{It is a function.}
            (if (fboundp s)             ; @r{これは関数}
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (commandp s) 
                       (let ((keys (where-is-internal s)))
                         (if keys
                             (concat
                              "Keys: "
                              (mapconcat 'key-description 
                                         keys " "))
                           "Keys: none"))
                     "Function")
@end group
@group
                   (or (documentation s) 
                       "not documented"))))
            
@c             (if (boundp s)              ; @r{It is a variable.}
            (if (boundp s)              ; @r{これは変数}
@end group
@group
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (user-variable-p s) 
                       "Option " "Variable")
@end group
@group
                   (or (documentation-property 
                         s 'variable-documentation)
                       "not documented")))))))
        sym-list)
@end group

@group
@c     ;; @r{Build a list of symbols that match pattern.}
    ;; @r{パターンに一致するシンボルのリストを作る}
    (mapatoms (function 
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))
@end group

@group
@c     ;; @r{Display the data.}
    ;; @r{データを表示する}
    (with-output-to-temp-buffer "*Help*"
      (mapcar describe-func (sort sym-list 'string<))
      (print-help-return-message))))
@end group
@end smallexample

@c   The @code{describe-symbols} function works like @code{apropos},
@c but provides more information.
関数@code{describe-symbols}は@code{apropos}のように動作しますが、
より多くの情報を提供します。

@smallexample
@group
(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option 
*Semipermanent goal column for vertical motion, as set by @dots{}
@end group
@c Do not blithely break or fill these lines.
@c That makes them incorrect.

@group
set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
@end group
@c DO NOT put a blank line here!  That is factually inaccurate!
@group
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.
@end group

@group
temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------
@end group
@end smallexample

@defun Snarf-documentation filename
@c This function is used only during Emacs initialization, just before
@c the runnable Emacs is dumped.  It finds the file offsets of the
@c documentation strings stored in the file @var{filename}, and records
@c them in the in-core function definitions and variable property lists in
@c place of the actual strings.  @xref{Building Emacs}.
この関数は、実行可能なEmacsをダンプする直前の
Emacsの初期化処理中にのみ使われる。
ファイル@var{filename}に格納された説明文字列のファイル内位置を探し出し、
それらの情報を実際の文字列のかわりに
メモリ内の関数定義や変数の属性リストに記録する。
@pxref{Building Emacs}。

@c Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
@c When the dumped Emacs is later executed, the same file will be looked
@c for in the directory @code{doc-directory}.  Usually @var{filename} is
@c @code{"DOC-@var{version}"}.
Emacsはファイル@var{filename}をディレクトリ@file{emacs/etc}から読む。
ダンプしたEmacsをのちに実行すると、
同じファイルをディレクトリ@code{doc-directory}で探す。
通常、@var{filename}は@code{"DOC-@var{version}"}である。
@end defun

@c Emacs 19 feature
@defvar doc-directory
@c This variable holds the name of the directory which should contain the
@c file @code{"DOC-@var{version}"} that contains documentation strings for
@c built-in and preloaded functions and variables.
この変数は、組み込みであったりあらかじめロード済みの関数や変数の
説明文字列を収めたファイル@code{"DOC-@var{version}"}を置いた
ディレクトリの名前を保持する。

@c In most cases, this is the same as @code{data-directory}.  They may be
@c different when you run Emacs from the directory where you built it,
@c without actually installing it.  See @code{data-directory} in @ref{Help
@c Functions}.
ほとんどの場合、これは@code{data-directory}と同じである。
Emacsをインストールせずに構築したディレクトリから起動すると、
それらは異なることがある。
@ref{Help Functions}の@code{data-directory}を参照。

@c In older Emacs versions, @code{exec-directory} was used for this.
Emacsの古い版では、この目的には@code{exec-directory}を用いていた。
@end defvar

@node Keys in Documentation
@c @section Substituting Key Bindings in Documentation
@section 説明文内のキーバインディングの置換
@c @cindex documentation, keys in
@c @cindex keys in documentation strings
@c @cindex substituting keys in documentation
@cindex 説明文、キー
@cindex 説明文字列内のキー
@cindex キー、説明文字列
@cindex 説明文内のキーの置換

@c   When documentation strings refer to key sequences, they should use the
@c current, actual key bindings.  They can do so using certain special text
@c sequences described below.  Accessing documentation strings in the usual
@c way substitutes current key binding information for these special
@c sequences.  This works by calling @code{substitute-command-keys}.  You
@c can also call that function yourself.
説明文字列からキー列を参照するときには、
現在の活性なキーバインディングを使うべきです。
これは以下に述べる特別なテキスト列でできます。
普通の方法で説明文字列を参照すると、
これらの特別な列は現在のキーバインディング情報で置き換えられます。
置き換えは@code{substitute-command-keys}を呼び出して行います。
読者自身がこの関数を使うこともできます。

@c   Here is a list of the special sequences and what they mean:
特別な列とその意味を以下にあげます。

@table @code
@item \[@var{command}]
@c stands for a key sequence that will invoke @var{command}, or @samp{M-x
@c @var{command}} if @var{command} has no key bindings.
コマンド@var{command}を起動するキー列を表す。
@var{command}にキーバインディングがなければ、
@samp{M-x @var{command}}を表す。

@item \@{@var{mapvar}@} 
@c stands for a summary of the keymap which is the value of the variable
@c @var{mapvar}.  The summary is made using @code{describe-bindings}.
変数@var{mapvar}の値であるキーマップの概要を表す。
この概要は@code{describe-bindings}を使って作成する。

@item \<@var{mapvar}> 
@c stands for no text itself.  It is used only for a side effect: it
@c specifies @var{mapvar}'s value as the keymap for any following
@c @samp{\[@var{command}]} sequences in this documentation string.
空テキストを表す。
副作用のためだけに使う。
つまり、この説明文字列内のこれ以降にある列@samp{\[@var{command}]}に
対するキーマップとして@var{mapvar}の値を指定する。

@item \=
@c quotes the following character and is discarded; thus, @samp{\=\[} puts
@c @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
@c output.
後続の文字をクォートし@samp{\=}は破棄する。
したがって、@samp{\=\[}は@samp{\[}という出力になり、
@samp{\=\=}は@samp{\=}という出力になる。
@end table

@c @strong{Please note:} Each @samp{\} must be doubled when written in a
@c string in Emacs Lisp.
@strong{注意：}@code{ }
Emacs Lispでは、文字列内の@samp{\}は、2つ続けて書くこと。

@defun substitute-command-keys string
@c This function scans @var{string} for the above special sequences and
@c replaces them by what they stand for, returning the result as a string.
@c This permits display of documentation that refers accurately to the
@c user's own customized key bindings.
この関数は、@var{string}から上記の特別な列を探し、
それらをそれらが意味するものに置き換え、結果を文字列で返す。
これにより、説明文の表示では、
ユーザー独自のカスタマイズしたキーバインディングを実際に参照できる。
@end defun

@c   Here are examples of the special sequences:
特別な列の例を示します。

@smallexample
@group
(substitute-command-keys 
   "To abort recursive edit, type: \\[abort-recursive-edit]")
@result{} "To abort recursive edit, type: C-]"
@end group

@group
(substitute-command-keys 
   "The keys that are defined for the minibuffer here are:
  \\@{minibuffer-local-must-match-map@}")
@result{} "The keys that are defined for the minibuffer here are:
@end group

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

@group
(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
@result{} "To abort a recursive edit from the minibuffer, type C-g."
@end group
@end smallexample

@node Describing Characters
@c @section Describing Characters for Help Messages
@section ヘルプメッセージ用の文字変換

@c   These functions convert events, key sequences, or characters to
@c textual descriptions.  These descriptions are useful for including
@c arbitrary text characters or key sequences in messages, because they
@c convert non-printing and whitespace characters to sequences of printing
@c characters.  The description of a non-whitespace printing character is
@c the character itself.
これらの関数は、イベント、キー列、文字をテキスト表記に変換します。
これらの表記は、メッセージに文字やキー列をテキストとして含めるのに有用です。
というのは、非印字文字や白文字を印字文字の列に変換するからです。
白文字でない印字文字は文字そのもので表記します。

@defun key-description sequence
@c @cindex Emacs event standard notation
@cindex Emacsのイベント標準表記
@c This function returns a string containing the Emacs standard notation
@c for the input events in @var{sequence}.  The argument @var{sequence} may
@c be a string, vector or list.  @xref{Input Events}, for more information
@c about valid events.  See also the examples for
@c @code{single-key-description}, below.
この関数は、@var{sequence}の入力イベントに対する
Emacsの標準表記を含んだ文字列を返す。
引数@var{sequence}は、文字列、ベクトル、リストである。
正しいイベントについて詳しくは@pxref{Input Events}。
下記の@code{single-key-description}の例を参照。
@end defun

@defun single-key-description event
@c @cindex event printing
@c @cindex character printing
@c @cindex control character printing
@c @cindex meta character printing
@cindex イベントの表示
@cindex 文字の表示
@cindex コントロール文字の表示
@cindex メタ文字の表示
@c This function returns a string describing @var{event} in the standard
@c Emacs notation for keyboard input.  A normal printing character appears
@c as itself, but a control character turns into a string starting with
@c @samp{C-}, a meta character turns into a string starting with @samp{M-},
@c and space, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc.  A
@c function key symbol appears as itself.  An event that is a list appears
@c as the name of the symbol in the @sc{car} of the list.
この関数は、@var{event}をキーボード入力向けのEmacsの標準表記で
表した文字列を返す。
普通の印字文字はそのまま現れるが、
コントロール文字は@samp{C-}で始まる文字列に、
メタ文字は@samp{M-}で始まる文字列に、
空白、タブなどは、@samp{SPC}、@samp{TAB}などとなる。
ファンクションキーのシンボルはそれ自身が現れる。
リストであるイベントはリストの@sc{car}のシンボルの名前が現れる。

@smallexample
@group
(single-key-description ?\C-x)
     @result{} "C-x"
@end group
@group
(key-description "\C-x \M-y \n \t \r \f123")
     @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
@end group
@group
(single-key-description 'C-mouse-1)
     @result{} "C-mouse-1"
@end group
@end smallexample
@end defun

@defun text-char-description character
@c This function returns a string describing @var{character} in the
@c standard Emacs notation for characters that appear in text---like
@c @code{single-key-description}, except that control characters are
@c represented with a leading caret (which is how control characters in
@c Emacs buffers are usually displayed).
この関数は、@var{character}を
テキストに現れる文字向けのEmacsの標準表記で表した文字列を返す。
@code{single-key-description}に似ているが、
コントロール文字は、始めにカレットを付けて表現する点が異なる
（Emacsのバッファでは、コントロールは普通このように表示される）。

@smallexample
@group
(text-char-description ?\C-c)
     @result{} "^C"
@end group
@group
(text-char-description ?\M-m)
     @result{} "M-m"
@end group
@group
(text-char-description ?\C-\M-m)
     @result{} "M-^M"
@end group
@end smallexample
@end defun

@defun read-kbd-macro string
@c This function is used mainly for operating on keyboard macros, but it
@c can also be used as a rough inverse for @code{key-description}.  You
@c call it with a string containing key descriptions, separated by spaces;
@c it returns a string or vector containing the corresponding events.
@c (This may or may not be a single valid key sequence, depending on what
@c events you use; @pxref{Keymap Terminology}.)
この関数は、キーボードマクロの処理に主に使われるが、
@code{key-description}に対するおおまかな逆変換にも使える。
空白で区切ったキーの表記を収めた文字列で、この関数を呼び出す。
対応するイベントを収めた文字列かベクトルを返す。
（指定したイベントに依存して、正しい単一のキー列であったりなかったりする。
@pxref{Keymap Terminology}。）
@end defun

@node Help Functions
@c @section Help Functions
@section ヘルプ機能

@c   Emacs provides a variety of on-line help functions, all accessible to
@c the user as subcommands of the prefix @kbd{C-h}.  For more information
@c about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}.  Here
@c we describe some program-level interfaces to the same information.
Emacsにはさまざまオンラインヘルプ関数があり、
それらはすべてプレフィックス@kbd{C-h}のサブコマンドとして使えます。
それらについて詳しくは、
@ref{Help,, ヘルプ機能, emacs, GNU Emacs マニュアル}を参照してください。
ここでは、同じ情報を得るプログラムレベルのインターフェイスを説明します。

@c @deffn Command apropos regexp &optional do-all
@deffn コマンド apropos regexp &optional do-all
@c This function finds all symbols whose names contain a match for the
@c regular expression @var{regexp}, and returns a list of them
@c (@pxref{Regular Expressions}).  It also displays the symbols in a buffer
@c named @samp{*Help*}, each with a one-line description taken from the
@c beginning of its documentation string.
この関数は、正規表現@var{regexp}に一致する名前を持つすべてのシンボルを探し、
それらのリストを返す（@pxref{Regular Expressions}）。
さらに、バッファ@samp{*Help*}に、各シンボルについて、
シンボルとその説明文字列の始めの部分から取り出した1行の説明文を表示する。

@c @c Emacs 19 feature
@c If @var{do-all} is non-@code{nil}, then @code{apropos} also shows key
@c bindings for the functions that are found; it also shows all symbols,
@c even those that are neither functions nor variables.
@var{do-all}が@code{nil}以外であると、
@code{apropos}は、みつけた関数に対するキーバインディングも表示する。
さらに、関数や変数以外も含めてすべてのシンボルを表示する。

@c In the first of the following examples, @code{apropos} finds all the
@c symbols with names containing @samp{exec}.  (We don't show here the
@c output that results in the @samp{*Help*} buffer.)
つぎの例では、@code{apropos}は、
@samp{exec}を名前に含むすべてのシンボルを探しだす。
（ここではバッファ@samp{*Help*}の表示は示さない。）

@smallexample
@group
(apropos "exec")
     @result{} (Buffer-menu-execute command-execute exec-directory
    exec-path execute-extended-command execute-kbd-macro
    executing-kbd-macro executing-macro)
@end group
@end smallexample
@end deffn

@defvar help-map
@c The value of this variable is a local keymap for characters following the
@c Help key, @kbd{C-h}.
この変数の値は、ヘルプキー@kbd{C-h}に続く文字向けのローカルキーマップである。
@end defvar

@c @deffn {Prefix Command} help-command
@deffn {プレフィックスコマンド} help-command
@c This symbol is not a function; its function definition cell holds the
@c keymap known as @code{help-map}.  It is defined in @file{help.el} as
@c follows:
このシンボルは関数ではない。
その関数定義セルは、@code{help-map}として知られるキーマップを保持している。
@file{help.el}での定義はつぎのとおりである。

@smallexample
@group
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
@end group
@end smallexample
@end deffn

@defun print-help-return-message &optional function
@c This function builds a string that explains how to restore the previous
@c state of the windows after a help command.  After building the message,
@c it applies @var{function} to it if @var{function} is non-@code{nil}.
@c Otherwise it calls @code{message} to display it in the echo area.
この関数は、ヘルプコマンドのあとでそれ以前のウィンドウの状態に復元する
方法を述べた文字列を作成する。
メッセージを作成後、@var{function}が@code{nil}以外であれば、
メッセージを@var{function}に適用する。
さもなければ、メッセージをエコー領域に表示するために@code{message}を呼び出す。

@c This function expects to be called inside a
@c @code{with-output-to-temp-buffer} special form, and expects
@c @code{standard-output} to have the value bound by that special form.
@c For an example of its use, see the long example in @ref{Accessing
@c Documentation}.
この関数は、スペシャルフォーム@code{with-output-to-temp-buffer}の
中から呼び出され、しかも、
当該スペシャルフォームで@code{standard-output}に値が束縛されているものと
仮定する。
使用例については、@ref{Accessing Documentation}の長い例を参照。
@end defun

@defvar help-char
@c The value of this variable is the help character---the character that
@c Emacs recognizes as meaning Help.  By default, its value is 8, which
@c stands for @kbd{C-h}.  When Emacs reads this character, if
@c @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
@c expression, and displays the result in a window if it is a string.
この変数の値はヘルプ文字、つまり、
Emacsがヘルプを意味すると認識する文字である。
デフォルトでは、その値は@kbd{C-h}を表す8である。
@code{help-form}が@code{nil}以外のLisp式であると、
Emacsがこの文字を読み取るとその式を評価し、
その結果が文字列であれば結果をウィンドウに表示する。

@c Usually the value of @code{help-form} is @code{nil}.  Then the
@c help character has no special meaning at the level of command input, and
@c it becomes part of a key sequence in the normal way.  The standard key
@c binding of @kbd{C-h} is a prefix key for several general-purpose help
@c features.
通常、@code{help-form}の値は@code{nil}である。
そうすると、ヘルプ文字にはコマンド入力のレベルでは特別な意味はなく、
普通の意味でのキー列の一部になる。
@kbd{C-h}の標準のキーバインディングは、
いくつかの汎用目的のヘルプ機能向けのプレフィックスキーである。

@c The help character is special after prefix keys, too.  If it has no
@c binding as a subcommand of the prefix key, it runs
@c @code{describe-prefix-bindings}, which displays a list of all the
@c subcommands of the prefix key.
ヘルプ文字は、プレフィックスキーのうしろでも特別である。
プレフィックスのサブコマンドとしてのバインディングがないと、
プレフィックスキーのすべてのサブコマンドの一覧を表示する
@code{describe-prefix-bindings}を実行する。
@end defvar

@defvar help-event-list
@tindex help-event-list
@c The value of this variable is a list of event types that serve as
@c alternative ``help characters.''  These events are handled just like the
@c event specified by @code{help-char}.
この変数の値は、別の『ヘルプ文字』として動作するイベント型のリストである。
これらのイベントは@code{help-char}で指定されたイベントと
まったく同様に扱われる。
@end defvar

@defvar help-form
@c If this variable is non-@code{nil}, its value is a form to evaluate
@c whenever the character @code{help-char} is read.  If evaluating the form
@c produces a string, that string is displayed.
この変数が@code{nil}以外であると、その値は、
@code{help-char}を読むたびに評価すべきフォームである。
フォームを評価すると文字列を生成すれば、その文字列が表示される。

@c A command that calls @code{read-event} or @code{read-char} probably
@c should bind @code{help-form} to a non-@code{nil} expression while it
@c does input.  (The time when you should not do this is when @kbd{C-h} has
@c some other meaning.)  Evaluating this expression should result in a
@c string that explains what the input is for and how to enter it properly.
@code{read-event}や@code{read-char}を呼ぶコマンドは、
入力中には@code{help-form}を@code{nil}以外に（たぶん）束縛すべきである。
（@kbd{C-h}に別の意味がある場合には、こうしないこと。）
この式の評価結果は、なんのための入力でどのように入力すべきかを
説明する文字列であること。

@c Entry to the minibuffer binds this variable to the value of
@c @code{minibuffer-help-form} (@pxref{Minibuffer Misc}).
ミニバッファに入ると、この変数は@code{minibuffer-help-form}
（@pxref{Minibuffer Misc}）の値に束縛される。
@end defvar

@defvar prefix-help-command
@c This variable holds a function to print help for a prefix key.  The
@c function is called when the user types a prefix key followed by the help
@c character, and the help character has no binding after that prefix.  The
@c variable's default value is @code{describe-prefix-bindings}.
この変数はプレフィックスキーに対するヘルプを表示する関数を保持する。
ユーザーがプレフィックスキーに続けてヘルプ文字や
当該プレフィックスのあとではバインディングを持たない文字を打つと
その関数が呼ばれる。
この変数のデフォルト値は@code{describe-prefix-bindings}である。
@end defvar

@defun describe-prefix-bindings
@c This function calls @code{describe-bindings} to display a list of all
@c the subcommands of the prefix key of the most recent key sequence.  The
@c prefix described consists of all but the last event of that key
@c sequence.  (The last event is, presumably, the help character.)
この関数は、もっとも最近のキー列のプレフィックスキーの
すべてのサブコマンドの一覧を表示するために@code{describe-bindings}を呼び出す。
プレフィックスの説明には、当該キー列の最後のイベント以外のすべてが含まれる。
（最後のイベントはヘルプ文字であると仮定する。）
@end defun

@c   The following two functions are meant for modes that want to provide
@c help without relinquishing control, such as the ``electric'' modes.
@c Their names begin with @samp{Helper} to distinguish them from the
@c ordinary help functions.
つぎの2つの関数は、『エレクトリック』モードのように
制御を放棄せずにヘルプを提供したいモードのためです。
それらの名前は、普通のヘルプ関数と区別するために@samp{Helper}で始まります。

@c @deffn Command Helper-describe-bindings
@deffn コマンド Helper-describe-bindings
@c This command pops up a window displaying a help buffer containing a
@c listing of all of the key bindings from both the local and global keymaps.
@c It works by calling @code{describe-bindings}.
このコマンドは、ローカルキーマップとグローバルキーマップの両者の
すべてのキーバインディングの一覧を収めたヘルプバッファを表示した
ウィンドウをポップアップする。
@code{describe-bindings}を呼び出すことで動作する。
@end deffn

@c @deffn Command Helper-help
@deffn コマンド Helper-help
@c This command provides help for the current mode.  It prompts the user
@c in the minibuffer with the message @samp{Help (Type ? for further
@c options)}, and then provides assistance in finding out what the key
@c bindings are, and what the mode is intended for.  It returns @code{nil}.
このコマンドはカレントモードについてのヘルプを提供する。
ミニバッファにおいて@samp{Help (Type ? for further options)}のメッセージで
ユーザーに問い合わせ、キーバインディングの意味やモードの目的を
調べることを補佐する。
@code{nil}を返す。

@c This can be customized by changing the map @code{Helper-help-map}.
このコマンドは、キーマップ@code{Helper-help-map}を
変更することでカスタマイズできる。
@end deffn

@c Emacs 19 feature
@defvar data-directory
@c This variable holds the name of the directory in which Emacs finds
@c certain documentation and text files that come with Emacs.  In older
@c Emacs versions, @code{exec-directory} was used for this.
この変数は、Emacsとともに配布された特定の説明文やテキストファイルを
Emacsが探すためのディレクトリの名前を保持する。
Emacsの古い版では、この目的には@code{exec-directory}を用いていた。
@end defvar

@c Emacs 19 feature
@defmac make-help-screen fname help-line help-text help-map
@c This macro defines a help command named @var{fname} that acts like a 
@c prefix key that shows a list of the subcommands it offers.
このマクロは、サブコマンドの一覧を表示するプレフィックスキーのように
動作する@var{fname}という名前のコマンドのヘルプを定義する。

@c When invoked, @var{fname} displays @var{help-text} in a window, then
@c reads and executes a key sequence according to @var{help-map}.  The
@c string @var{help-text} should describe the bindings available in
@c @var{help-map}.
起動されると、@var{fname}はウィンドウに@var{help-text}を表示し、
@var{help-map}に従ってキー列を読み実行する。
文字列@var{help-text}は、@var{help-map}が提供する
バインディングを記述するべきである。

@c The command @var{fname} is defined to handle a few events itself, by
@c scrolling the display of @var{help-text}.  When @var{fname} reads one of
@c those special events, it does the scrolling and then reads another
@c event.  When it reads an event that is not one of those few, and which
@c has a binding in @var{help-map}, it executes that key's binding and
@c then returns.
コマンド@var{fname}は、@var{help-text}の表示をスクロールすることで、
それ自身では少数のイベントを扱うように定義される。
@var{fname}がそれらの特殊イベントの1つを読み取ると、
スクロールしてつぎのイベントを読み取る。
読み取ったイベントが、扱えるものでなく、
@var{help-map}にバインディングがあれば、
当該キーのバインディングを実行して戻る。

@c The argument @var{help-line} should be a single-line summary of the
@c alternatives in @var{help-map}.  In the current version of Emacs, this
@c argument is used only if you set the option @code{three-step-help} to
@c @code{t}.
@var{help-line}は、@var{help-map}内の選択項目を1行にまとめたものであること。
Emacsの現在の版では、この引数はオプション@code{three-step-help}を@code{t}に
設定してある場合にのみ使われる。

@c This macro is used in the command @code{help-for-help} which is the
@c binding of @kbd{C-h C-h}.
このマクロは、@kbd{C-h C-h}のバインディングである
コマンド@code{help-for-help}で使われている。
@end defmac

@defopt three-step-help
@c If this variable is non-@code{nil}, commands defined with
@c @code{make-help-screen} display their @var{help-line} strings in the
@c echo area at first, and display the longer @var{help-text} strings only
@c if the user types the help character again.
この変数が@code{nil}以外であると、
@code{make-help-screen}で定義されたコマンドは、
まず文字列@var{help-line}をエコー領域に表示し、
ユーザーがヘルプ文字を再度打った場合にのみより長い文字列を表示する。
@end defopt