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: Question on set-window-margins Date: Thu, 04 Jan 2024 14:52:17 +0200 Message-ID: <83ttntw9a6.fsf@gnu.org> References: <83il4bzgmk.fsf@gnu.org> <83h6jvyu9p.fsf@gnu.org> <5FC2FDA6-CB7F-4285-958E-EC8595FC66AE@gmail.com> <834jfuzhg1.fsf@gnu.org> <83r0iyxsym.fsf@gnu.org> 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="864"; mail-complaints-to="usenet@ciao.gmane.io" Cc: nicolas.rougier@inria.fr, casouri@gmail.com, emacs-devel@gnu.org To: John Yates Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Jan 04 13:53:18 2024 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 1rLNDp-000ATn-BE for ged-emacs-devel@m.gmane-mx.org; Thu, 04 Jan 2024 13:53:17 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rLNDC-0005AQ-WA; Thu, 04 Jan 2024 07:52:39 -0500 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 1rLND9-00059f-6j for emacs-devel@gnu.org; Thu, 04 Jan 2024 07:52:35 -0500 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 1rLND7-0000UQ-6w; Thu, 04 Jan 2024 07:52:33 -0500 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=Xgx/uvjnJtgrqzxtDY/vzh9oD1zvxOjzptYOu+wFapE=; b=FYDDkMEroNCoiLL6TY9N qR7MVpkm3isc2rHDe37rGvY5QtIC91NxgLehD0kSGxZAgkMhM/vpQwFo5Bw9P8RoQeYwNYZJGLWx+ kwrJfhjZOCpIu8KvxmhNtgga2tcz/khg5eusKSlY7gzCvYli4X9CnguG+IygbPNjXgNm0QpZZhWlt T3CJGxWyXg4wQm80SW6QV1hsf3ek17dLG/JHnnlMiLje3ueeHtLiC0P0yA6tSBXggZsRZjuU1JsKG QDMWcXSVOeAkJxU+XuhTF2yqk7FCG33qlzCr2VlhcctwlDAusj7ebQxCxK1J6V8668FvhIxiIq6vp O5Wosxar/QAL+w==; In-Reply-To: (message from John Yates on Thu, 4 Jan 2024 07:29:00 -0500) 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:314537 Archived-At: > From: John Yates > Date: Thu, 4 Jan 2024 07:29:00 -0500 > Cc: nicolas.rougier@inria.fr, casouri@gmail.com, emacs-devel@gnu.org > > On Wed, Jan 3, 2024 at 11:49 AM Eli Zaretskii wrote: > > > > We do that when there are too many details to have them in the doc > > string. Otherwise, there's no need for a link because typing 'i' in > > the *Help* buffer will show the corresponding documentation in the > > manual. > > A visual link has the virtue that it makes immediately clear case > holds. It is infeasible to maintain such a link in a doc string of every symbol which is described in the manual(s), and unreasonable to expect us to add a link to each doc string of such symbols. There are too many of them, and keeping the links up-to-date given the changes in the manuals is a lot of work. So we do that judiciously, where we think it's needed; a judgment call. > No link? Then the doc string is equivalent to what one > will find in the manual That's not that easy, in general, since the manuals include a lot of background explanations, cross-references to other related places, etc., which are not pertinent for doc strings, but are still useful in some, mostly rare, situations. In fact, this case in point is a small demonstration of that, as the caveat that was in the manual is not really directly related to the documentation of the function per se. Anyway, feel free to come on-board and start working on improving the documentation, including, but not limited to, this aspect. Me, I just got up from adding a decent documentation to help-quick command, which originally said just this: Display a quick-help buffer. And believe me, this is not a solitary example. So please forgive me if, with such inadequacy in mind, I consider the hair-splitting arguments of this discussion not my first priority, not even the second.