Update copyright year to 2016

[gnu-emacs] / doc / lispref / help.texi

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 1375a057a5a6161f9251d90c7574426752b88195..0b8182c521abc6848232a46456889c59f2cdbe1b 100644 (file)
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -1,7 +1,7 @@
-@c -*-texinfo-*-
+@c -*- mode: texinfo; coding: utf-8 -*-

 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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
 @c See the file elisp.texi for copying conditions.
 @node Documentation
 @chapter Documentation


@@ -10,8 +10,13 @@
   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
   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
 
   Note that the documentation strings for Emacs are not the same thing
 as the Emacs manual.  Manuals have their own source files, written in


@@ -40,81 +45,52 @@ Help, emacs, The GNU Emacs Manual}.
 @cindex string, writing a doc string
 
   A documentation string is written using the Lisp syntax for strings,
 @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 text sequences,
-referring to key bindings which are looked up in the current keymaps
-when the user views the documentation.  This allows the help commands
-to display the correct keys even if a user rearranges the default key
+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
 bindings.  @xref{Keys in Documentation}.
 
   In the documentation string of an autoloaded command

-(@pxref{Autoload}), these special text sequences have an additional
-special effect: they cause @kbd{C-h f} (@code{describe-function}) on
-the command to trigger autoloading.  (This is needed for correctly
-setting up the hyperlinks in the @file{*Help*} buffer).
-
-@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.
+(@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
 
 @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
 
 @defun documentation-property symbol property &optional verbatim
 This function returns the documentation string recorded in


@@ -123,18 +99,20 @@ most often used to look up the documentation strings of variables, for
 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
 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
 
 @smallexample
 @group


@@ -161,16 +139,18 @@ ordinary functions.
 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
 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}.
 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}.


@@ -181,7 +161,6 @@ This function returns the documentation string of @var{face} as a
 face.
 @end defun
 
 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.
 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.


@@ -192,7 +171,7 @@ 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
 (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
   (interactive "sDescribe symbols matching: ")
   (let ((describe-func
          (function


@@ -262,6 +241,11 @@ Semipermanent goal column for vertical motion, as set by @dots{}
 @c Do not blithely break or fill these lines.
 @c That makes them incorrect.
 
 @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
 set-goal-column Keys: C-x C-n
 Set the current horizontal position as a goal for C-n and C-p.


@@ -270,17 +254,26 @@ 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.
 @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.
 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.
 @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
 ---------- Buffer: *Help* ----------
 @end group
 @end smallexample


@@ -296,12 +289,12 @@ memory in the function definitions and variable property lists.
 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
 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
 @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
 built-in and preloaded functions and variables.
 
 In most cases, this is the same as @code{data-directory}.  They may be


@@ -314,6 +307,7 @@ without actually installing it.  @xref{Definition of data-directory}.
 @cindex documentation, keys in
 @cindex keys in documentation strings
 @cindex substituting keys in documentation
 @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
 
   When documentation strings refer to key sequences, they should use the
 current, actual key bindings.  They can do so using certain special text


@@ -338,15 +332,38 @@ stands for no text itself.  It is used only for a side effect: it
 specifies @var{mapvar}'s value as the keymap for any following
 @samp{\[@var{command}]} sequences in this documentation string.
 
 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 \=
 @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.
 
 @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.
 @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.


@@ -374,8 +391,8 @@ specifies a key binding that the command does not actually have.
 @smallexample
 @group
 (substitute-command-keys
 @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
 @end group
 
 @group


@@ -395,9 +412,9 @@ C-g             abort-recursive-edit
 
 @group
 (substitute-command-keys
 
 @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
 
 @end group
 @end smallexample
 


@@ -448,7 +465,7 @@ This function returns a string describing @var{event} in the standard
 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
 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.
 @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.


@@ -528,18 +545,19 @@ non-@code{nil}, the return value is always a vector.
 
 @node Help Functions
 @section Help Functions
 
 @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
 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
 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:
 definition as a function, variable, or face, or has properties.
 
 The function returns a list of elements that look like this:


@@ -604,7 +622,7 @@ subcommands of the prefix key.
 
 @defopt help-event-list
 The value of this variable is a list of event types that serve as
 
 @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
 
 event specified by @code{help-char}.
 @end defopt
 


@@ -639,7 +657,7 @@ sequence.  (The last event is, presumably, the help character.)
 @end deffn
 
   The following two functions are meant for modes that want to provide
 @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.
 
 Their names begin with @samp{Helper} to distinguish them from the
 ordinary help functions.
 


@@ -670,14 +688,17 @@ This function returns the name of the help buffer, which is normally
 @file{*Help*}; if such a buffer does not exist, it is first created.
 @end defun
 
 @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{}
 @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
 @end defmac
 
 @defun help-setup-xref item interactive-p


@@ -728,4 +749,3 @@ If this variable is non-@code{nil}, commands defined with
 echo area at first, and display the longer @var{help-text} strings only
 if the user types the help character again.
 @end defopt
 echo area at first, and display the longer @var{help-text} strings only
 if the user types the help character again.
 @end defopt

-