From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.devel Subject: Re: master 2a7488d: Add support for displaying short documentation for function groups Date: Sun, 11 Oct 2020 23:47:46 +0200 Message-ID: <87k0vwfn99.fsf@gnus.org> References: <20201011035127.7723.3256@vcs0.savannah.gnu.org> <20201011035128.E3FD320667@vcs0.savannah.gnu.org> <87k0vxquvo.fsf@gnus.org> <83o8l850v5.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="37021"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Oct 11 23:49:10 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 1kRjDK-0009Wr-4B for ged-emacs-devel@m.gmane-mx.org; Sun, 11 Oct 2020 23:49:10 +0200 Original-Received: from localhost ([::1]:42352 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kRjDJ-0004cG-70 for ged-emacs-devel@m.gmane-mx.org; Sun, 11 Oct 2020 17:49:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:40972) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kRjCJ-0004AO-Td for emacs-devel@gnu.org; Sun, 11 Oct 2020 17:48:07 -0400 Original-Received: from quimby.gnus.org ([2a01:4f9:2b:f0f::2]:38230) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kRjCH-0004Nv-No; Sun, 11 Oct 2020 17:48:07 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=kCgRf8GjEE5TBHBfoPWrUqGx5BVXEHdu/uCHNSswUaA=; b=BrAeINWOIObtMV4KzGDyr9AHF4 MjWgUCZk/uTGqAS8RlBMnSF+fp0zBKUR0Yv8ZSXyChVrjOoE0aGpRLJzfbAXKLxkT2hUfcllXwhpL mGOF1P/Rmt905sTuQa3dWCLBjIkvsOKsQb0+1hs0s46oCiAF7MBK26kyODSvuTkix0Js=; Original-Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=xo) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kRjC0-0000Tn-0I; Sun, 11 Oct 2020 23:48:00 +0200 Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAABGdBTUEAALGPC/xhBQAAACBj SFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAGFBMVEX7+vbb1s/Fvret opySg3yKdnFrWlX///+5nBMEAAAAAWJLR0QHFmGI6wAAAAd0SU1FB+QKCxUfJDcE50AAAAGYSURB VDjLxVNRktsgDJV7AsQJCnTyb4lcoNh7AawcYLP4/keowIQ4mdmZTn/67A9bTxJIegL4r7BoTn8T wmQmY/4x2d8ifEfQcbL3+AajD1ZC4Y73zA6i4cSAP+Nbwp0JemMa6RCCD1zR+Wp33jqnqaj7Wqxv c8e5E+QDUaih/ohmBn5Bu5nVeAf9gKOolsk7bUj/rk7VIa6iyFSp/iOyLXlJI6cDtTAvyypbStyJ eh1YF9niykuOaqi3ClQrI8jqtWlE5muikYkYUpQo+y5SpDAHppg0hn8Di/rue5E1R7kt23oV0YQE mkFupcWnj02NN5F6T0i3/Ql12UiP/pUIhrF8lY+9bInIaRvNkxD55NYZMERaebPloO2znrGJGXCq xF2rclZnYEO+/JwQ46GrWIh6IwNdZjNhVz/f3VMCAcdygJ1733W2niyObTlmbNvUXZ3fg7CzfRVV m50Sl/tDWZ1Q34zZah0PTbkeoEL/MWOt4yXVWJPrPZwJM5b3qc4jYmpBqLoi5rcdMLUuuJbXiLEG I9Pb5vwBnmqG4gFQXfsAAAAldEVYdGRhdGU6Y3JlYXRlADIwMjAtMTAtMTFUMjE6MzE6MzUrMDA6 MDDWWj81AAAAJXRFWHRkYXRlOm1vZGlmeQAyMDIwLTEwLTExVDIxOjMxOjM1KzAwOjAwpweHiQAA AABJRU5ErkJggg== X-Now-Playing: Static's _Eject Your Mind_: "Spawn" In-Reply-To: <83o8l850v5.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 11 Oct 2020 16:49:18 +0300") Received-SPF: pass client-ip=2a01:4f9:2b:f0f::2; envelope-from=larsi@gnus.org; helo=quimby.gnus.org X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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:257419 Archived-At: Eli Zaretskii writes: > 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? Yes, it's a bad name; I tried coming up with a better name over a month's time, but I just blanked. > 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?) Hm... function-overview? function-group-overview? And, yes, it should go in 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. I'm not sure the list will grow all that much, though. This stuff is primarily useful for function discovery, and that's mostly useful when talking about the "built-in", base functions, like the string/list/vector manipulation functions, and not something like, say, shr. The latter is best handled in a traditional manual. > 4) Invoking shortdoc-display-group with "file" as the group signals an > error. Looks like we lack some auto-loading machinery here. I'll have a look. > 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? I think the manual gives superior information in most cases, so I'd really like this to link to the manual and not the doc strings. This is also a way to guide users into the manual and read more in-depth about not just the functions described, but the machinery surrounding them, giving them more context. > 6) I question the particular faces used for the display. Do you > really find the gray background to be such a good idea? No. But I experimented with various ways of grouping, and I couldn't find anything that wouldn't just make everything look like... mush... and still be compact. Suggestions are very welcome. The problem is that the text is sparse, and it can be problematic seeing where the next function definition starts when you're skimming the list, and skimming is what it's all about. > 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? I don't envision that the list will increase greatly. Perhaps a couple more groups, but that's it. > 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. Yes, using the examples in the normal *Help* output would make sense. > 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. No, adding more text here would be counter-productive. I think that there's a substantial number of programmers that don't like reading words, but they love seeing examples. If they liked reading, they'd be reading the manual already. > 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. :eval is for side-effect-free forms, and the result shown is what they actually eval to. The rest are needed when we can't eval, but we still want to show an example of what form the result from the function would typically be on. But, yes, the :no-eval* bit could use some work. > 10) This should be documented in the user manual, as all other Help > commands. I'll add that. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no