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

[Eli Zaretskii <eliz@gnu.org>]

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