bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Drew Adams]

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''

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Drew Adams]

> 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?).

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Eli Zaretskii]

> Date: Thu, 15 Oct 2020 08:18:25 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 43996@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.

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Eli Zaretskii]

> Date: Wed, 14 Oct 2020 14:11:02 -0700 (PDT)
> From: Drew Adams <drew.adams@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.

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Drew Adams]

> 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?

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Eli Zaretskii]

> Date: Thu, 15 Oct 2020 08:23:48 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 43996@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.

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Stefan Kangas]

tags 43996 + notabug wontfix
close 43996
thanks

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Thu, 15 Oct 2020 08:23:48 -0700 (PDT)
>> From: Drew Adams <drew.adams@oracle.com>
>> Cc: 43996@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.

bug#43996: 26.3; Please document frame parameter `modeline' in the Elisp manual

[Drew Adams]

> > 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.