-@c -*-texinfo-*-
+@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Documentation
@chapter Documentation
GNU Emacs has convenient built-in help facilities, most of which
derive their information from documentation strings associated with
functions and variables. This chapter describes how to access
-documentation strings in Lisp programs. @xref{Documentation Tips},
-for how to write good documentation strings.
+documentation strings in Lisp programs.
+
+ The contents of a documentation string should follow certain
+conventions. In particular, its first line should be a complete
+sentence (or two complete sentences) that briefly describes what the
+function or variable does. @xref{Documentation Tips}, for how to
+write good documentation strings.
Note that the documentation strings for Emacs are not the same thing
as the Emacs manual. Manuals have their own source files, written in
@cindex string, writing a doc string
A documentation string is written using the Lisp syntax for strings,
-with double-quote characters surrounding the text of the string. This
-is because it really is a Lisp string object. The string serves as
-documentation when it is written in the proper place in the definition
-of a function or variable. In a function definition, the documentation
-string follows the argument list. In a variable definition, the
-documentation string follows the initial value of the variable.
-
- When you write a documentation string, make the first line a
-complete sentence (or two complete sentences) that briefly describes
-what the function or variable does. Some commands, such as
-@code{apropos}, show only the first line of a multi-line documentation
-string. Also, you should not indent the second line of a
-documentation string, if it has one, because that looks odd when you
-use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
-(@code{describe-variable}) to view the documentation string. There
-are many other conventions for documentation strings; see
-@ref{Documentation Tips}.
-
- Documentation strings can contain several special substrings, which
-stand for key bindings to be looked up in the current keymaps when the
-documentation is displayed. This allows documentation strings to refer
-to the keys for related commands and be accurate even when a user
-rearranges the key bindings. (@xref{Keys in Documentation}.)
-
-@vindex emacs-lisp-docstring-fill-column
- Emacs Lisp mode fills documentation strings to the width
-specified by @code{emacs-lisp-docstring-fill-column}.
-
- Exactly where a documentation string is stored depends on how its
-function or variable was defined or loaded into memory:
-
-@itemize @bullet
-@item
-@kindex function-documentation
-When you define a function (@pxref{Lambda Expressions}, and
-@pxref{Function Documentation}), the documentation string is stored in
-the function definition itself. You can also put function
-documentation in the @code{function-documentation} property of a
-function name. That is useful for function definitions which can't
-hold a documentation string, such as keyboard macros.
-
-@item
-@kindex variable-documentation
-When you define a variable with a @code{defvar} or related form
-(@pxref{Defining Variables}), the documentation is stored in the
-variable's @code{variable-documentation} property.
-
-@cindex @file{DOC-@var{version}} (documentation) file
-@item
-To save memory, the documentation for preloaded functions and
-variables (including primitive functions and autoloaded functions) is
-not kept in memory, but in the file
-@file{emacs/etc/DOC-@var{version}}, where @var{version} is the Emacs
-version number (@pxref{Version Info}).
-
-@item
-When a function or variable is loaded from a byte-compiled file during
-the Emacs session, its documentation string is not loaded into memory.
-Instead, Emacs looks it up in the byte-compiled file as needed.
-@xref{Docs and Compilation}.
-@end itemize
-
-@noindent
-Regardless of where the documentation string is stored, you can
-retrieve it using the @code{documentation} or
-@code{documentation-property} function, described in the next section.
+with double-quote characters surrounding the text. It is, in fact, an
+actual Lisp string. When the string appears in the proper place in a
+function or variable definition, it serves as the function's or
+variable's documentation.
+
+@cindex @code{function-documentation} property
+ In a function definition (a @code{lambda} or @code{defun} form), the
+documentation string is specified after the argument list, and is
+normally stored directly in the function object. @xref{Function
+Documentation}. You can also put function documentation in the
+@code{function-documentation} property of a function name
+(@pxref{Accessing Documentation}).
+
+@cindex @code{variable-documentation} property
+ In a variable definition (a @code{defvar} form), the documentation
+string is specified after the initial value. @xref{Defining
+Variables}. The string is stored in the variable's
+@code{variable-documentation} property.
+
+@cindex @file{DOC} (documentation) file
+ Sometimes, Emacs does not keep documentation strings in memory.
+There are two such circumstances. Firstly, to save memory, the
+documentation for preloaded functions and variables (including
+primitives) is kept in a file named @file{DOC}, in the directory
+specified by @code{doc-directory} (@pxref{Accessing Documentation}).
+Secondly, when a function or variable is loaded from a byte-compiled
+file, Emacs avoids loading its documentation string (@pxref{Docs and
+Compilation}). In both cases, Emacs looks up the documentation string
+from the file only when needed, such as when the user calls @kbd{C-h
+f} (@code{describe-function}) for a function.
+
+ Documentation strings can contain special @dfn{key substitution
+sequences}, referring to key bindings which are looked up only when
+the user views the documentation. This allows the help commands to
+display the correct keys even if a user rearranges the default key
+bindings. @xref{Keys in Documentation}.
+
+ In the documentation string of an autoloaded command
+(@pxref{Autoload}), these key-substitution sequences have an
+additional special effect: they cause @kbd{C-h f} on the command to
+trigger autoloading. (This is needed for correctly setting up the
+hyperlinks in the @file{*Help*} buffer.)
@node Accessing Documentation
@section Access to Documentation Strings
+@cindex accessing documentation strings
@defun documentation-property symbol property &optional verbatim
This function returns the documentation string recorded in
which @var{property} is @code{variable-documentation}. However, it
can also be used to look up other kinds of documentation, such as for
customization groups (but for function documentation, use the
-@code{documentation} command, below).
+@code{documentation} function, below).
+
+If the property value refers to a documentation string stored in the
+@file{DOC} file or a byte-compiled file, this function looks up that
+string and returns it.
-If the value recorded in the property list refers to a documentation
-string stored in a @file{DOC-@var{version}} file or a byte-compiled
-file, it looks up that string and returns it. If the property value
-isn't @code{nil}, isn't a string, and doesn't refer to text in a file,
-then it is evaluated as a Lisp expression to obtain a string.
+If the property value isn't @code{nil}, isn't a string, and doesn't
+refer to text in a file, then it is evaluated as a Lisp expression to
+obtain a string.
-The last thing this function does is pass the string through
-@code{substitute-command-keys} to substitute actual key bindings
-(@pxref{Keys in Documentation}). However, it skips this step if
-@var{verbatim} is non-@code{nil}.
+Finally, this function passes the string through
+@code{substitute-command-keys} to substitute key bindings (@pxref{Keys
+in Documentation}). It skips this step if @var{verbatim} is
+non-@code{nil}.
@smallexample
@group
If @var{function} is a symbol, this function first looks for the
@code{function-documentation} property of that symbol; if that has a
non-@code{nil} value, the documentation comes from that value (if the
-value is not a string, it is evaluated). If @var{function} is not a
-symbol, or if it has no @code{function-documentation} property, then
-@code{documentation} extracts the documentation string from the actual
-function definition, reading it from a file if called for.
+value is not a string, it is evaluated).
-Finally, unless @var{verbatim} is non-@code{nil}, it calls
-@code{substitute-command-keys} so as to return a value containing the
-actual (current) key bindings.
+If @var{function} is not a symbol, or if it has no
+@code{function-documentation} property, then @code{documentation}
+extracts the documentation string from the actual function definition,
+reading it from a file if called for.
-The function @code{documentation} signals a @code{void-function} error
+Finally, unless @var{verbatim} is non-@code{nil}, this function calls
+@code{substitute-command-keys}. The result is the documentation
+string to return.
+
+The @code{documentation} function signals a @code{void-function} error
if @var{function} has no function definition. However, it is OK if
the function definition has no documentation string. In that case,
@code{documentation} returns @code{nil}.
face.
@end defun
-@c Wordy to prevent overfull hboxes. --rjc 15mar92
Here is an example of using the two functions, @code{documentation} and
@code{documentation-property}, to display the documentation strings for
several symbols in a @file{*Help*} buffer.
(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."
+in the *Help* buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
(function
@c Do not blithely break or fill these lines.
@c That makes them incorrect.
+@group
+minibuffer-temporary-goal-position Variable
+not documented
+@end group
+
@group
set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
@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
+With a non-nil argument ARG, 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'.
+The goal column is stored in the variable ‘goal-column’.
+
+(fn ARG)
@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.
+It is the column where point was at the start of the current run
+of vertical motion commands.
+
+When moving by visual lines via the function ‘line-move-visual’, it is a cons
+cell (COL . HSCROLL), where COL is the x-position, in pixels,
+divided by the default column width, and HSCROLL is the number of
+columns by which window is scrolled from left margin.
+
+When the ‘track-eol’ feature is doing its job, the value is
+‘most-positive-fixnum’.
---------- Buffer: *Help* ----------
@end group
@end smallexample
Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file will be looked
for in the directory @code{doc-directory}. Usually @var{filename} is
-@code{"DOC-@var{version}"}.
+@code{"DOC"}.
@end defun
@defvar doc-directory
This variable holds the name of the directory which should contain the
-file @code{"DOC-@var{version}"} that contains documentation strings for
+file @code{"DOC"} that contains documentation strings for
built-in and preloaded functions and variables.
In most cases, this is the same as @code{data-directory}. They may be
@cindex documentation, keys in
@cindex keys in documentation strings
@cindex substituting keys in documentation
+@cindex key substitution sequence
When documentation strings refer to key sequences, they should use the
current, actual key bindings. They can do so using certain special text
specifies @var{mapvar}'s value as the keymap for any following
@samp{\[@var{command}]} sequences in this documentation string.
+@item ‘
+@itemx `
+(left single quotation mark and grave accent) both stand for a left quote.
+
+@item ’
+@itemx '
+(right single quotation mark and apostrophe) both stand for a right quote.
+
@item \=
-quotes the following character and is discarded; thus, @samp{\=\[} puts
-@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
-output.
+quotes the following character and is discarded; thus, @samp{\=`} puts
+@samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output,
+and @samp{\=\=} puts @samp{\=} into the output.
@end table
@strong{Please note:} Each @samp{\} must be doubled when written in a
string in Emacs Lisp.
+@defvar text-quoting-style
+@cindex curved quotes
+@cindex curly quotes
+The value of this variable is a symbol that specifies the style Emacs
+should use for single quotes in the wording of help and messages.
+If the variable's value is @code{curve}, the style is
+@t{‘like this’} with curved single quotes. If the value is
+@code{straight}, the style is @t{'like this'} with straight
+apostrophes. If the value is @code{grave}, the style is @t{`like
+this'} with grave accent and apostrophe, the standard style
+before Emacs version 25. The default value @code{nil}
+acts like @code{curve} if curved single quotes are displayable, and
+like @code{grave} otherwise.
+@end defvar
+
@defun substitute-command-keys string
This function scans @var{string} for the above special sequences and
replaces them by what they stand for, returning the result as a string.
@smallexample
@group
(substitute-command-keys
- "To abort recursive edit, type: \\[abort-recursive-edit]")
-@result{} "To abort recursive edit, type: C-]"
+ "To abort recursive edit, type `\\[abort-recursive-edit]'.")
+@result{} "To abort recursive edit, type ‘C-]’."
@end group
@group
@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."
+ "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
Emacs notation for keyboard input. A normal printing character
appears as itself, but a control character turns into a string
starting with @samp{C-}, a meta character turns into a string starting
-with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
+with @samp{M-}, and space, tab, etc., appear as @samp{SPC},
@samp{TAB}, etc. A function key symbol appears inside angle brackets
@samp{<@dots{}>}. An event that is a list appears as the name of the
symbol in the @sc{car} of the list, inside angle brackets.
@node Help Functions
@section Help Functions
+@cindex help functions
- Emacs provides a variety of on-line help functions, all accessible to
+ Emacs provides a variety of built-in help functions, all accessible to
the user as subcommands of the prefix @kbd{C-h}. For more information
about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
we describe some program-level interfaces to the same information.
@deffn Command apropos pattern &optional do-all
-This function finds all ``meaningful'' symbols whose names contain a
+This function finds all meaningful symbols whose names contain a
match for the apropos pattern @var{pattern}. An apropos pattern is
either a word to match, a space-separated list of words of which at
least two must match, or a regular expression (if any special regular
-expression characters occur). A symbol is ``meaningful'' if it has a
+expression characters occur). A symbol is meaningful if it has a
definition as a function, variable, or face, or has properties.
The function returns a list of elements that look like this:
@defopt help-event-list
The value of this variable is a list of event types that serve as
-alternative ``help characters''. These events are handled just like the
+alternative help characters. These events are handled just like the
event specified by @code{help-char}.
@end defopt
@end deffn
The following two functions are meant for modes that want to provide
-help without relinquishing control, such as the ``electric'' modes.
+help without relinquishing control, such as the electric modes.
Their names begin with @samp{Helper} to distinguish them from the
ordinary help functions.
@file{*Help*}; if such a buffer does not exist, it is first created.
@end defun
+@vindex help-window-select
@defmac with-help-window buffer-name body@dots{}
-This macro evaluates the @var{body} forms, inserting any output they
-produce into a buffer named @var{buffer-name} like
-@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}).
-(Usually, @var{buffer-name} should be the value returned by the
-function @code{help-buffer}.) It also puts the specified buffer into
-Help mode and displays a message telling the user how to quit and
-scroll the help window.
+This macro evaluates @var{body} like @code{with-output-to-temp-buffer}
+(@pxref{Temporary Displays}), inserting any output produced by its forms
+into a buffer named @var{buffer-name}. (Usually, @var{buffer-name}
+should be the value returned by the function @code{help-buffer}.) It
+also puts the specified buffer into Help mode and displays a message
+telling the user how to quit and scroll the help window. It selects the
+help window if the current value of the user option
+@code{help-window-select} has been set accordingly. It returns the last
+value in @var{body}.
@end defmac
@defun help-setup-xref item interactive-p
echo area at first, and display the longer @var{help-text} strings only
if the user types the help character again.
@end defopt
-