bug#57890: 28.1; Doc string of `initial-frame-alist'

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Drew Adams]

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

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Eli Zaretskii]

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

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Lars Ingebrigtsen]

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?

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Lars Ingebrigtsen]

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.

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Drew Adams]

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

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Eli Zaretskii]

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

bug#57890: 28.1; Doc string of `initial-frame-alist'

[Christopher Dimech]

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