From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Christopher Dimech Newsgroups: gmane.emacs.bugs Subject: bug#57890: 28.1; Doc string of `initial-frame-alist' Date: Sun, 18 Sep 2022 19:05:02 +0200 Message-ID: References: <83o7vdz1gl.fsf@gnu.org> <834jx4zmih.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21671"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 57890@debbugs.gnu.org, Drew Adams To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Sep 18 19:06:20 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oZxkJ-0005Nm-4t for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 18 Sep 2022 19:06:19 +0200 Original-Received: from localhost ([::1]:50492 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oZxkH-00079e-P3 for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 18 Sep 2022 13:06:17 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52432) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oZxk2-00077D-Hw for bug-gnu-emacs@gnu.org; Sun, 18 Sep 2022 13:06:05 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52051) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oZxk2-0000z8-9p for bug-gnu-emacs@gnu.org; Sun, 18 Sep 2022 13:06:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oZxk1-0005wn-N6 for bug-gnu-emacs@gnu.org; Sun, 18 Sep 2022 13:06:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Christopher Dimech Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 18 Sep 2022 17:06:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 57890 X-GNU-PR-Package: emacs Original-Received: via spool by 57890-submit@debbugs.gnu.org id=B57890.166352071522802 (code B ref 57890); Sun, 18 Sep 2022 17:06:01 +0000 Original-Received: (at 57890) by debbugs.gnu.org; 18 Sep 2022 17:05:15 +0000 Original-Received: from localhost ([127.0.0.1]:51129 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oZxjH-0005vh-G1 for submit@debbugs.gnu.org; Sun, 18 Sep 2022 13:05:15 -0400 Original-Received: from mout.gmx.net ([212.227.17.21]:46945) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oZxjE-0005vO-PT for 57890@debbugs.gnu.org; Sun, 18 Sep 2022 13:05:14 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1663520702; bh=1NYu4rLGmyHWYzGuAWDb+U7Ji2hu3Xqu3H9ZqohlQJk=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:In-Reply-To:References; b=AKwMQx0a536TUcO4gFSUdPpU7FH1IX9fUul9k2S2Z0UYJIUT//cOCQjmusZ7cbgbq fcTLantyOiGJOJN0onLeENCmtJj8jNp4jIpLzysZLl/MM5Hh/lYLUklSVALED4zD4r MNeFcCiWa4dzT6TMbzt/z0myLFlezLZN4XpcbuGc= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from [92.251.127.164] ([92.251.127.164]) by web-mail.gmx.net (3c-app-mailcom-bs16.server.lan [172.19.170.184]) (via HTTP); Sun, 18 Sep 2022 19:05:02 +0200 Importance: normal Sensitivity: Normal In-Reply-To: <834jx4zmih.fsf@gnu.org> X-UI-Message-Type: mail X-Priority: 3 X-Provags-ID: V03:K1:qO8OaMnd6jPARduBi9QIndey96+GiiIFwMRA6ZTy5M3uBHtzfddnZOxblVF0rkcNyVVs3 XZJFCtckN1RZXSYNFwD6pkHnEopWorxV7G7dv9kbQo3bw3nV9wgbJiaaXPdJzh9f0cmJ5NlXwJ/8 lJBjxq/Zwle1XWkUsNSL3E691+J6E/5SO0E6D76KM2RgrgGjYBga4PoSjhTy1l0iQKFZ6ojep+2I AaQ/NFgoitUHK/TaLHCkefxTs3LI5IJLn6jwZ4xE0eRqtYAdzwjgV+AAXFUXjKr4kmh7yg5T5MPm rE= X-UI-Out-Filterresults: notjunk:1;V03:K0:lQ25iYmpNf4=:5sUaXNppGGu3EhRg3224w5 H4v49P3LEkON+t974dPzG539k/DV77305ajPPkIzJaiLpvPKygRmv3RCY0dKAnOM+6v5TiBcp 7RNqbV4sF9sElaQIXA3uMrLKIxMVwCO9R/O/saPUBhdbcd6r0X+zCUsHvdZ/UiYOuoQ7nf6wi wBNCBFSKVOpUV74+qChkAr4uqoOPE2Y7WWC16WQclgMCSDCFVi7YVqAXKO1SYk+c5sVDTFnd+ cw7aozn+znrxPzd43vOIwJEzHPFNxE43UrxyezTW3zuiVKJwg87BrJMzHnRlNtZjiSX3uLJi6 Xwezq3zeS1OwUKgklMT+mOP88jIEFoxsBJ+xs+IHRpqcjwIfdFVVHA1W/UG+tsCEvDeG/dJQv fE2tChMq92PKgJTmWEvrhLGH9wCk1TD14HR/nKyeo8DhFi//yHh3h192jeaZmOhTm7EWuVpHZ fQu9LzPjkvanutvWNASHM96OdCbhdauHxoltE0+iCvqVGbbflytkMB+4ujtZCyB7QEbEzI4iC dkiLuDQeR5OKKARuIqq6WW4LE3u8u7wFnB2UxPVyxhYTLvqzSlUse88R0pVWuk+cw38XT67g7 9dw+zm2oAJLL35xu6qJYigT64afVYefsbRmEKxVNpSPT3DZvjJC0iJzg8NFbERMYYu2ie6ut1 034I2JPmIrjXP1vCU8QdP004MF9CjNbGyh/A52R/01Igjj2PaQrHXcjIpGQxOZNP0rrFJmqSi j8OzhjyYpH60y/7KAztyabA/BGAnP89Ya8AmrcmneCsl5lAb7/1EknNUPjpChC1WxjYdpUIY X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:243005 Archived-At: > Sent: Monday, September 19, 2022 at 4:16 AM > From: "Eli Zaretskii" > To: "Drew Adams" > Cc: 57890@debbugs.gnu.org > Subject: bug#57890: 28.1; Doc string of `initial-frame-alist' > > > From: Drew Adams > > 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, someh= ow > > > > 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 introduction= s > > > and terminology explanations. They are succinct and assume some lev= el > > > 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 certai= nly 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 pra= gmatic. > > 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.