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: master 2a7488d: Add support for displaying short documentation for function groups Date: Sun, 11 Oct 2020 16:49:18 +0300 Message-ID: <83o8l850v5.fsf@gnu.org> References: <20201011035127.7723.3256@vcs0.savannah.gnu.org> <20201011035128.E3FD320667@vcs0.savannah.gnu.org> <87k0vxquvo.fsf@gnus.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="19059"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Lars Ingebrigtsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Oct 11 15:55:24 2020 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 1kRbop-0004rs-U6 for ged-emacs-devel@m.gmane-mx.org; Sun, 11 Oct 2020 15:55:23 +0200 Original-Received: from localhost ([::1]:60906 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kRboo-0002cf-UV for ged-emacs-devel@m.gmane-mx.org; Sun, 11 Oct 2020 09:55:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41786) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kRbiu-0005Sk-Gr for emacs-devel@gnu.org; Sun, 11 Oct 2020 09:49:16 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:52306) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kRbiu-0001Dx-3J; Sun, 11 Oct 2020 09:49:16 -0400 Original-Received: from [176.228.60.248] (port=4830 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kRbit-0002q2-D8; Sun, 11 Oct 2020 09:49:15 -0400 In-Reply-To: <87k0vxquvo.fsf@gnus.org> (message from Lars Ingebrigtsen on Sun, 11 Oct 2020 05:55:23 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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" Xref: news.gmane.io gmane.emacs.devel:257362 Archived-At: > From: Lars Ingebrigtsen > Date: Sun, 11 Oct 2020 05:55:23 +0200 > > After tinkering with this for a while on a branch, I've now merged the > shortdoc stuff into the trunk. Thanks. I think this is a very useful documentation feature. Some comments and thoughts: 1) Is "shortdoc" the best name for this? This is not really some short form of existing documentation, it is something else. Unless we plan to add more similar features, how about "help-func-groups" or "help-func-summaries" instead? 2) A better name for the shortdoc-display-group command would be something like describe-function-group or somesuch -- this is basically a help command. (And how about adding it to the Help menu?) 3) An apropos-style command regarding the known groups should probably be added. As long as the list of the groups is short, just C-h (which already works) is enough, but that will become inconvenient as the list grows, I think. 4) Invoking shortdoc-display-group with "file" as the group signals an error. Looks like we lack some auto-loading machinery here. 5) Pushing the button with a function name in the group display pops up the ELisp manual. I wonder whether this is a good idea: why not show the full doc string of the function instead? Come think about it, why not _insert_ the full doc string right after the function's signature, in the same buffer, instead of popping up a new buffer? 6) I question the particular faces used for the display. Do you really find the gray background to be such a good idea? 7) Loading the entire database of all the groups at once sounds un-economical, especially if we envision that the groups will grow and their number will increase. Should we perhaps have a separate DB file for each group? 8) The information stored in the group consists of 2 separate parts: . the functions that belong to a group . the examples of using each function These 2 are not necessarily tightly coupled, and the examples are useful on their own right. For example, should we perhaps make the examples of using a particular function accessible from the *Help* buffer that describes that function? The "group" button is not an efficient way of seeing those examples because it shows the entire group, not the function from which we started. Also, how about some facility to add a description or explanation of what each example does? It's IME sub-optimal to expect the reader to glean that on his/her own just by looking at the call and the result, especially when there are several non-trivial arguments. 9) Do we really need all the type keywords (:eval, :eg-result, etc.)? I'm not sure I understand why not just evaluate the example and produce the result automatically, without all those different types? E.g., it sounds artificial to me to use :no-eval* to get "[it depends]", instead of just saying "[it depends]" explicitly. 10) This should be documented in the user manual, as all other Help commands.