GNU bug report logs -
#57890
28.1; Doc string of `initial-frame-alist'
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Sat, 17 Sep 2022 22:23:02 UTC
Severity: minor
Found in version 28.1
Fixed in version 29.1
Done: Lars Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 57890 in the body.
You can then email your comments to 57890 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sat, 17 Sep 2022 22:23:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Drew Adams <drew.adams <at> oracle.com>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Sat, 17 Sep 2022 22:23:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
The doc string seems to suggest that the option, or its use, somehow
depends on X resources:
... If you want the initial frame
to have the proper geometry as soon as it appears, you need to
use this three-step process:
* Specify X resources to give the geometry you want.
* Set 'default-frame-alist' to override these options so that they
don't affect subsequent frames.
* Set 'initial-frame-alist' in a way that matches the X resources,
to override what you put in 'default-frame-alist'.
That text is not introduced by anything saying, e.g., IF you are
using X resources or by saying that this 3-step process is
applicable only if you can use X resources. At least some of it
doesn't make sense without X resources, AFAIK.
The coverage in the Emacs and Elisp manuals seems OK - doesn't present
this problem/confusion.
In GNU Emacs 28.1 (build 2, x86_64-w64-mingw32)
of 2022-04-21 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19044
System Description: Microsoft Windows 10 Pro (v10.0.2009.19044.1889)
Configured using:
'configure --with-modules --without-dbus --with-native-compilation
--without-compress-install CFLAGS=-O2'
Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB
(NATIVE_COMP present but libgccjit not available)
Important settings:
value of $LANG: ENU
locale-coding-system: cp1252
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 05:39:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 57890 <at> debbugs.gnu.org (full text, mbox):
> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Sat, 17 Sep 2022 22:22:05 +0000
>
> The doc string seems to suggest that the option, or its use, somehow
> depends on X resources:
And it does. So I don't understand the complaint.
> That text is not introduced by anything saying, e.g., IF you are
> using X resources or by saying that this 3-step process is
> applicable only if you can use X resources. At least some of it
> doesn't make sense without X resources, AFAIK.
Doc strings are not nodes in a manual, they cannot have introductions
and terminology explanations. They are succinct and assume some level
of general knowledge.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 10:50:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 57890 <at> debbugs.gnu.org (full text, mbox):
Drew Adams <drew.adams <at> oracle.com> writes:
> The doc string seems to suggest that the option, or its use, somehow
> depends on X resources:
>
> ... If you want the initial frame
> to have the proper geometry as soon as it appears, you need to
> use this three-step process:
> * Specify X resources to give the geometry you want.
> * Set 'default-frame-alist' to override these options so that they
> don't affect subsequent frames.
> * Set 'initial-frame-alist' in a way that matches the X resources,
> to override what you put in 'default-frame-alist'.
>
> That text is not introduced by anything saying, e.g., IF you are
> using X resources or by saying that this 3-step process is
> applicable only if you can use X resources. At least some of it
> doesn't make sense without X resources, AFAIK.
And isn't this advice outdated now anyway? The easiest way to specify
initial-frame-alist is to adjust it in `early-init-file', I think?
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 11:12:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 57890 <at> debbugs.gnu.org (full text, mbox):
Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> And isn't this advice outdated now anyway? The easiest way to specify
> initial-frame-alist is to adjust it in `early-init-file', I think?
But that way it is impossible to have different geometries according to
the display or screen in use.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 11:22:01 GMT)
Full text and
rfc822 format available.
Message #17 received at 57890 <at> debbugs.gnu.org (full text, mbox):
Po Lu <luangruo <at> yahoo.com> writes:
>> And isn't this advice outdated now anyway? The easiest way to specify
>> initial-frame-alist is to adjust it in `early-init-file', I think?
>
> But that way it is impossible to have different geometries according to
> the display or screen in use.
That's true. So I think the thing to do here is to prepend the existing
text with "if you're using X" like Drew suggested, but also mention
`early-init-file'.
So I've now done that in Emacs 29.
bug marked as fixed in version 29.1, send any further explanations to
57890 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com>
Request was from
Lars Ingebrigtsen <larsi <at> gnus.org>
to
control <at> debbugs.gnu.org
.
(Sun, 18 Sep 2022 11:22:02 GMT)
Full text and
rfc822 format available.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 12:00:02 GMT)
Full text and
rfc822 format available.
Message #22 received at 57890 <at> debbugs.gnu.org (full text, mbox):
Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> That's true. So I think the thing to do here is to prepend the existing
> text with "if you're using X" like Drew suggested, but also mention
> `early-init-file'.
LGTM, thanks.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 16:09:02 GMT)
Full text and
rfc822 format available.
Message #25 received at 57890 <at> debbugs.gnu.org (full text, mbox):
> > The doc string seems to suggest that the option, or its use, somehow
> > depends on X resources:
>
> And it does. So I don't understand the complaint.
Complaint?
It depends on X resources if you have X resources.
I'm on MS Windows, for example. Nothing about X
resources is relevant to `initial-frame-list' on
that platform, IIUC.
It's fine to mention platform or other non-Emacs
features in the doc string. But just make clear
that that's what they are. E.g., "IF...".
> > That text is not introduced by anything saying, e.g., IF you are
> > using X resources or by saying that this 3-step process is
> > applicable only if you can use X resources. At least some of it
> > doesn't make sense without X resources, AFAIK.
>
> Doc strings are not nodes in a manual, they cannot have introductions
> and terminology explanations. They are succinct and assume some level
> of general knowledge.
Yes. And? This doc string includes platform-specific
info without saying that's what it is, no?
If you want to make it more succinct, and leave
out that X resources info, that's also a way to
remedy the confusion.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 16:17:02 GMT)
Full text and
rfc822 format available.
Message #28 received at 57890 <at> debbugs.gnu.org (full text, mbox):
> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "57890 <at> debbugs.gnu.org" <57890 <at> debbugs.gnu.org>
> Date: Sun, 18 Sep 2022 16:08:03 +0000
>
> > > The doc string seems to suggest that the option, or its use, somehow
> > > depends on X resources:
> >
> > And it does. So I don't understand the complaint.
>
> Complaint?
>
> It depends on X resources if you have X resources.
> I'm on MS Windows, for example. Nothing about X
> resources is relevant to `initial-frame-list' on
> that platform, IIUC.
That is incorrect, see the node "MS-Windows Registry" in the Emacs
user manual (the last paragraph thereof).
> > > That text is not introduced by anything saying, e.g., IF you are
> > > using X resources or by saying that this 3-step process is
> > > applicable only if you can use X resources. At least some of it
> > > doesn't make sense without X resources, AFAIK.
> >
> > Doc strings are not nodes in a manual, they cannot have introductions
> > and terminology explanations. They are succinct and assume some level
> > of general knowledge.
>
> Yes. And? This doc string includes platform-specific
> info without saying that's what it is, no?
It assumes that every user knows enough to understand that.
> If you want to make it more succinct, and leave
> out that X resources info, that's also a way to
> remedy the confusion.
Yes. Another effective method is to close this bug.
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#57890
; Package
emacs
.
(Sun, 18 Sep 2022 17:06:01 GMT)
Full text and
rfc822 format available.
Message #31 received at 57890 <at> debbugs.gnu.org (full text, mbox):
> Sent: Monday, September 19, 2022 at 4:16 AM
> From: "Eli Zaretskii" <eliz <at> gnu.org>
> To: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: 57890 <at> debbugs.gnu.org
> Subject: bug#57890: 28.1; Doc string of `initial-frame-alist'
>
> > From: Drew Adams <drew.adams <at> oracle.com>
> > CC: "57890 <at> debbugs.gnu.org" <57890 <at> debbugs.gnu.org>
> > Date: Sun, 18 Sep 2022 16:08:03 +0000
> >
> > > > The doc string seems to suggest that the option, or its use, somehow
> > > > depends on X resources:
> > >
> > > And it does. So I don't understand the complaint.
> >
> > Complaint?
> >
> > It depends on X resources if you have X resources.
> > I'm on MS Windows, for example. Nothing about X
> > resources is relevant to `initial-frame-list' on
> > that platform, IIUC.
>
> That is incorrect, see the node "MS-Windows Registry" in the Emacs
> user manual (the last paragraph thereof).
>
> > > > That text is not introduced by anything saying, e.g., IF you are
> > > > using X resources or by saying that this 3-step process is
> > > > applicable only if you can use X resources. At least some of it
> > > > doesn't make sense without X resources, AFAIK.
> > >
> > > Doc strings are not nodes in a manual, they cannot have introductions
> > > and terminology explanations. They are succinct and assume some level
> > > of general knowledge.
If users are telling you that the information is not helping them, because of
confusion in terminology or certain knowledge, the docstring should certainly
start to say no, so users can be directed on the kind of information they would
likely need to know.
The biggest problem I see, is that at times, too much knowledge is assumed, making
the docstring info practically useless. Docstrings got to become more pragmatic.
> > Yes. And? This doc string includes platform-specific
> > info without saying that's what it is, no?
>
> It assumes that every user knows enough to understand that.
>
>
> > If you want to make it more succinct, and leave
> > out that X resources info, that's also a way to
> > remedy the confusion.
>
> Yes. Another effective method is to close this bug.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Mon, 17 Oct 2022 11:24:09 GMT)
Full text and
rfc822 format available.
This bug report was last modified 1 year and 183 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.