From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.devel Subject: Re: Documenting buffer display Date: Mon, 22 Oct 2018 11:06:07 +0200 Message-ID: <5BCD92FF.8070905@gmx.at> References: <5BCB1D82.3020108@gmx.at> <834ldgvjmj.fsf@gnu.org> <5BCB6DAE.30209@gmx.at> <83mur7tq4f.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1540199124 7112 195.159.176.226 (22 Oct 2018 09:05:24 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 22 Oct 2018 09:05:24 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 22 11:05:20 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gEW9H-0001iQ-1z for ged-emacs-devel@m.gmane.org; Mon, 22 Oct 2018 11:05:19 +0200 Original-Received: from localhost ([::1]:33655 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEWBN-0002r1-2U for ged-emacs-devel@m.gmane.org; Mon, 22 Oct 2018 05:07:29 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38314) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gEWAb-0002Vv-E4 for emacs-devel@gnu.org; Mon, 22 Oct 2018 05:06:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gEWAR-0002Jl-Ih for emacs-devel@gnu.org; Mon, 22 Oct 2018 05:06:40 -0400 Original-Received: from mout.gmx.net ([212.227.15.18]:60391) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gEWA9-0002Bh-Sz; Mon, 22 Oct 2018 05:06:14 -0400 Original-Received: from [192.168.1.101] ([213.162.73.34]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MVN0w-1g7Sur2Egg-00Yh0K; Mon, 22 Oct 2018 11:06:11 +0200 Original-Received: from [192.168.1.101] ([213.162.73.34]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MVN0w-1g7Sur2Egg-00Yh0K; Mon, 22 Oct 2018 11:06:11 +0200 In-Reply-To: <83mur7tq4f.fsf@gnu.org> X-Provags-ID: V03:K1:HDQBDhx4sYlyUvp7k1FLzRW88qAjmvw6xCmd72IxXiVm1mYWxZV +pI1njTx0nig5r2mSMfUOhxZb52hoFy9HQ+AGdX8wwPWz32uywjS23Fo0F4r2Bevy8B3U1b gIssk2abKP9PQTohZSop8cstkBm/572vIIrvFBdt6k8cTWgjZubEg6Ez84pasDdOUTdGSSz 1Ovk6TNlmiFKYfxF6Figg== X-UI-Out-Filterresults: notjunk:1;V01:K0:WntC6vmUlbQ=:NfuOfe9P2yTfkIS4QcPyRs 0H2FXgHRikGJLRZU5OUV52hg7G77ejRIMEgA9IAzRGMnR58CL2tp9HQcp4ZvwwDQtUh188I3E ZO0P+6m1h746iaSiAGLxAgR4FqwnDV1VYk8SLJ3XdGSHcuB7AthC4fkd56VBr4NCkAusVTGwf 03omAT8+5h1hZHFC5FcJF7qcrr6pdxy7+Gvueh2m0Wg9LG3dzg7DSIljjkQF2qOdNL1KCzAaJ bPSJ2gwGOyIvMMwMMxH8hNczPrNp6xNZAu8oMmmdk6MzrerbsjuMYoZyb4xorC3oCS0vvTxHy vW7ug7sLjsUp0tX6n2LdOLZ1V7hbRbakODSxR77aBvkpe5paqCUszV7Wwy6lYUvYJTy+5VN6q n16IJrwtHDh/wM+7LqenHbOYt0ebM2Mjb3Nxj9/CJFHjOnH+eNCxALCoP5DGcHD/+QEpto2Hs F9JgH/3pZQ078onk/uOhlDPEHhzhG3i7FnYpHceqZoXJjmzqD9ntK+OlFRXb9DXIIXd7VQ9bA 06o8hCci+UUKtyoFC9IwqHWuVXOscapbUY+sLNFmVVDue8kA4yL0rsLhkgFqBfMZIOGb0ONfJ 0W3I2rE7T92d5zKPZ3B/lV332CCFf4CCYNK3uEtkkcWwVvGXhnBHahMq5yE5ZhKPW3A04eYXD fT66RFp8z8R2Txp9H6cxPHzFbkG3BarxSG0AMD1yHN7dTkpKPjTkqAU91ZLbjGvXsmbfWDW0+ krho/B1NqLhqz9IV+3KCYeUD1m1uocSaEOdD6ihercZeTWcHOMf7QDEGaz6UxTKNtaK5G/2U X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.15.18 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:230552 Archived-At: > I'm not against tutorials; far from that. I just think they should be > separate from Reference manuals. Reference manuals can then point to > tutorials for examples. I could put the last two sections into the "Tips and Conventions" chapter. Or do we have another place where to put tutorial-like text? > But that doesn't mean a Reference manual can consider itself done by > providing a "lip service" in the form of such a tutorial reference. A > good Reference manual should still describe the feature in a clear and > useful way. My basic idea was to put the description proper into the first three, four sections and leave the last two, three sections to those puzzled by the technical level used in the decription. > Reference manual's main audience are people who already have some, > perhaps even good, idea about the feature, and need help in finding > exactly the right tools, out of those available, to do the jop at > hand. Tutorials, by contrast, target newbies who have no clue: > walking those through a large enough set of well-explained examples > will bring them up to speed, so they could proceed to the Reference > manual. That's why I chose the present style: The first three, four sections address the main audience, the people who search for the right tools. These sections try to be concise and use cross references to lead the reader right to the tool in question. The remaining sections are by design not intended for finding tools. People are supposed to read these sections when they are confused by the technicality of the previous sections. The examples are intentionally not concise - code like (display-buffer (get-buffer-create "*foo*") '((display-buffer-below-selected display-buffer-at-bottom))) has been written for being evaluated in place so to not confuse already confused people more by telling them how to create *foo* first. I repetitively employ calls of 'display-buffer' and 'customize-set-variable' to emphasize the distinction between how programmers are supposed to use actions and how users are supposed to customize them. So occasionally text in these sections is repetitive. But asking again: How else would you address a complaint like Telling someone that they must instead use `display-buffer' ACTION hoops to accomplish the same thing leads them down the garden path, on a wild goose chase, over the river & through the woods, and around Robin Hood's barn. IMO. if not with the help of an example where every single step can be executed right in place and the effect of that step seen right away? >> Readers in a hurry are not supposed to read that section. > > I think it's a mistake to take that stand when writing a Reference > manual. I disagree in this particular case. Readers in a hurry will have found the necessary information already in the preceding sections. If they didn't, we have to fix that in those sections. Only if they did but they are still uncertain about how to put their findings into practice they would go on with the remaining sections. > One thing to remember is that the manual is not the only place where > the documentation could live: there are doc strings as well. Some of > the details might be better suited to doc strings. Well, Alan's impression was that The doc string of display-buffer is a bit of a heavy read at this time of night. and I'm currently contemplating to remove the description of action alist entries from it. 'display-buffer' is a function that delegates its work to action functions (Drew's garden path) and guides the latter with the help of action alists which have now their separate entry in the Elisp manual. The "further down" in the garden path an information is found, the more Drew will complain. The "further up" everybody else will complain. A couple of weeks ago Drew complained that the doc-string of 'pop-to-buffer-same-window' misses any information about how it handles dedicated windows. So you amended the doc-string as follows: Unlike `pop-to-buffer', this function prefers using the selected window over popping up a new window or frame. Specifically, if the selected window is neither a minibuffer window (as reported by `window-minibuffer-p'), nor is dedicated to another buffer (see `window-dedicated-p'), BUFFER will be displayed in the currently selected window; otherwise it will be displayed in another window. While this would be appropriate for 'switch-to-buffer-other-window' it may be wrong for 'pop-to-buffer-same-window' as soon as the user has customized 'display-buffer-alist'. We can't avoid the garden path of 'display-buffer' here and elsewhere. > I didn't say those tips are useless, far from it. I just ended up > having an impression that I've read a list of tips that I will have to > re-read again when I need to find something in it. So I suggested to > think about some way of organizing them, so that similar and related > stuff is closer to one another. I see what you mean and it's obvious that the text I wrote takes the opposite direction. It tries to segregate the tips from the technical description rather than to combine them. The intention was that experienced readers should be allowed to read the technical sections without having to study the tips at the same time (or at all). Confused readers OTOH should be carefully guided to read on, as time permits. martin