Update copyright year to 2016

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

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 6fdc8e2ec797ab8a3083bde8658b3c61cc596552..dee43cefb15ef7464fbf9bf328c5b55455d2ab1f 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software

 @c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @node Command Loop
 @c Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @node Command Loop


@@ -132,7 +132,7 @@ byte compiler to warn if the command is called from Lisp.  The output
 of @code{describe-function} will include similar information.
 The value of the property can be: a string, which the byte-compiler
 will use directly in its warning (it should end with a period, and not
 of @code{describe-function} will include similar information.
 The value of the property can be: a string, which the byte-compiler
 will use directly in its warning (it should end with a period, and not

-start with a capital, e.g. ``use @dots{} instead.''); @code{t}; any
+start with a capital, e.g., @code{"use (system-name) instead."}); @code{t}; any

 other symbol, which should be an alternative function to use in Lisp
 code.
 
 other symbol, which should be an alternative function to use in Lisp
 code.
 


@@ -211,7 +211,7 @@ argument.
 
 The prompt string can use @samp{%} to include previous argument values
 (starting with the first argument) in the prompt.  This is done using
 
 The prompt string can use @samp{%} to include previous argument values
 (starting with the first argument) in the prompt.  This is done using

-@code{format} (@pxref{Formatting Strings}).  For example, here is how
+@code{format-message} (@pxref{Formatting Strings}).  For example, here is how

 you could read the name of an existing buffer followed by a new name to
 give to that buffer:
 
 you could read the name of an existing buffer followed by a new name to
 give to that buffer:
 


@@ -1043,8 +1043,8 @@ the current Emacs session.  If a symbol has not yet been so used,
 @end defun
 
 @menu
 @end defun
 
 @menu

-* Keyboard Events::             Ordinary characters--keys with symbols on them.
-* Function Keys::               Function keys--keys with names, not symbols.
+* Keyboard Events::             Ordinary characters -- keys with symbols on them.
+* Function Keys::               Function keys -- keys with names, not symbols.

 * Mouse Events::                Overview of mouse events.
 * Click Events::                Pushing and releasing a mouse button.
 * Drag Events::                 Moving the mouse before releasing the button.
 * Mouse Events::                Overview of mouse events.
 * Click Events::                Pushing and releasing a mouse button.
 * Drag Events::                 Moving the mouse before releasing the button.


@@ -1462,7 +1462,7 @@ the symbols @code{handle} (the scroll bar handle), @code{above-handle}
 (the area above the handle), @code{below-handle} (the area below the
 handle), @code{up} (the up arrow at one end of the scroll bar), or
 @code{down} (the down arrow at one end of the scroll bar).
 (the area above the handle), @code{below-handle} (the area below the
 handle), @code{up} (the up arrow at one end of the scroll bar), or
 @code{down} (the down arrow at one end of the scroll bar).

-@c The `top', `bottom', and `end-scroll' codes don't seem to be used.
+@c The 'top', 'bottom', and 'end-scroll' codes don't seem to be used.

 @end table
 
 
 @end table
 
 


@@ -1557,8 +1557,8 @@ the command binding of the double click event to assume that the
 single-click command has already run.  It must produce the desired
 results of a double click, starting from the results of a single click.
 
 single-click command has already run.  It must produce the desired
 results of a double click, starting from the results of a single click.
 

-This is convenient, if the meaning of a double click somehow ``builds
-on'' the meaning of a single click---which is recommended user interface
+This is convenient, if the meaning of a double click somehow builds
+on the meaning of a single click---which is recommended user interface

 design practice for double clicks.
 
 If you click a button, then press it down again and start moving the
 design practice for double clicks.
 
 If you click a button, then press it down again and start moving the


@@ -1720,7 +1720,7 @@ occurred.
 
 @vindex mouse-wheel-up-event
 @vindex mouse-wheel-down-event
 
 @vindex mouse-wheel-up-event
 @vindex mouse-wheel-down-event

-This kind of event is generated only on some kinds of systems. On some
+This kind of event is generated only on some kinds of systems.  On some

 systems, @code{mouse-4} and @code{mouse-5} are used instead.  For
 portable code, use the variables @code{mouse-wheel-up-event} and
 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine
 systems, @code{mouse-4} and @code{mouse-5} are used instead.  For
 portable code, use the variables @code{mouse-wheel-up-event} and
 @code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine


@@ -1856,7 +1856,7 @@ into another window.  That produces a pair of events like these:
 @end smallexample
 
 The frame with input focus might not take up the entire screen, and
 @end smallexample
 
 The frame with input focus might not take up the entire screen, and

-the user might move the mouse outside the scope of the frame. Inside
+the user might move the mouse outside the scope of the frame.  Inside

 the @code{track-mouse} special form, that produces an event like this:
 
 @smallexample
 the @code{track-mouse} special form, that produces an event like this:
 
 @smallexample


@@ -2085,7 +2085,13 @@ Return the actual row and column in @var{position}, as a cons cell
 @code{(@var{col} . @var{row})}.  The values are the actual row and
 column numbers in the window given by @var{position}.  @xref{Click
 Events}, for details.  The function returns @code{nil} if
 @code{(@var{col} . @var{row})}.  The values are the actual row and
 column numbers in the window given by @var{position}.  @xref{Click
 Events}, for details.  The function returns @code{nil} if

-@var{position} does not include actual position values.
+@var{position} does not include actual position values; in that case
+@code{posn-col-row} can be used to get approximate values.
+
+Note that this function doesn't account for the visual width of
+characters on display, like the number of visual columns taken by a
+tab character or an image.  If you need the coordinates in canonical
+character units, use @code{posn-col-row} instead.

 @end defun
 
 @defun posn-string position
 @end defun
 
 @defun posn-string position


@@ -2107,8 +2113,9 @@ Return the image or string object in @var{position}, either
 @defun posn-object-x-y position
 Return the pixel-based x and y coordinates relative to the upper left
 corner of the object in @var{position} as a cons cell @code{(@var{dx}
 @defun posn-object-x-y position
 Return the pixel-based x and y coordinates relative to the upper left
 corner of the object in @var{position} as a cons cell @code{(@var{dx}

-. @var{dy})}.  If the @var{position} is a buffer position, return the
-relative position in the character at that position.
+. @var{dy})}.  If the @var{position} is on buffer text, return the
+relative position of the buffer-text character closest to that
+position.

 @end defun
 
 @defun posn-object-width-height position
 @end defun
 
 @defun posn-object-width-height position


@@ -2437,7 +2444,7 @@ same symbol that would normally represent that combination of mouse
 button and modifier keys.  The information about the window part is kept
 elsewhere in the event---in the coordinates.  But
 @code{read-key-sequence} translates this information into imaginary
 button and modifier keys.  The information about the window part is kept
 elsewhere in the event---in the coordinates.  But
 @code{read-key-sequence} translates this information into imaginary

-``prefix keys'', all of which are symbols: @code{header-line},
+prefix keys, all of which are symbols: @code{header-line},

 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
 @code{vertical-line}, and @code{vertical-scroll-bar}.  You can define
 meanings for mouse clicks in special window parts by defining key
 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
 @code{vertical-line}, and @code{vertical-scroll-bar}.  You can define
 meanings for mouse clicks in special window parts by defining key


@@ -2580,7 +2587,7 @@ If you wish to read a single key taking these translations into
 account, use the function @code{read-key}:
 
 @defun read-key &optional prompt
 account, use the function @code{read-key}:
 
 @defun read-key &optional prompt

-This function reads a single key.  It is ``intermediate'' between
+This function reads a single key.  It is intermediate between

 @code{read-key-sequence} and @code{read-event}.  Unlike the former, it
 reads a single key, not a key sequence.  Unlike the latter, it does
 not return a raw event, but decodes and translates the user input
 @code{read-key-sequence} and @code{read-event}.  Unlike the former, it
 reads a single key, not a key sequence.  Unlike the latter, it does
 not return a raw event, but decodes and translates the user input


@@ -2626,7 +2633,7 @@ character for this purpose, but as a character with no modifiers.
 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
 modification.
 
 Thus, setting @code{extra-keyboard-modifiers} to zero cancels any
 modification.
 

-When using a window system, the program can ``press'' any of the
+When using a window system, the program can press any of the

 modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
 keys can be virtually pressed.
 
 modifier keys in this way.  Otherwise, only the @key{CTL} and @key{META}
 keys can be virtually pressed.
 


@@ -2776,7 +2783,7 @@ What character @kbd{1 7 7}-
 @node Event Input Misc
 @subsection Miscellaneous Event Input Features
 
 @node Event Input Misc
 @subsection Miscellaneous Event Input Features
 

-This section describes how to ``peek ahead'' at events without using
+This section describes how to peek ahead at events without using

 them up, how to check for pending input, and how to discard pending
 input.  See also the function @code{read-passwd} (@pxref{Reading a
 Password}).
 them up, how to check for pending input, and how to discard pending
 input.  See also the function @code{read-passwd} (@pxref{Reading a
 Password}).


@@ -2811,7 +2818,7 @@ most recently unread will be reread first.
 Events read from this list are not normally added to the current
 command's key sequence (as returned by, e.g., @code{this-command-keys}),
 as the events will already have been added once as they were read for
 Events read from this list are not normally added to the current
 command's key sequence (as returned by, e.g., @code{this-command-keys}),
 as the events will already have been added once as they were read for

-the first time.  An element of the form @code{(@code{t} . @var{event})}
+the first time.  An element of the form @w{@code{(t . @var{event})}}

 forces @var{event} to be added to the current command's key sequence.
 @end defvar
 
 forces @var{event} to be added to the current command's key sequence.
 @end defvar
 


@@ -3041,7 +3048,7 @@ usual result of this---a quit---is prevented.  Eventually,
 binding is unwound at the end of a @code{let} form.  At that time, if
 @code{quit-flag} is still non-@code{nil}, the requested quit happens
 immediately.  This behavior is ideal when you wish to make sure that
 binding is unwound at the end of a @code{let} form.  At that time, if
 @code{quit-flag} is still non-@code{nil}, the requested quit happens
 immediately.  This behavior is ideal when you wish to make sure that

-quitting does not happen within a ``critical section'' of the program.
+quitting does not happen within a critical section of the program.

 
 @cindex @code{read-quoted-char} quitting
   In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
 
 @cindex @code{read-quoted-char} quitting
   In some functions (such as @code{read-quoted-char}), @kbd{C-g} is


@@ -3304,7 +3311,7 @@ using the minibuffer.  Usually it is more convenient for the user if you
 change the major mode of the current buffer temporarily to a special
 major mode, which should have a command to go back to the previous mode.
 (The @kbd{e} command in Rmail uses this technique.)  Or, if you wish to
 change the major mode of the current buffer temporarily to a special
 major mode, which should have a command to go back to the previous mode.
 (The @kbd{e} command in Rmail uses this technique.)  Or, if you wish to

-give the user different text to edit ``recursively'', create and select
+give the user different text to edit recursively, create and select

 a new buffer in a special mode.  In this mode, define a command to
 complete the processing and go back to the previous buffer.  (The
 @kbd{m} command in Rmail does this.)
 a new buffer in a special mode.  In this mode, define a command to
 complete the processing and go back to the previous buffer.  (The
 @kbd{m} command in Rmail does this.)