RE: Rename `mini-' options

RE: Rename `mini-' options

[Davis Herring]

>> This is the first time I encounter something called "mini-windows",
>> but it seems to me, after having read the documentation for the
>> variable, that the minibuffer is an instance of them? Are there any
>> other mini-windows or is this just very poorly documented?
>
> Just poorly named and poorly documented. What is meant is the (active)
> minibuffer window.
>
> There can be more than one minibuffer window, but only one is active at
> any time.

The mini-window is the window that holds the minibuffer, but also the echo
area.  Try evaluating this with `eval-region':

(let (resize-mini-windows)
  (message (make-string 100 100))
  (sit-for 1))

(I didn't bother looking up the order of the arguments to `make-string'. 
100 may be made wider than your frame if you can figure that out. ;)

So: there's a reason for calling it something other than "minibuffer".

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

RE: Rename `mini-' options

[Drew Adams]

> >> This is the first time I encounter something called "mini-windows",
> >> but it seems to me, after having read the documentation for the
> >> variable, that the minibuffer is an instance of them? Are there any
> >> other mini-windows or is this just very poorly documented?
> >
> > Just poorly named and poorly documented. What is meant is 
> > the (active) minibuffer window.
> >
> > There can be more than one minibuffer window, but only one 
> > is active at any time.
> 
> The mini-window is the window that holds the minibuffer,

Nice try ;-). But you're simply making that up.

> but also the echo area.  Try evaluating this with `eval-region':
> (let (resize-mini-windows)
>   (message (make-string 100 100))
>   (sit-for 1))

Yes, of course. The minibuffer and the echo area share the same screen real
estate. But it's not a window - "window" means something specific in Emacs.

Is there a need for some new name to identify that screen area? Maybe, maybe
not. In any case, "mini-window" is not, today, such an identifier. 

There ain't no such definition. Try `M-x apropos mini-'. Search the Emacs manual
for `mini-'. Search the Elisp manual. You will find only these poorly named
variables. Search the manuals and doc strings for "mini window" - nada. 

If we want to discuss whether there should be a name for this common area, we
can. If we finally decide that there should be, then we can discuss what that
name should be. It certainly should not have "window" in it, as that is
misleading. There is no window that corresponds to the echo area: its messages
are not displayed in a window.

Most importantly, to come back to the point: Users will not easily find these
particular options - whether they look for `minibuffer' or `echo-area'.

Re: Rename `mini-' options

[Juanma Barranquero]

On Sat, May 16, 2009 at 04:11, Drew Adams <drew.adams@oracle.com> wrote:

> The minibuffer and the echo area share the same screen real
> estate. But it's not a window - "window" means something specific in Emacs.

Why not?

 -- Function: window-tree &optional frame
     This function returns the window tree for frame FRAME.  If FRAME
     is omitted, the selected frame is used.

     The return value is a list of the form `(ROOT MINI)', where ROOT
     represents the window tree of the frame's root window, and MINI is
     the frame's minibuffer window.

Or are you saying that "the frame's minibuffer window" does not mean
that it is a window?

ELISP> (window-tree)
(#<window 13 on *ielm*> #<window 4 on  *Minibuf-0*>)

ELISP> (windowp (cadr (window-tree)))
t

    Juanma

RE: Rename `mini-' options

[Drew Adams]

> Or are you saying that "the frame's minibuffer window" does not mean
> that it is a window?

I did not say anything about the frame's minibuffer window. And yes, the
minibuffer window is a window.

1. I said that the _echo area_ is not an Emacs window.

2. And that there is currently no such animal called a "mini-window" or a "mini
window".

3. And that using `mini-' in the names of these particular options makes it more
difficult for users to find them.

Point #3 is the real point I raised (see Subject line).
Do you dispute that point?

Re: Rename `mini-' options

[Juanma Barranquero]

On Sat, May 16, 2009 at 04:32, Drew Adams <drew.adams@oracle.com> wrote:

> I did not say anything about the frame's minibuffer window. And yes, the
> minibuffer window is a window.

You said:

> The minibuffer and the echo area share the same screen real
> estate. But it's not a window - "window" means something specific in Emacs.

What is the difference between the frame's minibuffer window, and the
screen real state used by the minibuffer? (Unless you're trying to
imply that the "screen real state" is not a window, because a window
is an Emacs object, which would be handwaving IMO).

> 1. I said that the _echo area_ is not an Emacs window.

> Do you dispute that point?

No. I dispute that you said 1. Because Davis said

 > The mini-window is the window that holds the minibuffer, but also
the echo area

and your answer was:

> Nice try ;-). But you're simply making that up.

As for the other points, the manual says:

   The variable `max-mini-window-height', which specifies the maximum
height for resizing minibuffer windows, also applies to the echo area
(which is really a special use of the minibuffer window.  *Note
Minibuffer Misc::.).

so, on one hand, it is not very difficult to find what is
max-mini-widow-height used for; and, on the other hand, changing it to
max-minibuffer-window-height would obscure the fact that the echo area
is also affected.

    Juanma

RE: Rename `mini-' options

[Drew Adams]

> > I did not say anything about the frame's minibuffer window. 
> > And yes, the minibuffer window is a window.
> 
> You said:
>
> > The minibuffer and the echo area share the same screen real
> > estate. But it's not a window - "window" means something 
> > specific in Emacs.

Yes, I did. The echo area is not an Emacs window. See if `select-window' and
such can handle it. See if the doc ever refers to it as a window. No and no.

> What is the difference between the frame's minibuffer window, and the
> screen real state used by the minibuffer? (Unless you're trying to
> imply that the "screen real state" is not a window, because a window
> is an Emacs object, which would be handwaving IMO).

Not handwaving at all. That is how Emacs has always talked about the echo area -
as an area of the screen where the minibuffer is displayed for input and output
messages are echoed. You will not find it referred to in the doc as a "window".

You will instead see that the doc says that the "line at the very bottom of the
frame is the `echo area'". And that "The echo area is also used to display the
"minibuffer", a special window..." And that "At the very bottom of the frame is
a special `echo area', where short informative messages are displayed and where
you enter information when Emacs asks for it."

And the Elisp manual: "The `echo-area' is used for displaying error messages...
It is not the same as the minibuffer, despite the fact
that the minibuffer appears (when active) in the same place on the
screen as the echo area."

The Elisp manual says that the echo area and the minibuffer appear in the same
place - without naming that place. The Emacs manual calls that place the "echo
area" - an area at the bottom of the screen. 

There is thus some minor terminology mismatch between the two manuals, but
neither refers to that area as a "window", AFAIK - they both call it an "area"
of the screen, avoiding the term "window". That area is sometimes used to
_display_ a window, the minibuffer window. But certainly not the echo-area
window.

> > 1. I said that the _echo area_ is not an Emacs window.
> > Do you dispute that point?
> 
> No. I dispute that you said 1.

Here's exactly what I said: "But it's not a window - `window' means something
specific in Emacs." And "it" refers here to the echo area. I clearly said that
the echo area is not an Emacs window. On what basis do you dispute that?

> Because Davis said
>  > The mini-window is the window that holds the minibuffer, but also
>  > the echo area
> and your answer was:
> 
> > Nice try ;-). But you're simply making that up.

Yes, making up the term "mini-window". You will not find it anywhere in the doc.

That doesn't imply that I never said that the echo area is not a window.

> As for the other points, the manual says:
> 
> The variable `max-mini-window-height', which specifies the maximum
> height for resizing minibuffer windows, also applies to the echo area
> (which is really a special use of the minibuffer window.  *Note
> Minibuffer Misc::.).

I disagree with that characterization. Perhaps it was written by the same person
who coined those unhelpful option names - I don't know. Based on what I quoted
above from the Emacs manual, you might say that the minibuffer is a special use
of the echo area, but not the other way around. (The Elisp manual would say that
they are both special uses of a special, unnamed area at the bottom of the
screen.)

See the Emacs manual, where it actually introduces and _defines_ the term, which
I quoted above. What you quoted is just the description of the very option whose
terminology is in question! Did the same person write that doc and name the
option?

> so, on one hand, it is not very difficult to find what is
> max-mini-widow-height used for;

What is more difficult than it should be is _finding_ the options that control
resizing of the minibuffer and its height. Completion, `apropos', and other
common search tools won't help you, as I pointed out.

It doesn't matter whether you're looking for an option that controls the
minibuffer height or the echo area height - looking for either `minibuffer' or
`echo-area' in the option name will not find it.

> and, on the other hand, changing it to max-minibuffer-window-height
> would obscure the fact that the echo area is also affected.

The doc string can explain exactly what is affected, as precisely as you like.
The point of having a useful name is to help users find the critter in the first
place.

I personally would have no objection to either aliasing a name that contains
`echo-area' or even having a long name that contains both `minibuffer' and
`echo-area'. (There are several variables whose names contain `echo-area' - see
the Elisp manual, node Echo Area Customization.)

Neither of those approaches would be my preference, however - I don't think
that's necessary, but I recognize that someone could make the same argument for
trying to find options that affect the echo area height, so I concede that
putting `echo-area' in the name could help. I don't concede that `mini-' helps
someone find an option that affects the echo area.

I made a simple proposal to rename a couple of options. You apparently just want
to argue in circles about what I said or didn't say.

Re: Rename `mini-' options

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 15 May 2009 21:20:54 -0700
> Cc: emacs-devel@gnu.org, 'Deniz Dogan' <deniz.a.m.dogan@gmail.com>

Let me say up front that I don't object to have variables whose names
include ``minibuffer'' rather than ``mini'', if that makes someone
happy.  We could add aliases to the currently-named variables, which
should be harmless even at this late stage of the pretest.  We could
also add index entries in the manuals, which is even less harmful,
just to ease searching for them.

But that issue aside, I would like to everybody be on the right page
regarding whether echo are is or isn't a window.

> > You said:
> >
> > > The minibuffer and the echo area share the same screen real
> > > estate. But it's not a window - "window" means something 
> > > specific in Emacs.
> 
> Yes, I did. The echo area is not an Emacs window. See if `select-window' and
> such can handle it. See if the doc ever refers to it as a window. No and no.

You are wrong.  Maybe the documentation is misleading or inaccurate,
but the echo area is indeed just a special use of the minibuffer
window.  This fact is clearly visible from the C code that is the
infrastructure for displaying text in the echo area.  The following
snippet is from xdisp.c:echo_area_display:

  struct frame *sf = SELECTED_FRAME ();

  mini_window = FRAME_MINIBUF_WINDOW (sf);
  w = XWINDOW (mini_window);

  [...]

      echo_area_window = mini_window;
      window_height_changed_p = display_echo_area (w);
      w->must_be_updated_p = 1;

In plain English, this does the following:

  . finds the currently selected frame
  . then gets the minibuffer window used by that frame
  . and finally, uses that window to display the echo area contents

(For people who are not fluent in reading Emacs C sources: mini_window
and w are two ways of specifying the same window: the former is a Lisp
object that refers to the minibuffer window, the latter is a pointer
to a C data structure which specifies that same window.  The macro
XWINDOW takes a Lisp object for a window and returns a C pointer for
that window.)

So, not only is the echo area using the minibuffer window on the
selected frame, there's also a Lisp object, called echo_area_window,
which specifies that window as long as it is in use.  Which means
that, if the need arises, we could have a Lisp-level binding for that
object, and then Lisp programs could use it in many ways like any
other window.

It is true that this window is special in many ways, which could
explain why the documentation is so vague about it.  But please don't
claim with such certainty that it's not a window, because that's
simply false.

RE: Rename `mini-' options

[Drew Adams]

> Let me say up front that I don't object to have variables whose names
> include ``minibuffer'' rather than ``mini'', if that makes someone
> happy.  We could add aliases to the currently-named variables, which
> should be harmless even at this late stage of the pretest.  We could
> also add index entries in the manuals, which is even less harmful,
> just to ease searching for them.

Good. That was all I proposed. Let's do that.

The rest of this discussion is accessory - a related but separate topic.

> You are wrong.  Maybe the documentation is misleading or inaccurate,

The doc plus the UI (names the user sees) are all that I spoke about. I am not
wrong about those. You are apparently saying in fact that the doc and UI are
wrong, that they do not faithfully reflect the internals of the product.

You go on to show that the doc and UI do not correspond to what actually happens
in the C internals, in the sense that there is a C code entity with "echo" and
"area" in its name, and that is associated with the minibuffer window.

That may be, but it is irrelevant here, unless we decide that the user's mental
model should correspond more faithfully with the implementation (in fact, with
that part of the implementation that s?he does not see directly when interacting
with Emacs: C code).

If we decide that, then the doc and UI names need to be changed, to teach users
a model that better reflects what the implementation actually does. The question
is what model to present to the users: what do they need, to understand all of
the _behavior that they can see_. User-observable behavior is the key to
defining a helpful conceptual model for the user.

The implementation is an aid in doing that, but it is not the guide. The guide
is the user's point of view and what s?he can actually do and see when
interacting with the program.

If the echo area window that you refer to in the C code is something that the
user cannot observe and interact with - e.g. s?he cannot treat it as an Emacs
window, then perhaps it should not be part of the user's mental model. I'm no
expert on whether that is the case - you decide.

The idea, as always, is to come up with a conceptual model for the user that
reflects (preferably all) _user observable_ behavior. User models reflect
implementations, but they generally abstract from what the user cannot see or
touch. I would suggest limiting the meaning of "observable", for Emacs, to what
users experience interactively and by using Lisp.

> but the echo area is indeed just a special use of the minibuffer
> window.  This fact is clearly visible from the C code that is the
> infrastructure for displaying text in the echo area.  The following
> snippet is from xdisp.c:echo_area_display:
>...
> In plain English, this does the following:
>   . finds the currently selected frame
>   . then gets the minibuffer window used by that frame
>   . and finally, uses that window to display the echo area contents
>...
> So, not only is the echo area using the minibuffer window on the
> selected frame, there's also a Lisp object, called echo_area_window,
> which specifies that window as long as it is in use.  Which means
> that, if the need arises, we could have a Lisp-level binding for that
> object, and then Lisp programs could use it in many ways like any
> other window.
> 
> It is true that this window is special in many ways, which could
> explain why the documentation is so vague about it.  But please don't
> claim with such certainty that it's not a window, because that's
> simply false.

So the documentation is misleading, and has been so since Day 1, in particular
in the very places where it introduces (defines) these concepts - I cited the
relevant sections, in case you want to correct them.

However, that said, the question remains of how this should be presented to
users conceptually. You had recourse to the C code, admitting that the echo area
window is not currently Lisp-accessible. That is, you cannot use it as a window
from Lisp (which confirms what I said).

As long as this internal, special window is not available to (Lisp) users,
should we even introduce it at all, to become part of the user's conceptual
model? That's a choice to be made. Currently, the doc does not present it that
way at all. The "echo area" in the doc is a different animal altogether from the
`echo_area_window' C variable, even though the names are similar.

If we choose not to introduce the concept of an echo area _window_, that is, if
we continue the current (doc) approach, then there is still the question whether
to say that the echo area borrows the minibuffer window or, as is said
currently, that the minibuffer window is displayed in the "screen area" that
either (a) is known as the "echo area" (Emacs manual) or (b) has the same
location as the echo area (Elisp manual).

Re: Rename `mini-' options

[Juanma Barranquero]

On Sat, May 16, 2009 at 06:20, Drew Adams <drew.adams@oracle.com> wrote:

> I made a simple proposal to rename a couple of options. You apparently just want
> to argue in circles about what I said or didn't say.

Miles and Eli have already explained why you were wrong. If
disagreeing with you when you strongly defend mistakes is arguing in
circles, so be it.

    Juanma

Re: Rename `mini-' options

[Stephen J. Turnbull]

Juanma Barranquero writes:

 > so, on one hand, it is not very difficult to find what is
 > max-mini-widow-height used for; and, on the other hand, changing it to
 > max-minibuffer-window-height would obscure the fact that the echo area
 > is also affected.

So does max-mini-window-height.  And as your own words and the
existing documentation which you quote demonstrate:

 jb> What is the difference between the frame's minibuffer window, and the
 jb> screen real state used by the minibuffer?

 doc>    The variable `max-mini-window-height', which specifies the maximum
 doc> height for resizing minibuffer windows, also applies to the echo area
 doc> (which is really a special use of the minibuffer window.  *Note
 doc> Minibuffer Misc::.).

the name of the window in question is "minibuffer window".

Drew is right.  It is inconsistent with existing practice, and
confuses something that is already rife with possibilities for
confusion.  And "mini-window" strongly suggests a new class of "small
window" objects, which doesn't exist.  There is precedent in the
3d-party resize-minibuffer mode, where the following names already
exist:

 * resize-minibuffer-frame-max-height - Maximum size the minibuffer
                                    frame is allowed to become. 
 * resize-minibuffer-idle-height  - When minibuffer is idle, crop its
                                    window to this height. 
 * resize-minibuffer-window-max-height - Maximum size the minibuffer
                                    window is allowed to become. 

Please fix the "mini-" names.

Re: Rename `mini-' options

[Miles Bader]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
> the name of the window in question is "minibuffer window".

Er, except that it's not.

For better or worse, Emacs traditionally distinguishes "the minibuffer"
from "the echo area", and resize-mini-windows applies to both.  So a
name which captures this subtlety is arguably better than one which lies
a bit for the sake of convenient document searching.

> Drew is right.  It is inconsistent with existing practice, and
> confuses something that is already rife with possibilities for
> confusion.

The variable in question _is_ existing practice -- it was introduced
almost a decade ago, in Emacs 21.

> There is precedent in the 3d-party resize-minibuffer mode, where the
> following names already exist:

That (long obsolete) mode does something _different_ than
resize-mini-windows:  it only applies to the minibuffer.  Thus even if
referring to "minibuffer-window" makes sense for that mode, that doesn't
mean it makes sense for Emacs' builtin behavior.

[I suppose you could argue against the "echo area"/"minibuffer" split,
and say we should just refer to them both as "the minibuffer"
(or whatever), but that's a different argument (and certainly not
something that should happen right now, as it's a big change).]

-Miles

-- 
Education, n. That which discloses to the wise and disguises from the foolish
their lack of understanding.

RE: Rename `mini-' options

[Drew Adams]

> For better or worse, Emacs traditionally distinguishes "the 
> minibuffer" from "the echo area", and resize-mini-windows
> applies to both.  So a name which captures this subtlety
> is arguably better than one which lies
> a bit for the sake of convenient document searching.

And the name `resize-mini-windows' captures this subtlety just how? Is it
because it cleverly doesn't mention _either_ the minibuffer or the echo area?
That's supposed to help somehow?

You heard it from user Deniz: "Unless I had read your post I never would have
guessed `resize-mini-windows' deals with the minibuffer at all." Case closed.
(Or it should be.) Never would have guessed at all! Even with the name looking
us in the face - let alone the problem of finding that name in the first place.

As I said, use something like `minibuffer-echo-area-resize', if you're concerned
about "capturing the subtlety" that this option applies to both. I have no
problem with that. There's no need to "lie a bit".

Finding options and functions by name is important, and that is not just about
searching the doc. This is why `apropos' works as well as it does - conventional
naming.

> The variable in question _is_ existing practice -- it was introduced
> almost a decade ago, in Emacs 21.

There are lots of things introduced a while ago that could still merit
improvement.

The more important point is that this is an _exception_ to the rest of the
"existing practice". No where else does `mini-' occur. And it remains
unexplained, undocumented.

This is just a bug, no matter how long ago it was introduced. And in the grand
scheme of Emacs terminology, Emacs 21 is a relative newcomer. The terminology of
`minibuffer' and `echo area' have been with us since Day 1.

I apologize for not catching this bug sooner. (I don't use such resizing, myself
- I  use a standalone minibuffer frame, with my own resizing code for that.)

Re: Rename `mini-' options

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
>> For better or worse, Emacs traditionally distinguishes "the
>> minibuffer" from "the echo area", and resize-mini-windows applies to
>> both.  So a name which captures this subtlety is arguably better than
>> one which lies a bit for the sake of convenient document searching.
>
> And the name `resize-mini-windows' captures this subtlety just how? Is
> it because it cleverly doesn't mention _either_ the minibuffer or the
> echo area?  That's supposed to help somehow?

Sure.  If no existing term captures a concept, then it seems a
reasonable argument that it's better to make a new term than use an
incorrect one.

Of course, it's not always to come up with a good term, but I'm not sure
what other term would be better.  The terms you suggested are pithy, but
seem inaccurate.

Maybe it's better to just declare that "minibuffer-window" always
includes the echo-area, but it's not clear to me whether this would run
into other conflicts or not (e.g. uses of that term that really only
intend to refer to the minibuffer's window).

> The more important point is that this is an _exception_ to the rest of
> the "existing practice". No where else does `mini-' occur.

Eh?  An "exception" to _what_ existing practice?  Are there other
variables/functions which control both echo-area and the minibuffer
display, which use some other term than "mini-window"?

> And it remains unexplained, undocumented.

Perhaps the documentation could use improvement of course.

Indeed, that seems like the most reasonable solution to this issue
(certainly in the short term):  Make sure these variables are mentioned
in every place where they should be; in the end (while apropos is very
convenient, it's not a replacement for the real documentation).

> I apologize for not catching this bug sooner.

It's not a bug, of course.

-Miles

-- 
Any man who is a triangle, has thee right, when in Cartesian Space,
to have angles, which when summed, come to know more, nor no less,
than nine score degrees, should he so wish.  [TEMPLE OV THEE LEMUR]

RE: Rename `mini-' options

[Drew Adams]

> >> For better or worse, Emacs traditionally distinguishes "the
> >> minibuffer" from "the echo area", and resize-mini-windows 
> >> applies to both.  So a name which captures this subtlety is
> >> arguably better than one which lies a bit for the sake of
> >> convenient document searching.
> >
> > And the name `resize-mini-windows' captures this subtlety 
> > just how? Is it because it cleverly doesn't mention _either_
> > the minibuffer or the echo area?  That's supposed to help somehow?
> 
> Sure.  If no existing term captures a concept, then it seems a
> reasonable argument that it's better to make a new term than use an
> incorrect one.

But no such new term was ever introduced (defined). If I simply refer in passing
to the throndolt, have I helped you understand what a throndolt is?

Same thing for `mini-window'. Just using the term does not introduce it; it does
not "capture the concept". Of course, with enough use of the term, one might be
able to figure it out, even without an explicit definition.

But that is not the case here. The doc string talks only about resizing
`mini-windows', without ever giving a clue what a `mini-window' is. Might as
well talk about resizing `thronbolts'.

> Of course, it's not always to come up with a good term, but 
> I'm not sure what other term would be better.  The terms you
> suggested are pithy, but seem inaccurate.

You seem to be confusing two different things, under the slippery rubrique of
"come up with a good term":

1. Introducing a new term altogether, which really requires defining it, giving
some explanation of what `mini-window' refers to.

2. Combining existing defined terms into a phrase term:
`minibuffer-echo-area-resize' is a "new term", but it's meaning is guessable
from its known components `minibuffer' and `echo-area'.

As Deniz pointed out, he would never have guessed that `resize-mini-windows' had
_anything to do_ with the minibuffer.

Besides that, how is `minibuffer-echo-area-resize' inaccurate?

> Maybe it's better to just declare that "minibuffer-window" always
> includes the echo-area, but it's not clear to me whether this 
> would run into other conflicts or not (e.g. uses of that term
> that really only intend to refer to the minibuffer's window).

I don't want to get involved in that discussion, at least not at this point. I'd
simply advise to be careful what you bite off, to be sure you really want to
chew and digest it all. There are many, many references to the minibuffer, its
features, and how to use them. And many of those simply do not apply to the echo
area. And, to a lesser extent, vice versa, there are references to the echo area
that don't apply to the minibuffer.

Even if the two concepts have a window (or screen area or whatever) in common,
that doesn't mean they are not distinct concepts.

Until now, it has been relatively simple to understand the model we present to
the user: the minibuffer reads some user input; the echo area displays some
output. That will become quite a bit more complicated if you conflate the two,
or even just the windows.

You will probably need to introduce two modes for this unified thingy: input
mode (with completion or other `read' properties) and output mode. IOW, you
might decide to conflate the windows, but most uses of those windows will need
to remain distinct. The minibuffer and the echo area as we now understand them
will come back, in one guise or another.

Most importantly, if you really want to change the doc and UI terminology and
presentation, then we should _start_ by deciding just what the user needs to
understand about this (conceptual model), and _then_ decide on a terminology
that fits that. We should not start by changing the language here and there,
without knowing what model/concepts we are trying to introduce with that
language change.

> Perhaps the documentation could use improvement of course.
> 
> Indeed, that seems like the most reasonable solution to this issue
> (certainly in the short term):  Make sure these variables are 
> mentioned in every place where they should be; in the end (while
> apropos is very convenient, it's not a replacement for the real 
> documentation).

If you are reading the doc about the minibuffer or the echo area, and these
options are mentioned there, then you will understand them. No problem. That's
already the case today. That's not the point.

(We can perhaps add index entries to help you find such doc passages easier
(e.g. when looking for `echo area' - `minibuffer' is already well indexed for
resizing).)

But if you are looking for such an option outside the manual, you should be able
to find it easily using `C-h v' (with completion) or `apropos'. That's where
aliases could help. `apropos', in particular, is perhaps the best tool we have
for finding symbols based on parts of their names. (Well, second best, after
Icicles ;-).)

Even `apropos-documentation' won't help here, because the doc string refers only
to the unexplained term `mini-windows', never mentioning `minibuffer' or `echo
area'. IOW, neither the option name nor its doc string provides useful
information about what the option is for.

Re: Rename `mini-' options

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> But that is not the case here. The doc string talks only about resizing
> `mini-windows', without ever giving a clue what a `mini-window' is. Might as
> well talk about resizing `thronbolts'.

Sorry, that's not true.  "mini-window" is hardly an inspired term, but
despite being kind of ad-hoc, it's not a random word, and that makes a
big difference.  When I first saw that variable, I instantly realized
what it probably meant.

[exactly why, I dunno -- maybe it's because "mini" ~= "minibuffer", and
hey, "-window", so it's that window... maybe it's just because
"mini-window" suggests a very small window, let's see... what on my
display is a very small window ... aha! -- anyway regardless of the
thought process, it worked on me.]

Now, maybe you were completely confused by those variable names, I
dunno, but I agree that if we can find a better terminology that makes
everybody happy, great!

>> Of course, it's not always to come up with a good term, but 
>> I'm not sure what other term would be better.  The terms you
>> suggested are pithy, but seem inaccurate.
>
> how is `minibuffer-echo-area-resize' inaccurate?

That's not the term you suggested; you said, in your original message:

> It would have been sufficient, if the name length were so important, to use
> `minibuffer-resize' or `minibuf-auto-resize'. Similarly,
> `minibuffer-max-height'. And `minibuffer' should probably come first in the
> name: `minibuffer-resize', not `resize-minibuffer'.

Such terms are inaccurate because they just say "minibuffer", which is a
something different -- a _minibuffer_ is the actual editable thingie
that is involved in user input.

That's why "minibuffer-window" is better:  it doesn't refer to
minibuffers per-se, but rather to the window used to display them, which
is something different.

-Miles

-- 
"She looks like the wax version of herself."
     	   	    		   [Comment under a Paris Hilton fashion pic]

Re: Rename `mini-' options

[Stephen J. Turnbull]

Miles Bader writes:

 > The variable in question _is_ existing practice -- it was introduced
 > almost a decade ago, in Emacs 21.

OK, then fix the docs to explain the difference between "mini-window"
and "minibuffer window", and use the concept appropriately.

But this is another case where I'm glad that XEmacs hasn't kept up to
GNU Emacs "existing practice".  I think it's perfectly reasonable to
document the echo area as "borrowing" the minibuffer window, rather
than creating a new concept of "mini-windows" (which don't actually
exist, anyway).

 > That (long obsolete) mode does something _different_ than
 > resize-mini-windows:  it only applies to the minibuffer.

Actually, it doesn't.  At least in the XEmacs implementation, the echo
area really does borrow the minibuffer window, so to the extent that
the minibuffer expansion persists (which it normally does, as
repetitions of similar long prompts etc. are common), so does the echo
area.  There were also some fragile hacks that allowed the echo area
to expand as well.

 > Thus even if referring to "minibuffer-window" makes sense for that
 > mode, that doesn't mean it makes sense for Emacs' builtin behavior.

Maybe not.  I think that says more about your sense of "sense" than it
does about Drew's proposal, though. :-)

 > [I suppose you could argue against the "echo area"/"minibuffer" split,
 > and say we should just refer to them both as "the minibuffer"
 > (or whatever), but that's a different argument (and certainly not
 > something that should happen right now, as it's a big change).]

My point, and Drew's, is that as far as the *window* goes, that *is*
existing practice.  Even the documentation of the *-mini-* functions
refers to the "minibuffer window", not to the "mini-window", and so do
you long-time developers.

Re: Rename `mini-' options

[Stefan Monnier]

>> the name of the window in question is "minibuffer window".
> Er, except that it's not.
> For better or worse, Emacs traditionally distinguishes "the minibuffer"
> from "the echo area", and resize-mini-windows applies to both.  So a
> name which captures this subtlety is arguably better than one which lies
> a bit for the sake of convenient document searching.

Actually, we very often refer to this window as "minibuffer window".
E.g. C-h f window-minibuffer-p RET says:

	Return non-nil if WINDOW is a minibuffer window.
	WINDOW defaults to the selected window.

So while this name might not be perfect, it's not that terrible and has
been in use for a while, so we may as well declare it official.


        Stefan

Rename `mini-' options

[Drew Adams]

Names such as `resize-mini-windows' and `max-mini-window-height' are
unfortunate. They prevent you from easily finding them by looking for names that
include `minibuffer' or even `minibuf'.
 
Since when did `mini' start being used in option etc. names to stand for the
minibuffer? The only variable names with `mini-' are these two plus
`kmacro-step-edit-mini-window-height'. Obviously, given the last of these, the
name length is not of supreme importance. And there are *no* functions with
`mini-' in their names.

It would have been sufficient, if the name length were so important, to use
`minibuffer-resize' or `minibuf-auto-resize'. Similarly,
`minibuffer-max-height'. And `minibuffer' should probably come first in the
name: `minibuffer-resize', not `resize-minibuffer'.
 
We should change the names of the `mini-' window options and use temporary
aliases to ease deprecation of those names.

Re: Rename `mini-' options

[Deniz Dogan]

2009/5/15 Drew Adams <drew.adams@oracle.com>:
> Names such as `resize-mini-windows' and `max-mini-window-height' are
> unfortunate. They prevent you from easily finding them by looking for names that
> include `minibuffer' or even `minibuf'.
>
> Since when did `mini' start being used in option etc. names to stand for the
> minibuffer? The only variable names with `mini-' are these two plus
> `kmacro-step-edit-mini-window-height'. Obviously, given the last of these, the
> name length is not of supreme importance. And there are *no* functions with
> `mini-' in their names.
>
> It would have been sufficient, if the name length were so important, to use
> `minibuffer-resize' or `minibuf-auto-resize'. Similarly,
> `minibuffer-max-height'. And `minibuffer' should probably come first in the
> name: `minibuffer-resize', not `resize-minibuffer'.
>
> We should change the names of the `mini-' window options and use temporary
> aliases to ease deprecation of those names.

Unless I had read your post I never would have guessed
`resize-mini-windows' deals with the minibuffer at all.

resize-mini-windows is a variable defined in `C source code'.
Its value is grow-only

Documentation:
*How to resize mini-windows.
A value of nil means don't automatically resize mini-windows.
A value of t means resize them to fit the text displayed in them.
A value of `grow-only', the default, means let mini-windows grow
only, until their display becomes empty, at which point the windows
go back to their normal size.

This is the first time I encounter something called "mini-windows",
but it seems to me, after having read the documentation for the
variable, that the minibuffer is an instance of them? Are there any
other mini-windows or is this just very poorly documented?

Deniz Dogan

RE: Rename `mini-' options

[Drew Adams]

> Unless I had read your post I never would have guessed
> `resize-mini-windows' deals with the minibuffer at all.
> 
> resize-mini-windows is a variable defined in `C source code'.
> Its value is grow-only
> 
> Documentation:
> *How to resize mini-windows.
> A value of nil means don't automatically resize mini-windows.
> A value of t means resize them to fit the text displayed in them.
> A value of `grow-only', the default, means let mini-windows grow
> only, until their display becomes empty, at which point the windows
> go back to their normal size.
> 
> This is the first time I encounter something called "mini-windows",
> but it seems to me, after having read the documentation for the
> variable, that the minibuffer is an instance of them? Are there any
> other mini-windows or is this just very poorly documented?

Just poorly named and poorly documented. What is meant is the (active)
minibuffer window.

There can be more than one minibuffer window, but only one is active at any
time.