From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: icon-title-format vs. frame-title-format (Bug#61496) Date: Fri, 05 May 2023 14:00:11 +0300 Message-ID: <83pm7fhwlg.fsf@gnu.org> References: <4920048a-aded-3588-50d2-4bea3c0c096b@web.de> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="7960"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Tobias Bading Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri May 05 13:00:06 2023 Return-path: Envelope-to: ged-emacs-devel@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 1putAU-0001tP-4p for ged-emacs-devel@m.gmane-mx.org; Fri, 05 May 2023 13:00:06 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1put9m-0000KL-3e; Fri, 05 May 2023 06:59:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1put9k-0000Jz-I8 for emacs-devel@gnu.org; Fri, 05 May 2023 06:59:20 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1put9j-0004Cx-Il; Fri, 05 May 2023 06:59:20 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=FJJqriAfDp0plh7ZJ4fWz4ZlvifVh7UqF3Om5o5vmc0=; b=jMUbqm4MzjCH6QV3riD/ KnENqK3oReo/WaZp0eXyTG+mHczCr1QSFTUCuRU0TDkemjcycFmidHp8CeJN0XBDCXhuSIwM3iSVk iNXpnMyKcnIoJ0hQAvz8azQMqQcSJmrCwzUTNuI2+FJjyK0zsDw99wvHJe5PDDSejzqhHMyEadjYA l1zsgPA1LVzOoRevXtmms6rA4rxPb8LydRpghvXAtTtaD/Wg1KRl7TJ+yn9ZBjDLSBm3GwOY3oDGW GrvktZ7Lk5QxFlxBQwnN4PxZEXVa69YcGf+N2HpxdI83WWce2f79y3k8F96E+VK7nY75tzjqyKGhD oEgBpD/h2Owtzw==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1put9j-0000F1-2R; Fri, 05 May 2023 06:59:19 -0400 In-Reply-To: <4920048a-aded-3588-50d2-4bea3c0c096b@web.de> (message from Tobias Bading on Fri, 5 May 2023 12:40:37 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:305870 Archived-At: > Date: Fri, 5 May 2023 12:40:37 +0200 > From: Tobias Bading > > Oh god, what have I done? XD > [...] > What were we talking about again? > Right, that frame-title-format doc string… XD > I didn’t intend to start a mega-thread about terminology. If Emacs doc > strings had see-also sections I would have simply asked to please put a > “See also: icon-title-format” into frame-title-format’s doc string. > I’m happy with the added (setq icon-title-format t) in my ~/.emacs, which > made Emacs 29 behave like Emacs 26.3. I just thought a little hint in the > doc string might help other people who upgrade their Emacs like me and > wonder about those changing window titles. Something to consider when you post a message about some minor (in this case, really minuscule) issue. There's a lesson to be learned here, I think. Bottom line: from my POV, there's nothing wrong with our doc strings. icon-title-format has a reference to frame-title-format, and there's a reason for that. There's no reason for the reverse reference, so we don't have it. Blindly adding a "see also" for every possible subject under the sun is not something we do, and should not do. References should be instrumental, focused, and to the point, otherwise they are just a distraction and a cause for user frustration. The manual, OTOH, shows a broader picture, and thus describes both of them, and provides some context which allows the reader to understand the logic behind having both. The right way of using the Emacs documentation is to start with doc strings (perhaps via apropos commands), then look in the manual if the issue is still not clear or if there's a need for deeper, more comprehensive understanding of the issue and its aspects. Expecting the doc strings to answer all the questions and include all the references to all the possible tangents is impractical.