procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Minor copyedits of recent changes in documentation

Browse source 
* doc/lispref/frames.texi (Frame Layout, Frame Position)
(Frame Size, Frame Interaction Parameters, Input Focus)
(Raising and Lowering, Child Frames): Improve wording and indexing.
* doc/emacs/cmdargs.texi (Borders X): Improve indexing.
This commit is contained in:
Eli Zaretskii 2017-04-13 20:52:30 +03:00
parent dbae41896c
commit 030c4f94b6
3 changed files with 96 additions and 85 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/emacs/cmdargs.texi
View file

@ -1077,6 +1077,7 @@ frame's text area), in pixels.
@itemx --border-width=@var{width}
@opindex --border-width
@cindex main border width, command-line argument
@cindex outer border width, command-line argument
Specify @var{width} as the width of the outer border, in pixels.
@end table

174
doc/lispref/frames.texi
View file

@ -505,17 +505,17 @@ two frames adjacent to each other on the screen. Usually, the outer
size of a frame is available only after the frame has been mapped (made
visible, @pxref{Visibility of Frames}) at least once. For the initial
frame or a frame that has not been created yet, the outer size can be
estimated only or must be calculated from the window-system's or window
manager defaults. One workaround is to obtain the differences of the
only estimated or must be calculated from the window-system's or window
manager's defaults. One workaround is to obtain the differences of the
outer and native (see below) sizes of a mapped frame and use them for
calculating the outer size of the new frame.
@cindex outer position
The upper left corner of the outer frame (indicated by @samp{(0)} in the
drawing above) is the @dfn{outer position} of the frame. The outer
position of a graphical frame is also referred to as ``the position'' of
the frame because it usually remains unchanged on its display whenever
the frame is resized or its layout is changed.
The position of the upper left corner of the outer frame (indicated by
@samp{(0)} in the drawing above) is the @dfn{outer position} of the
frame. The outer position of a graphical frame is also referred to as
``the position'' of the frame because it usually remains unchanged on
its display whenever the frame is resized or its layout is changed.
The outer position is specified by and can be set via the @code{left}
and @code{top} frame parameters (@pxref{Position Parameters}). For a
@ -551,22 +551,24 @@ frames (@pxref{Child Frames}) and @code{undecorated} or
@code{override-redirect} frames (@pxref{Management Parameters}).
Outer borders are never shown on text terminal frames and on frames
generated by GTK+ routines. On Windows, the outer border is emulated
generated by GTK+ routines. On MS-Windows, the outer border is emulated
with the help of a one pixel wide external border. Non-toolkit builds
allow to change the color of the outer border by setting the
on X allow to change the color of the outer border by setting the
@code{border-color} frame parameter (@pxref{Layout Parameters}).
@item Title Bar
@cindex title bar
The @dfn{title bar} is also part of the window manager's decorations and
typically displays the title of the frame (@pxref{Frame Titles}) as well
as buttons for minimizing, maximizing and deleting the frame. It can be
also used for dragging the frame with the mouse. The title bar is
usually not displayed for fullboth (@pxref{Size Parameters}), tooltip
(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't
exist for terminal frames. Display of the title bar can be suppressed
by setting the @code{override-redirect} or the @code{undecorated} frame
parameters (@pxref{Management Parameters}).
@cindex caption bar
The @dfn{title bar}, a.k.a.@ @dfn{caption bar}, is also part of the
window manager's decorations and typically displays the title of the
frame (@pxref{Frame Titles}) as well as buttons for minimizing,
maximizing and deleting the frame. It can be also used for dragging
the frame with the mouse. The title bar is usually not displayed for
fullboth (@pxref{Size Parameters}), tooltip (@pxref{Tooltips}) and
child frames (@pxref{Child Frames}) and doesn't exist for terminal
frames. Display of the title bar can be suppressed by setting the
@code{override-redirect} or the @code{undecorated} frame parameters
(@pxref{Management Parameters}).
@item Menu Bar
@cindex internal menu bar
@ -582,11 +584,12 @@ and Frames}). As a rule, menu bars are never shown on child frames
setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters})
to zero.
It depends on the toolkit whether to wrap or truncate the menu bar
whenever it becomes too long to fit on its frame. Usually, only Motif
and Windows builds can wrap the menu bar. When they (un-)wrap the menu
bar, they try to keep the outer height of the frame unchanged, so the
native height of the frame (see below) will change instead.
Whether the menu bar is wrapped or truncated whenever its width
becomes too large to fit on its frame depends on the toolkit .
Usually, only Motif and MS-Windows builds can wrap the menu bar. When
they (un-)wrap the menu bar, they try to keep the outer height of the
frame unchanged, so the native height of the frame (see below) will
change instead.
@item Tool Bar
@cindex internal tool bar
@ -602,12 +605,13 @@ setting the @code{tool-bar-lines} parameter (@pxref{Layout
Parameters}) to zero.
If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs
wraps the internal tool bar when it becomes too long for its frame. If
and when Emacs (un-)wraps the internal tool bar, it by default keeps the
outer height of the frame unchanged, so the native height of the frame
(see below) will change instead. Emacs built with GTK+, on the other
hand, never wraps the tool bar but may automatically increase the outer
width of a frame in order to accommodate an overlong tool bar.
wraps the internal tool bar when its width becomes too large for its
frame. If and when Emacs (un-)wraps the internal tool bar, it by
default keeps the outer height of the frame unchanged, so the native
height of the frame (see below) will change instead. Emacs built with
GTK+, on the other hand, never wraps the tool bar but may
automatically increase the outer width of a frame in order to
accommodate an overlong tool bar.
@item Native Frame
@cindex native frame
@ -631,14 +635,14 @@ button in the title bar or when dragging its external border with the
mouse.
@cindex native position
The top left corner of the native frame specifies the @dfn{native
position} of the frame. (1)--(3) in the drawing above indicate that
position for the various builds:
The position of the top left corner of the native frame specifies the
@dfn{native position} of the frame. (1)--(3) in the drawing above
indicate that position for the various builds:
@itemize @w{}
@item (1) non-toolkit and terminal frames
@item (2) Lucid, Motif and Windows frames
@item (2) Lucid, Motif and MS-Windows frames
@item (3) GTK+ and NS frames
@end itemize
@ -697,11 +701,11 @@ The @dfn{text area} of a frame is a somewhat fictitious area that can be
embedded in the native frame. Its position is unspecified. Its width
can be obtained by removing from that of the native width the widths of
the internal border, one vertical scroll bar, and one left and one right
fringe as specified for this frame, see @ref{Layout Parameters}. Its
height can be obtained by removing from that of the native height the
widths of the internal border and the heights of the frame's internal
menu and tool bars and one horizontal scroll bar as specified for this
frame.
fringe if they are specified for this frame, see @ref{Layout
Parameters}. Its height can be obtained by removing from that of the
native height the widths of the internal border and the heights of the
frame's internal menu and tool bars and one horizontal scroll bar if
specified for this frame.
@end table
@cindex absolute position
@ -715,7 +719,7 @@ horizontal and vertical pixel offsets relative to an origin (0, 0) of
the frame's display. Correspondingly, the @dfn{absolute edges} of a
frame are given as pixel offsets from that origin.
Note that with multiple monitors the origin of the display does not
Note that with multiple monitors, the origin of the display does not
necessarily coincide with the top-left corner of the entire usable
display area of the terminal. Hence the absolute position of a frame
can be negative in such an environment even when that frame is
@ -724,7 +728,7 @@ completely visible.
By convention, vertical offsets increase ``downwards''. This means
that the height of a frame is obtained by subtracting the offset of its
top edge from that of its bottom edge. Horizontal offsets increase
``leftwards'' as expected so a frame's width is calculated by
``rightwards'', as expected, so a frame's width is calculated by
subtracting the offset of its left edge from that of its right edge.
For a frame on a graphical terminal the following function returns the
@ -734,9 +738,10 @@ sizes of the areas described above:
This function returns geometric attributes of @var{frame}. The return
value is an association list of the attributes listed below. All
coordinate, height and width values are integers counting pixels. Note
that if @var{frame} has not been mapped (@pxref{Visibility of Frames})
yet, some of the return values may only represent approximations of the
actual values---those that can be seen after the frame has been mapped.
that if @var{frame} has not been mapped yet, (@pxref{Visibility of
Frames}) some of the return values may only represent approximations of
the actual values---those that can be seen after the frame has been
mapped.
@table @code
@item outer-position
@ -792,10 +797,10 @@ native and inner frame.
@defun frame-edges &optional frame type
This function returns the absolute edges of the outer, native or inner
frame of @var{frame}. @var{frame} must be a live frame and defaults to
the selected one. The list returned has the form (@var{left} @var{top}
@var{right} @var{bottom}) where all values are in pixels relative to the
origin of @var{frame}'s display. For terminal frames the values
returned for @var{left} and @var{top} are always zero.
the selected one. The returned list has the form @w{@code{(@var{left}
@var{top} @var{right} @var{bottom})}} where all values are in pixels
relative to the origin of @var{frame}'s display. For terminal frames
the values returned for @var{left} and @var{top} are always zero.
Optional argument @var{type} specifies the type of the edges to return:
@code{outer-edges} means to return the outer edges of @var{frame},
@ -803,14 +808,15 @@ Optional argument @var{type} specifies the type of the edges to return:
@code{inner-edges} means to return its inner edges.
By convention, the pixels of the display at the values returned for
@var{left} and @var{top} are inside (part of) @var{frame}. Hence, if
@var{left} and @var{top} are both zero, the pixel at the display's
origin is part of @var{frame}. The pixels at @var{bottom} and
@var{right}, on the other hand, lie immediately outside @var{frame}.
This means that if you have, for example, two side-by-side frames
positioned such that the right outer edge of the frame on the left
equals the left outer edge of the frame on the right, the pixels at that
edge show a part of the frame on the right.
@var{left} and @var{top} are considered to be inside (part of)
@var{frame}. Hence, if @var{left} and @var{top} are both zero, the
pixel at the display's origin is part of @var{frame}. The pixels at
@var{bottom} and @var{right}, on the other hand, are considered to lie
immediately outside @var{frame}. This means that if you have, for
example, two side-by-side frames positioned such that the right outer
edge of the frame on the left equals the left outer edge of the frame on
the right, the pixels at that edge show a part of the frame on the
right.
@end defun
@ -878,21 +884,21 @@ Geometry}). The position of a child frame (@pxref{Child Frames}) is
specified via pixel offsets of its outer edges relative to the native
position of its parent frame.
You can read or change the position of a frame using the frame
You can access or change the position of a frame using the frame
parameters @code{left} and @code{top} (@pxref{Position Parameters}).
Here are two additional functions for working with the positions of an
existing, visible frame. For both functions, the argument @var{frame}
must denote a live frame and defaults to the selected frame.
@defun frame-position &optional frame
For a normal, non-child frame this function returns a cons of the (X, Y)
pixel coordinates of its outer position (@pxref{Frame Layout}) with
respect to the origin (0, 0) of its display. For a child frame
For a normal, non-child frame this function returns a cons of the pixel
coordinates of its outer position (@pxref{Frame Layout}) with respect to
the origin @code{(0, 0)} of its display. For a child frame
(@pxref{Child Frames}) this function returns the pixel coordinates of
its outer position with respect to an origin (0, 0) at the native
its outer position with respect to an origin @code{(0, 0)} at the native
position of @var{frame}'s parent.
Negative return values never indicate an offset from the right or bottom
Negative values never indicate an offset from the right or bottom
edge of @var{frame}'s display or parent frame. Rather, they mean that
@var{frame}'s outer position is on the left and/or above the origin of
its display or the native position of its parent frame. This usually
@ -907,7 +913,7 @@ On a text terminal frame both values are zero.
@defun set-frame-position frame x y
This function sets the outer frame position of @var{frame} to (@var{x},
@var{y}). The latter arguments specify pixels and normally count from
an origin at the position (0, 0) of @var{frame}'s display. For child
the origin at the position (0, 0) of @var{frame}'s display. For child
frames, they count from the native position of @var{frame}'s parent
frame.
@ -921,14 +927,15 @@ edge of @var{frame} exactly at the right or bottom edge of its display
or parent frame. Neither do they allow to specify a position that does
not lie within the edges of the display or parent frame. The frame
parameters @code{left} and @code{top} (@pxref{Position Parameters})
allow to do that but may still fail to provide good results for the
allow to do that, but may still fail to provide good results for the
initial or a new frame.
This function has no effect on text terminal frames.
@end defun
@defvar move-frame-functions
This hook specifies the functions run when an Emacs frame is moved
@cindex frame position changes, a hook
This hook specifies the functions that are run when an Emacs frame is moved
(assigned a new position) by the window-system or window manager. The
functions are run with one argument, the frame that moved. For a child
frame (@pxref{Child Frames}), the functions are run only when the
@ -954,8 +961,8 @@ This means that in general you cannot use the native size to specify the
initial size of a frame. As soon as you know the native size of a
visible frame, you can calculate its outer size (@pxref{Frame Layout})
by adding in the remaining components from the return value of
@code{frame-geometry} . For invisible frames or for frames that have
yet to be created, however, the outer size can be estimated only. This
@code{frame-geometry}. For invisible frames or for frames that have
yet to be created, however, the outer size can only be estimated. This
also means that calculating an exact initial position of a frame
specified via offsets from the right or bottom edge of the screen
(@pxref{Frame Position}) is impossible.
@ -1006,8 +1013,8 @@ leaving some empty space below and/or on the right of the frame. The
following option may help in that case.
@defopt frame-resize-pixelwise
If this option is @code{nil}, a frame's text pixel size is usually
rounded to a multiple of the current values of that frame's
If this option is @code{nil} (the default), a frame's text pixel size is
usually rounded to a multiple of the current values of that frame's
@code{frame-char-height} and @code{frame-char-width} whenever the frame
is resized. If this is non-@code{nil}, no rounding occurs, hence frame
sizes can increase/decrease by one pixel.
@ -1747,6 +1754,8 @@ If non-@code{nil}, this frame's window is never split automatically.
@node Frame Interaction Parameters
@subsubsection Frame Interaction Parameters
@cindex frame interaction parameters
@cindex interaction parameters between frames
These parameters supply forms of interactions between different frames.
@ -1754,7 +1763,7 @@ These parameters supply forms of interactions between different frames.
@vindex parent-frame, a frame parameter
@item parent-frame
If non-@code{nil}, this means that this frame is a child frame
(@pxref{Child Frames}) and this parameter specifies its parent frame.
(@pxref{Child Frames}), and this parameter specifies its parent frame.
If nil, this means that this frame is a normal, top-level frame.
@vindex delete-before, a frame parameter
@ -1852,13 +1861,13 @@ display bugs or pine for that retro, flicker-y feeling.
If non-@code{nil}, this tells the window manager to remove the frame's
icon from the taskbar associated with the frame's display and inhibit
switching to the frame's window via the combination @kbd{Alt-@key{TAB}}.
On Windows, iconifying such a frame will "roll in" its window-system
On MS-Windows, iconifying such a frame will "roll in" its window-system
window at the bottom of the desktop. Some window managers may not honor
this parameter.
@vindex no-focus-on-map, a frame parameter
@item no-focus-on-map
If non-@code{nil}, this means that the frame dos not want to receive
If non-@code{nil}, this means that the frame does not want to receive
input focus when it is mapped (@pxref{Visibility of Frames}). Some
window managers may not honor this parameter.
@ -1875,8 +1884,8 @@ this parameter.
@vindex undecorated, a frame parameter
@item undecorated
If non-@code{nil}, this frame's window-system window is drawn without
decorations like title, minimize/maximize boxes and external borders.
This usually means that the window cannot be dragged, resized,
decorations, like the title, minimize/maximize boxes and external
borders. This usually means that the window cannot be dragged, resized,
iconified, maximized or deleted with the mouse. If nil, the frame's
window is usually drawn with all the elements listed above unless their
display has been suspended via window manager settings.
@ -2266,8 +2275,8 @@ frame.
It first deletes any child frame of @var{frame} (@pxref{Child Frames})
and any frame whose @code{delete-before} frame parameter (@pxref{Frame
Interaction Parameters}) specifies @var{frame}. All such deletions are
performed recursively; so this step makes sure that there will not exist
any other frames with @var{frame} as their ancestor. Then, unless
performed recursively; so this step makes sure that there no other
frames with @var{frame} as their ancestor will exist. Then, unless
@var{frame} specifies a tooltip, this function runs the hook
@code{delete-frame-functions} (each function getting one argument,
@var{frame}) before actually killing the frame.
@ -2468,7 +2477,7 @@ non-@code{nil}, means to avoid making @var{frame}'s window-system window
the ``active'' window which should insist a bit more on avoiding to
raise @var{frame} above other frames.
On Windows the @var{noactivate} argument has no effect. However, if
On MS-Windows the @var{noactivate} argument has no effect. However, if
@var{frame} is a child frame (@pxref{Child Frames}), this function
usualy does focus @var{frame} without raising it above other child
frames.
@ -2593,7 +2602,7 @@ Note that this option does not distinguish ``sloppy'' focus (where the
frame that previously had focus retains focus as long as the mouse
pointer does not move into another window manager window) from
``strict'' focus (where a frame immediately loses focus when it's left
by the mouse pointer). It neither recognizes whether your window
by the mouse pointer). Neither does it recognize whether your window
manager supports delayed focusing or auto-raising where you can
explicitly specify the time until a new frame gets focus or is
auto-raised.
@ -2656,7 +2665,7 @@ you can do that with @code{raise-frame} if you wish (@pxref{Raising and
Lowering}).
Making a frame visible usually makes all its child frames (and their
descendants) visible too (@pxref{Child Frames}).
descendants) visible as well (@pxref{Child Frames}).
@end deffn
@deffn Command make-frame-invisible &optional frame force
@ -2691,6 +2700,7 @@ selected frame.
@cindex restacking a frame
@cindex frame stacking order
@cindex frame Z-order
@cindex Z-order
Most window systems use a desktop metaphor. Part of this metaphor is
the idea that system-level windows (representing, e.g., Emacs frames)
are stacked in a notional third dimension perpendicular to the screen
@ -2865,8 +2875,8 @@ frame does not show a menu or tool bar, any other of the frame's borders
(@pxref{Layout Parameters}) can be used instead of the external borders.
In particular, under X (but not when building with GTK+), the frame's
outer border can be used. On Windows, specifying a non-zero outer
border width will show a one pixel wide external border. Under all
outer border can be used. On MS-Windows, specifying a non-zero outer
border width will show a one-pixel wide external border. Under all
window-systems, the internal border can be used. In either case, it's
advisable to disable a child frame's window manager decorations with the
@code{undecorated} frame parameter @pxref{Management Parameters}).
@ -2902,9 +2912,9 @@ policy to child frames. Customizing @code{mouse-autoselect-window} can
help in this regard (@pxref{Mouse Window Auto-selection}).
@item
Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too
Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed to
work on all window-systems. Some will drop the object on the parent
frame or some ancestor instead.
frame or on some ancestor instead.
@end itemize
The following two functions may be useful when working with child and

6
doc/lispref/windows.texi
View file

@ -1752,9 +1752,9 @@ whenever a window gets selected more ``permanently''.
not related to window management, it will usually make sense to save the
value of the selected window somewhere and compare it with the value of
@code{selected-window} while running that hook. Also, to avoid false
positives when using @code{buffer-list-update-hook} it is good practice
positives when using @code{buffer-list-update-hook}, it is good practice
that every @code{select-window} call supposed to select a window only
temporarily, passes a non-@code{nil} @var{norecord} argument. If
temporarily passes a non-@code{nil} @var{norecord} argument. If
possible, the macro @code{with-selected-window} (see below) should be
used in such cases.
@ -4623,7 +4623,7 @@ Any other non-@code{nil} value means to select a window instantaneously
as soon as the mouse pointer enters it.
@end table
In either case the mouse pointer must enter the text area of a window in
In either case, the mouse pointer must enter the text area of a window in
order to trigger its selection. Dragging the scroll bar slider or the
mode line of a window conceptually should not cause its auto-selection.