Re: trunk r116526: Document some frame and window changes in NEWS.

Re: trunk r116526: Document some frame and window changes in NEWS.

[Glenn Morris]

Hi Martin,

Why did you mark all these NEWS entries with ---?
It is not obvious to me that no doc changes are needed.

Eg on a specific level, funtions like window-total-size are documented
in the manual, and take different arguments now.

And on a general level, why should the manuals make no mention
whatsoever of "dividers", pixelwise resizing, etc?


Martin Rudalics wrote:
> 
> --- a/etc/NEWS	2014-02-21 20:24:02 +0000
> +++ b/etc/NEWS	2014-02-22 17:57:57 +0000
> @@ -194,15 +194,67 @@
>  These are normal hooks run when an Emacs frame gains or loses input focus.
>  
>  ---
> -*** Emacs can now draw dividers between adjacent windows.
> -To put dividers between side-by-side/vertically stacked windows
> -customize the frame parameter `right-divider-width'/`bottom-divider-width'
> -to some positive integer.  You can drag dividers with the mouse
> -(they show a corresponding cursor when the mouse hovers over them).
> -You can change the appearance of dividers by customizing the faces
> -`window-divider', `window-divider-first-pixel', and
> -`window-divider-last-pixel'.  The last two are useful to provide a 3D
> -effect, or to better distinguish dividers from surrounding display objects.
> +*** Emacs can now change frame sizes pixelwise.
> +When maximizing a frame or making it fullscreen, remaining extra pixels
> +are no more given to the minibuffer, the rightmost fringe, or other
> +unusable space, but are distributed among the text areas of the frame's
> +windows.  The new option `frame-resize-pixelwise', when non-nil, makes
> +all frame size changes happen pixelwise and sets the corresponding size
> +hints for the window manager.
> +
> +---
> +*** Emacs can now change window sizes pixelwise.
> +Mouse-dragging a modeline or window divider now changes the size of
> +adjacent windows pixelwise.  The new option `window-resize-pixelwise',
> +when non-nil, automatically makes functions like `balance-windows-area'
> +or `fit-window-to-buffer' resize windows pixelwise.  Most functions for
> +resizing or accessing sizes of windows now have an additional argument
> +which allows to apply changes or return values in pixels instead of
> +lines/columns.
> +
> +---
> +*** Emacs can now draw dividers between adjacent windows.  To put
> +dividers between side-by-side/vertically stacked windows customize the
> +frame parameters `right-divider-width' and `bottom-divider-width' to
> +some positive integer.  You can drag dividers with the mouse (they show
> +a corresponding cursor when the mouse hovers over them).  You can change
> +the appearance of dividers by customizing the faces `window-divider',
> +`window-divider-first-pixel', and `window-divider-last-pixel'.  The last
> +two are useful to provide a 3D effect, or to better distinguish dividers
> +from surrounding display objects.
> +
> +---
> +*** New functions are provided to return the pixel sizes of window
> +components, namely `window-scroll-bar-width', `window-mode-line-height'
> +`window-header-line-height', `window-right-divider-width' and
> +`window-bottom-divider-width'.
> +
> +---
> +*** The new function `window-text-pixel-size' returns the size of the
> +text of a window's buffer in pixels.  This allows functions like
> +`fit-frame-to-buffer' and `fit-window-to-buffer' to accurately fit a
> +window to its buffer as it will be displayed.
> +
> +---
> +*** `fit-window-to-buffer' can now resize windows horizontally.
> +This behavior is controlled by the new option
> +`fit-window-to-buffer-horizontally'.
> +
> +---
> +*** `fit-frame-to-buffer' can now fit frames in both directions.
> +This behavior is controlled by the option `fit-frame-to-buffer' which
> +tells in which direction(s) the frame shall be fit.  The new options
> +`fit-frame-to-buffer-margins' and `fit-frame-to-buffer-sizes' allow to
> +control the size of the frame and its position on screen.
> +
> +---
> +*** Temp Buffer Resize Mode can now adjust height and width of windows
> +and frames.  `temp-buffer-resize-mode' is now able to adjust the height
> +and the width of a window displaying a temporary buffer.  The new option
> +`temp-buffer-max-width' allows to control the width of temporary buffer
> +windows.  Moreover, if the new option `fit-frame-to-buffer' is non-nil
> +and the buffer appears in the root window of a frame, Temp Buffer Resize
> +Mode will try to adjust width and/or height of the frame.
>  
>  ---
>  *** `split-window' is now a non-interactive function, not a command.
> @@ -210,12 +262,30 @@
>  and as such superfluous.  After being reimplemented in Lisp, its
>  interactive form was mistakenly retained.
>  
> +---
> +*** The functions `window-size' and `window-total-size' now have an
> +optional argument to return a rounded size value.
> +
> +---
> +*** `window-state-put' now allows to put a window state into internal
> +windows too.
> +
>  +++
>  *** New option `scroll-bar-adjust-thumb-portion'.
>  Available only on X, this option allows to control over-scrolling
>  using the scroll bar (i.e. dragging the thumb down even when the end
>  of the buffer is visible).
>  
> +---
> +*** New basic action function `display-buffer-in-previous-window' has
> +`display-buffer' display a buffer in a window previously showing that
> +buffer.
> +
> +---
> +*** New basic action function `display-buffer-at-bottom' has
> +`display-buffer' choose or make a window at the bottom of the selected
> +frame.
> +
>  ** Lisp evaluation changes
>  +++
>  *** `eval-defun' on an already defined defcustom calls the :set function,

Re: trunk r116526: Document some frame and window changes in NEWS.

[martin rudalics]

 > Why did you mark all these NEWS entries with ---?

Elementary.  I thought the --- stands for "a change in the manuals is
needed".  It's a long time that I added something to NEWS (and you
should have already noticed the --- for the dividers entry which is here
for a week at least).  I'll fix it tomorrow.

martin

Re: trunk r116526: Document some frame and window changes in NEWS.

[martin rudalics]

 > Why did you mark all these NEWS entries with ---?

Should be fixed now.  BTW, is "pixelwise" a very bad term?  Should I
generally try to use "in units of pixels" instead?

martin

RE: trunk r116526: Document some frame and window changes in NEWS.

[Drew Adams]

> BTW, is "pixelwise" a very bad term?  Should I
> generally try to use "in units of pixels" instead?

It is not a bad term, depending on what you use it for.
"-wise" means with respect to, concerning, in the manner of,
in the direction of, and so on.  So pixelwise is more general
than just using a pixel as the unit of measure.

So yes, if you want to specify that pixels are used for
measurement then it would be clearer to say "in pixels" or
similar.

Re: trunk r116526: Document some frame and window changes in NEWS.

[Glenn Morris]

martin rudalics wrote:

> BTW, is "pixelwise" a very bad term?

I don't think it's "very bad", no. Is it a standard term?
It's certainly fine for symbol names.

> Should I generally try to use "in units of pixels" instead?

Well, it seemed a bit clearer to me for a NEWS entry is all.