diff options
Diffstat (limited to 'doc/lispref')
| -rw-r--r-- | doc/lispref/ChangeLog | 15 | ||||
| -rw-r--r-- | doc/lispref/buffers.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/commands.texi | 35 | ||||
| -rw-r--r-- | doc/lispref/display.texi | 10 | ||||
| -rw-r--r-- | doc/lispref/frames.texi | 53 | ||||
| -rw-r--r-- | doc/lispref/functions.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/modes.texi | 9 | ||||
| -rw-r--r-- | doc/lispref/windows.texi | 49 |
8 files changed, 83 insertions, 92 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 2cb9970f5fd..f3fce93dd53 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,18 @@ +2014-10-04 Glenn Morris <rgm@gnu.org> + + * commands.texi (Generic Commands): Copyedits. + + * display.texi (Scroll Bars): + * modes.texi (Header Lines): Copyedits. + + * buffers.texi (Buffer List): + * display.texi (Image Descriptors, Defining Images): + * functions.texi (Core Advising Primitives): Small fixes re @var usage. + + * windows.texi (Window Sizes, Resizing Windows): Copyedits. + + * frames.texi (Multiple Terminals): Copyedits re multiple monitors. + 2014-10-03 Martin Rudalics <rudalics@gmx.at> * frames.texi (Size Parameters, Size and Position): Mention that diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 1293a03082c..5ac2d6786e8 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -863,7 +863,7 @@ If no suitable buffer exists, the buffer @file{*scratch*} is returned @defun last-buffer &optional buffer visible-ok frame This function returns the last buffer in @var{frame}'s buffer list other -than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the +than @var{buffer}. If @var{frame} is omitted or @code{nil}, it uses the selected frame's buffer list. The argument @var{visible-ok} is handled as with @code{other-buffer}, diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 58e903918bf..e5db4d87539 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -589,31 +589,26 @@ Put them into three windows, selecting the last one." @cindex alternatives, defining The macro @code{define-alternatives} can be used to define -@dfn{generic commands}. Generic commands are interactive functions -whose implementation can be selected among several alternatives, as a -matter of user preference. +@dfn{generic commands}. These are interactive functions whose +implementation can be selected from several alternatives, as a matter +of user preference. @defmac define-alternatives command &rest customizations -Define the new command `COMMAND'. +Define the new command @var{command}, a symbol. -The argument `COMMAND' should be a symbol. +When a user runs @kbd{M-x @var{command} @key{RET}} for the first time, +Emacs prompts for which real form of the command to use, and records +the selection by way of a custom variable. Using a prefix argument +repeats this process of choosing an alternative. -When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs -will prompt for which alternative to use and record the selected -command as a custom variable. +The variable @code{@var{command}-alternatives} should contain an alist +with alternative implementations of @var{command}. +Until this variable is set, @code{define-alternatives} has no effect. -Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an -alternative and overwrites the previous choice. - -The variable @code{COMMAND-alternatives} contains an alist -(@pxref{Association Lists}) with alternative implementations of -`COMMAND'. @code{define-alternatives} does not have any effect until -this variable is set. - -If @var{customizations} is non-@var{nil}, it should be composed of -alternating @code{defcustom} keywords and values to add to the -declaration of @code{COMMAND-alternatives} (typically :group and -:version). +If @var{customizations} is non-@code{nil}, it should consist of +alternating @code{defcustom} keywords (typically @code{:group} and +@code{:version}) and values to add to the declaration of +@code{@var{command}-alternatives}. @end defmac @node Interactive Call diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index e88eadb5ca7..46be5ecf3f0 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -3925,9 +3925,9 @@ bar actually occupies. @end defun @defun window-scroll-bar-width &optional window -This function returns the width of @var{window}'s vertical scrollbar, -in pixels. @var{window} must be a live window. If @var{window} is -@code{nil} or omitted, it will be the selected window. +This function returns the width in pixels of @var{window}'s vertical +scrollbar. @var{window} must be a live window, and defaults to the +selected window. @end defun If you don't specify these values for a window with @@ -4503,7 +4503,7 @@ functions to insert images into buffers. Each image descriptor has the form @code{(image . @var{props})}, where @var{props} is a property list of alternating keyword symbols -and values, including at least the pair @code{:type @var{TYPE}} which +and values, including at least the pair @code{:type @var{type}} that specifies the image type. The following is a list of properties that are meaningful for all @@ -4995,7 +4995,7 @@ of a list of image specifications @var{specs}. Each specification in @var{specs} is a property list with contents depending on image type. All specifications must at least contain the properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} -or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying +or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying the image type, e.g., @code{xbm}, @var{file} is the file to load the image from, and @var{data} is a string containing the actual image data. The first specification in the list whose @var{type} is supported, and diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index fdb995f2399..c8e0fff6cd0 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -314,57 +314,50 @@ on that display (@pxref{Deleting Frames}). @cindex multi-monitor On some ``multi-monitor'' setups, a single X display outputs to more -than one physical monitor. @code{display-monitor-attributes-list} and -@code{frame-monitor-attributes} can be used to obtain information -about each physical monitor on multi-monitor setups. +than one physical monitor. You can use the functions +@code{display-monitor-attributes-list} and @code{frame-monitor-attributes} +to obtain information about such setups. @defun display-monitor-attributes-list &optional display This function returns a list of physical monitor attributes on -@var{display}. Each element of the list is an association list, -representing the attributes of each physical monitor. The first -element corresponds to the primary monitor. - -Attributes for a physical monitor are: +@var{display}, which defaults to that of the selected frame. +Each element of the list is an association list, representing the +attributes of a physical monitor. The first element corresponds to +the primary monitor. The attribute keys and values are: @table @samp @item geometry -Position and size in pixels in the form of @samp{(X Y WIDTH HEIGHT)} +Position and size in pixels as @samp{(@var{x} @var{y} +@var{width} @var{height})}. @item workarea -Position and size of the workarea in pixels in the form of @samp{(X Y -WIDTH HEIGHT)} +Position and size of the work area in pixels as +@samp{(@var{x} @var{y} @var{width} @var{height})}. @item mm-size -Width and height in millimeters in the form of @samp{(WIDTH HEIGHT)} +Width and height in millimeters as @samp{(@var{width} @var{height})} @item frames -List of frames dominated by the physical monitor +List of frames that this physical monitor dominates (see below). @item name -Name of the physical monitor as a string +Name of the physical monitor as @var{string}. @end table -where X, Y, WIDTH, and HEIGHT are integers. @samp{name} is optional. - -A frame is dominated by a physical monitor when either the -largest area of the frame resides in the monitor, or the monitor -is the closest to the frame if the frame does not intersect any -physical monitors. Every non-tip frame (including invisible one) -in a graphical display is dominated by exactly one physical -monitor at a time, though it can span multiple (or no) physical -monitors. +@var{x}, @var{y}, @var{width}, and @var{height} are integers. +@samp{name} may not be present. -@var{display} defaults to the selected frame's display. +A frame is @dfn{dominated} by a physical monitor when either the +largest area of the frame resides in that monitor, or (if the frame +does not intersect any physical monitors) that monitor is the closest +to the frame. Every (non-tooltip) frame (whether visible or not) in a +graphical display is dominated by exactly one physical monitor at a +time, though the frame can span multiple (or no) physical monitors. @end defun @defun frame-monitor-attributes &optional frame This function returns the attributes of the physical monitor -dominating @var{frame}, which defaults to the selected frame. - -A frame is dominated by a physical monitor when either the -largest area of the frame resides in the monitor, or the monitor -is the closest to the frame if the frame does not intersect any -physical monitors. +dominating (see above) @var{frame}, which defaults to the selected frame. @end defun @node Frame Parameters diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 3049660159a..023175e3632 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1232,7 +1232,7 @@ global value of @var{place}. Whereas if @var{place} is of the form @code{(local @var{symbol})}, where @var{symbol} is an expression which returns the variable name, then @var{function} will only be added in the current buffer. Finally, if you want to modify a lexical variable, you will -have to use @code{(var @var{VARIABLE})}. +have to use @code{(var @var{variable})}. Every function added with @code{add-function} can be accompanied by an association list of properties @var{props}. Currently only two of those diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index e23e2685a7c..d67bac63b15 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -2221,13 +2221,10 @@ is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). It is normally @code{nil}, so that ordinary buffers have no header line. @end defvar -The function @code{window-header-line-height} returns the height of -the header line: - @defun window-header-line-height &optional window -Return the height of @var{window}'s header line, in pixels. -@var{window} must be a live window. If @var{window} is @code{nil} or -omitted, it will be the selected window. +This function returns the height in pixels of @var{window}'s header +line. @var{window} must be a live window, and defaults to the +selected window. @end defun A window that is just one line tall never displays a header line. A diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f2fe5c85a93..f5122a39f8c 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -451,7 +451,7 @@ This function returns the total height, in lines, of the window the selected window. If @var{window} is an internal window, the return value is the total height occupied by its descendant windows. - If a window's pixel height is not an integral multiple of its frame's + If a window's pixel height is not an integral multiple of its frame's default character height, the number of lines occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total heights of all its child windows @@ -462,13 +462,12 @@ vertically combined and has a right sibling, the topmost row of that sibling can be calculated as the sum of this window's topmost row and total height (@pxref{Coordinates and Windows}) - If the optional argument @var{round} equals @code{ceiling}, this + If the optional argument @var{round} is @code{ceiling}, this function returns the smallest integer larger than @var{window}'s pixel -height divided by the character height of @var{window}'s frame; if it is -@code{floor}, it returns the largest integer smaller than @var{window}'s -pixel height divided by the character height of @var{window}'s frame. -Any other value of @var{round} means to return the internal value of the -total height of @var{window}. +height divided by the character height of its frame; if it is +@code{floor}, it returns the largest integer smaller than said value; +with any other @var{round} it returns the internal value of +@var{windows}'s total height. @end defun @cindex window width @@ -484,7 +483,7 @@ This function returns the total width, in columns, of the window the selected window. If @var{window} is internal, the return value is the total width occupied by its descendant windows. - If a window's pixel width is not an integral multiple of its frame's + If a window's pixel width is not an integral multiple of its frame's character width, the number of lines occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total widths of all its children internally @@ -493,15 +492,9 @@ windows have the same pixel width, their internal total widths may differ by one column. This means also, that if this window is horizontally combined and has a right sibling, the leftmost column of that sibling can be calculated as the sum of this window's leftmost -column and total width (@pxref{Coordinates and Windows}). - -If the optional argument @var{round} is @code{ceiling}, this function -will return the smallest integer larger than @var{window}'s pixel width -divided by the character width of @var{window}'s frame; if it is -@code{floor}, it returns the largest integer smaller than @var{window}'s -pixel width divided by the character width of @var{window}'s frame. Any -other value of @var{round} means to return the internal total width of -@var{window}. +column and total width (@pxref{Coordinates and Windows}). The +optional argument @var{round} behaves as it does for +@code{window-total-height}. @end defun @defun window-total-size &optional window horizontal round @@ -510,8 +503,7 @@ width in columns of the window @var{window}. If @var{horizontal} is omitted or @code{nil}, this is equivalent to calling @code{window-total-height} for @var{window}; otherwise it is equivalent to calling @code{window-total-width} for @var{window}. The optional -argument @code{ROUND} is handled as for @code{window-total-height} and -@code{window-total-width}. +argument @var{round} behaves as it does for @code{window-total-height}. @end defun The following two functions can be used to return the total size of a @@ -754,8 +746,8 @@ tall; and a minimum-width window as one consisting of fringes, margins, a scroll bar and a right divider (if any), plus a text area two columns wide. -If the optional argument @code{pixelwise} is non-@code{nil}, -@var{delta} will be interpreted as pixels. +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} is interpreted as pixels. @end defun @defun window-resize window delta &optional horizontal ignore pixelwise @@ -779,7 +771,7 @@ values of the option @code{window-combination-resize} and the combination limits of the involved windows; in some cases, it may alter both edges. @xref{Recombining Windows}. To resize by moving only the bottom or right edge of a window, use the function -@code{adjust-window-trailing-edge}, below. +@code{adjust-window-trailing-edge}. @end defun @c The commands enlarge-window, enlarge-window-horizontally, @@ -792,8 +784,8 @@ If optional argument @var{horizontal} is non-@code{nil}, it instead moves the right edge by @var{delta} columns. If @var{window} is @code{nil}, it defaults to the selected window. -If the optional argument @code{pixelwise} is non-@code{nil}, -@var{delta} will be interpreted as pixels. +If the optional argument @var{pixelwise} is non-@code{nil}, +@var{delta} is interpreted as pixels. A positive @var{delta} moves the edge downwards or to the right; a negative @var{delta} moves it upwards or to the left. If the edge @@ -807,17 +799,16 @@ window is fixed-size), it may resize other windows. @cindex pixelwise, resizing windows @defopt window-resize-pixelwise -If the value of this option is non-@code{nil}, windows are resized in +If the value of this option is non-@code{nil}, Emacs resizes windows in units of pixels. This currently affects functions like @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window}, @code{minimize-window}, @code{fit-window-to-buffer}, @code{shrink-window-if-larger-than-buffer} (all listed below) and @code{fit-frame-to-buffer} (@pxref{Size and Position}). -Note that when a frame's pixel size is not a multiple of the frame's -character size, at least one window may get resized pixelwise even if -this option is @code{nil}. The default value of this option is -@code{nil}. +Note that when a frame's pixel size is not a multiple of its character +size, at least one window may get resized pixelwise even if this +option is @code{nil}. The default value is @code{nil}. @end defopt The following commands resize windows in more specific ways. When |