Subject: RE: doc for recenter, redisplay

From: "Drew Adams" <[email-masked]>
Date: Mon, 1 Sep 2008 11:13:52 -0700

> > I notice that `recenter' has the effect of calling 
> > (redisplay t); that is, it seems to force a redisplay. I don't
> > see this mentioned anywhere. It might be helpful to mention it.
> > We might want to mention it in the Elisp manual node Textual
> > Scrolling, where `recenter' is covered, and also in node
> > Forcing Redisplay, where redisplay is
> > covered (with an xref to Textual Scrolling).
>
> > Users who want to both recenter and redisplay might want to
> > know that `recenter' alone suffices.
>  
> > Users who do not want to force a redisplay might want to
> > know that `recenter' does that.
>  
> 
> In the docstring:
>   
>   If arg is omitted or nil, erase the entire frame and then 
>   redraw with point in the center of the current window.
> 
> In the Emacs manual:
> 
>   It also clears the screen and redisplays all windows; this is useful
>   in case the screen becomes garbled for any reason (*note Screen
>   Garbled::).
> 
> In the Elisp manual:
> 
>   If @var{count} is @code{nil}, @code{recenter} puts the line 
>   containing point in the middle of the window, then clears and
>   redisplays the entire selected frame.
> 
> However, the docstring for recenter-top-bottom (new to Emacs 
> 23) did not mention this; I've updated it accordingly.

OK, thanks.

I was mainly concerned about the redisplay doc in the Elisp manual, where I was
looking for info about functions that can cause redisplay. Could you please also
mention this effect in node Forcing Redisplay (and cross-reference node Textual
Scrolling for more info about `recenter'). Thx.

Reasons (again):

1. You might have a (recenter) in your code and not be able to figure out why or
where redisplay is occurring. Knowing this redisplay effect would help
debugging.

2. You might want to both recenter and redisplay. Looking up `redisplay' in the
manual should let you know that recentering will also cause redisplay.

Also, the Emacs manual (node Scrolling) says that `C-l' redisplays "on a text
terminal". I don't think that restriction is applicable anymore; I think it
redisplays always and everywhere. Perhaps what gets redisplayed is different for
a text terminal? Not sure just what was meant here.

The Scrolling node passage also sends you to node Screen Garbled, which also
speaks only of text terminals. Dunno if that restriction is appropriate there
either, but it is certainly true that `C-l' redisplay can be important for text
terminals (or at least it used to be important).