* bug#57890: 28.1; Doc string of `initial-frame-alist'
@ 2022-09-17 22:22 Drew Adams
2022-09-18 5:38 ` Eli Zaretskii
2022-09-18 10:49 ` Lars Ingebrigtsen
0 siblings, 2 replies; 9+ messages in thread
From: Drew Adams @ 2022-09-17 22:22 UTC (permalink / raw)
To: 57890
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-17 22:22 bug#57890: 28.1; Doc string of `initial-frame-alist' Drew Adams
@ 2022-09-18 5:38 ` Eli Zaretskii
2022-09-18 16:08 ` Drew Adams
2022-09-18 10:49 ` Lars Ingebrigtsen
1 sibling, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2022-09-18 5:38 UTC (permalink / raw)
To: Drew Adams; +Cc: 57890
> From: Drew Adams <drew.adams@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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-18 5:38 ` Eli Zaretskii
@ 2022-09-18 16:08 ` Drew Adams
2022-09-18 16:16 ` Eli Zaretskii
0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2022-09-18 16:08 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 57890@debbugs.gnu.org
> > 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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-18 16:08 ` Drew Adams
@ 2022-09-18 16:16 ` Eli Zaretskii
2022-09-18 17:05 ` Christopher Dimech
0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2022-09-18 16:16 UTC (permalink / raw)
To: Drew Adams; +Cc: 57890
> From: Drew Adams <drew.adams@oracle.com>
> CC: "57890@debbugs.gnu.org" <57890@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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-18 16:16 ` Eli Zaretskii
@ 2022-09-18 17:05 ` Christopher Dimech
0 siblings, 0 replies; 9+ messages in thread
From: Christopher Dimech @ 2022-09-18 17:05 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 57890, Drew Adams
> Sent: Monday, September 19, 2022 at 4:16 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Drew Adams" <drew.adams@oracle.com>
> Cc: 57890@debbugs.gnu.org
> Subject: bug#57890: 28.1; Doc string of `initial-frame-alist'
>
> > From: Drew Adams <drew.adams@oracle.com>
> > CC: "57890@debbugs.gnu.org" <57890@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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-17 22:22 bug#57890: 28.1; Doc string of `initial-frame-alist' Drew Adams
2022-09-18 5:38 ` Eli Zaretskii
@ 2022-09-18 10:49 ` Lars Ingebrigtsen
2022-09-18 11:11 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
1 sibling, 1 reply; 9+ messages in thread
From: Lars Ingebrigtsen @ 2022-09-18 10:49 UTC (permalink / raw)
To: Drew Adams; +Cc: 57890
Drew Adams <drew.adams@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?
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-18 10:49 ` Lars Ingebrigtsen
@ 2022-09-18 11:11 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-09-18 11:20 ` Lars Ingebrigtsen
0 siblings, 1 reply; 9+ messages in thread
From: Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-09-18 11:11 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 57890, Drew Adams
Lars Ingebrigtsen <larsi@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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-18 11:11 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
@ 2022-09-18 11:20 ` Lars Ingebrigtsen
2022-09-18 11:59 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 1 reply; 9+ messages in thread
From: Lars Ingebrigtsen @ 2022-09-18 11:20 UTC (permalink / raw)
To: Po Lu; +Cc: 57890, Drew Adams
Po Lu <luangruo@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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#57890: 28.1; Doc string of `initial-frame-alist'
2022-09-18 11:20 ` Lars Ingebrigtsen
@ 2022-09-18 11:59 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
0 siblings, 0 replies; 9+ messages in thread
From: Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors @ 2022-09-18 11:59 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: 57890, Drew Adams
Lars Ingebrigtsen <larsi@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.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2022-09-18 17:05 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-09-17 22:22 bug#57890: 28.1; Doc string of `initial-frame-alist' Drew Adams
2022-09-18 5:38 ` Eli Zaretskii
2022-09-18 16:08 ` Drew Adams
2022-09-18 16:16 ` Eli Zaretskii
2022-09-18 17:05 ` Christopher Dimech
2022-09-18 10:49 ` Lars Ingebrigtsen
2022-09-18 11:11 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-09-18 11:20 ` Lars Ingebrigtsen
2022-09-18 11:59 ` Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).