GNU bug report logs - #43996
26.3; Please document frame parameter `modeline' in the Elisp manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 43996 in the body.
You can then email your comments to 43996 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.3; Please document frame parameter `modeline' in the Elisp manual
Date: Wed, 14 Oct 2020 14:11:02 -0700 (PDT)

Subject line says it all.

I couldn't find where this is used in the Lisp code, so I guess it's
used in C code.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

Message #8 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 43996 <at> debbugs.gnu.org
Subject: Re: bug#43996: 26.3; Please document frame parameter `modeline' in
 the Elisp manual
Date: Thu, 15 Oct 2020 09:27:47 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> Subject line says it all.
>
> I couldn't find where this is used in the Lisp code, so I guess it's
> used in C code.

Where did you happen onto the modeline frame parameter?

Reading the code, it looks like internal bookkeeping, and is always set
on the C level from f->wants_modeline, which again is only set to false
in make_minibuffer_frame.

So it doesn't look like a frame parameter that can be set by the user,
if I'm reading the code correctly, and therefore shouldn't be documented.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #11 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 43996 <at> debbugs.gnu.org
Subject: Re: bug#43996: 26.3;
 Please document frame parameter `modeline' in the Elisp manual
Date: Thu, 15 Oct 2020 16:46:22 +0300

> Date: Wed, 14 Oct 2020 14:11:02 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> Subject line says it all.

No, it doesn't.  Did you actually have a real-life use case where that
parameter was needed and useful to your Lisp program?

> I couldn't find where this is used in the Lisp code, so I guess it's
> used in C code.

This parameter doesn't really exist, it's an illusion.

Message #14 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 43996 <at> debbugs.gnu.org
Subject: RE: bug#43996: 26.3; Please document frame parameter `modeline' in
 the Elisp manual
Date: Thu, 15 Oct 2020 08:18:25 -0700 (PDT)

> Where did you happen onto the modeline frame parameter?

I see it when I invoke function `frame-parameters'.

I don't have it in any of my code.  It must be coming
from Emacs itself.

> Reading the code, it looks like internal bookkeeping, and is always set
> on the C level from f->wants_modeline, which again is only set to false
> in make_minibuffer_frame.

Thanks for that info.  That corresponds to what I
see.  I cannot add a mode-line to a standalone
minibuffer frame, it seems.  See bug #43997 for a
request to be able to do that.

> So it doesn't look like a frame parameter that can be set by the user,
> if I'm reading the code correctly, and therefore shouldn't be documented.

Can't be set, but can be seen.  And you can
_seemingly_ set it.  You get no error or direct
indication that it doesn't get set, when you try
to set it.  So at the very least, its visibility
and apparent setting can mislead/confuse users.
If it were entirely invisible from Lisp, then,
yes, it wouldn't need to be described/explained.

The fact that you can't really set it should
maybe be doc'd.  Or at least the fact that
non-nil means there is a mode-line (or whatever
it really means), and that a standalone
minibuffer frame can't have a mode-line (but
why not?).

Message #17 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 43996 <at> debbugs.gnu.org
Subject: RE: bug#43996: 26.3; Please document frame parameter `modeline' in
 the Elisp manual
Date: Thu, 15 Oct 2020 08:23:48 -0700 (PDT)

> No, it doesn't.  Did you actually have a real-life use case where that
> parameter was needed and useful to your Lisp program?

Maybe.  How to know, without knowing what it does
or is supposed to do?

> > I couldn't find where this is used in the Lisp code, so I guess it's
> > used in C code.
> 
> This parameter doesn't really exist, it's an illusion.

Then could you please remove this "illusion" from what
users see and can manipulate in Lisp?

Message #20 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 43996 <at> debbugs.gnu.org
Subject: Re: bug#43996: 26.3;
 Please document frame parameter `modeline' in the Elisp manual
Date: Thu, 15 Oct 2020 18:46:50 +0300

> Date: Thu, 15 Oct 2020 08:18:25 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 43996 <at> debbugs.gnu.org
> 
> Can't be set, but can be seen.  And you can
> _seemingly_ set it.

You can set a parameter by any name you like.  That's how frame-local
variables are used.  That doesn't mean a name you invent should be
documented.

Message #23 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 43996 <at> debbugs.gnu.org
Subject: Re: bug#43996: 26.3; Please document frame parameter `modeline' in
 the Elisp manual
Date: Thu, 15 Oct 2020 18:49:28 +0300

> Date: Thu, 15 Oct 2020 08:23:48 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 43996 <at> debbugs.gnu.org
> 
> > This parameter doesn't really exist, it's an illusion.
> 
> Then could you please remove this "illusion" from what
> users see and can manipulate in Lisp?

No, it's needed and sometimes useful, but not to readers of the Lisp
Reference manual.

Message #26 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 43996 <at> debbugs.gnu.org
Subject: RE: bug#43996: 26.3; Please document frame parameter `modeline' in
 the Elisp manual
Date: Thu, 15 Oct 2020 09:17:56 -0700 (PDT)

> > Can't be set, but can be seen.  And you can
> > _seemingly_ set it.
> 
> You can set a parameter by any name you like.  That's how frame-local
> variables are used.

Yes, I know.

> That doesn't mean a name you invent should be
> documented.

`modeline' is not a name I invented.  You seem
to be changing the subject.  This is only about
parameter `modeline', not an arbitrary parameter
added by user code.

Message #29 received at 43996 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 43996 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#43996: 26.3; Please document frame parameter `modeline' in
 the Elisp manual
Date: Sat, 25 Sep 2021 08:25:24 -0700

tags 43996 + notabug wontfix
close 43996
thanks

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Thu, 15 Oct 2020 08:23:48 -0700 (PDT)
>> From: Drew Adams <drew.adams <at> oracle.com>
>> Cc: 43996 <at> debbugs.gnu.org
>>
>> > This parameter doesn't really exist, it's an illusion.
>>
>> Then could you please remove this "illusion" from what
>> users see and can manipulate in Lisp?
>
> No, it's needed and sometimes useful, but not to readers of the Lisp
> Reference manual.

OK, that sounds to me like an official maintainer decision that we don't
want to document this parameter in the ELisp manual.

I'm consequently closing this bug report.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.